Skip to content

08.01-initialization.md

Latest commit

 

History

History
202 lines (121 loc) · 14.7 KB

08.01-initialization.md

File metadata and controls

202 lines (121 loc) · 14.7 KB
Raw

8.1. Initialization

After Studio loads bambu_networking and passes the version / signature gates (§5), it creates an opaque agent and drives a fixed setup sequence before any printer or cloud traffic is allowed. Typedefs for these entry points live in NetworkAgent.hpp; Studio resolves them via dlsym / GetProcAddress as bambu_network_* in NetworkAgent::initialize_network_module. The post-create_agent calls sit in GUI_App::on_init_network; SSDP discovery starts later (§8.4).

Symbol Signature
bambu_network_check_debug_consistent bool(bool is_debug)
bambu_network_get_version std::string(void)
bambu_network_create_agent void*(std::string log_dir)
bambu_network_destroy_agent int(void* agent)
bambu_network_set_config_dir int(void* agent, std::string config_dir)
bambu_network_init_log int(void* agent)
bambu_network_set_cert_file int(void* agent, std::string folder, std::string filename)
bambu_network_set_country_code int(void* agent, std::string country_code)
bambu_network_start int(void* agent)

Neighboring steps in the same bring-up path — documented elsewhere: bambu_network_set_extra_http_header (§8.10), the set_on_*_fn battery (§8.2), bambu_network_start_discovery (§8.4.2).

8.1.1. Common contract / sequence

Return convention. Most of these entry points return int: 0 on success, or a BAMBU_NETWORK_ERR_* code (§8.16) — typically BAMBU_NETWORK_ERR_INVALID_HANDLE when agent is null / unknown. check_debug_consistent returns bool; get_version returns std::string. Evidence: Studio wrappers in NetworkAgent.cpp.

Cold-boot has four phases. The plugin must tolerate this exact order; in particular, no networking work before start(), and discovery is a separate later step — not part of on_init_network.

  1. Load / version gate (before any agent exists). Studio dlopens the module, then GUI_App::check_networking_version → NetworkAgent::get_version, which calls check_debug_consistent then get_version. First 8 characters of the version string must match SLIC3R_VERSION (§5).

  2. Post-create_agent in on_init_network (GUI_App.cpp:3677-3729):

    1. create_agent(data_dir()) via new NetworkAgent(...)
    2. set_config_dir(data_dir())
    3. init_log()
    4. set_cert_file(resources_dir()+"/cert", "slicer_base64.cer")
    5. init_http_extra_header() → set_extra_http_header(...) (§8.10)
    6. init_networking_callbacks() → most set_on_*_fn setters (§8.2.1; SSDP / HTTP-error are not here)
    7. set_country_code(app_config->get_country_code())
    8. start()

  3. After init — discovery. GUI_App::post_init (and restart_networking) (re)install set_on_ssdp_msg_fn / set_on_http_error_fn (§8.2.3, §8.2.4), then start_discovery(true, false). Details: §8.4.2, §6.1.

  4. Teardown. On Windows, GUI_App::OnExit stops discovery with start_discovery(false, false) then delete m_agent, which invokes ~NetworkAgent → destroy_agent.

8.1.2. bambu_network_check_debug_consistent

Parameters.

Name Type Meaning
is_debug bool Studio build flavor: true if Studio is debug, else false.

Purpose. Reject a plugin built with the wrong debug/release flavor relative to Studio.

Studio. Invoked from NetworkAgent::get_version before get_version: under NDEBUG Studio passes is_debug=false, otherwise true. If the call returns false, Studio never reads the real version string and substitutes "00.00.00.00", which fails the 8-character gate.

Plugin behaviour. Return true only when the plugin's build flavor matches is_debug. A release plugin asked is_debug=true (or vice versa) must return false.

Return. bool — no BAMBU_NETWORK_ERR_*.

8.1.3. bambu_network_get_version

Parameters.

Name Type Meaning
— — No parameters.

Purpose. Report the plugin version so Studio can enforce ABI compatibility.

Studio. check_networking_version compares network_ver.substr(0,8) with SLIC3R_VERSION.substr(0,8). Mismatch → m_networking_compatible = false and no agent is created (backup DLL path may retry). Full gate story: §5.

Plugin behaviour. Return a string of the form NN.NN.NN.NN (optional build suffix after the first 8 characters is ignored by Studio). The first 8 characters must equal the Studio build's SLIC3R_VERSION prefix.

Return. std::string. On missing symbol / debug mismatch Studio already maps to "00.00.00.00" in its wrapper — the plugin itself should still return a real version when called.

8.1.4. bambu_network_create_agent

Parameters.

Name Type Meaning
log_dir std::string Studio data_dir(); directory for plugin logs.

Purpose. Allocate the opaque agent that every subsequent bambu_network_* call takes as void* agent.

Studio. on_init_network does new NetworkAgent(data_dir()); the ctor calls create_agent_ptr(log_dir) (NetworkAgent.cpp:143-147). log_dir is Studio's data_dir() — the same path later passed to set_config_dir.

Plugin behaviour. Create and return a non-null opaque handle. Treat log_dir as the directory for plugin logs (and any early filesystem setup that must precede init_log). Do not start cloud / printer I/O here.

Return. void* agent handle, or nullptr on failure (Studio then treats the agent as unusable).

8.1.5. bambu_network_destroy_agent

Parameters.

Name Type Meaning
agent void* Opaque agent from create_agent.

Purpose. Tear down the agent and release resources.

Studio. Not called from on_init_network. Invoked from ~NetworkAgent when Studio deletes m_agent in OnExit (Windows stops discovery first). Failed load paths that never created an agent only unload_network_module().

Plugin behaviour. Shut down workers, close sockets, free the handle. After return, Studio must not call any other agent method on that pointer.

Return. 0 on success; non-zero BAMBU_NETWORK_ERR_* on failure.

8.1.6. bambu_network_set_config_dir

Parameters.

Name Type Meaning
agent void* Opaque agent from create_agent.
config_dir std::string Studio data_dir(); root for plugin config / auth / TLS state.

Purpose. Tell the agent where Studio keeps user data / config.

Studio. Immediately after create_agent, with the same data_directory (GUI_App.cpp:3705-3708).

Plugin behaviour. Store config_dir as the root for plugin-owned config / auth / TLS state that belongs under Studio's data directory. Ordering relative to init_log / set_cert_file must be tolerated as Studio emits it.

Return. 0 on success; non-zero on invalid handle / failure.

8.1.7. bambu_network_init_log

Parameters.

Name Type Meaning
agent void* Opaque agent from create_agent.

Purpose. Initialize (or finish initializing) the plugin's internal logging.

Studio. Right after set_config_dir (GUI_App.cpp:3709-3712).

Plugin behaviour. Ensure logging is ready, using log_dir from create_agent and/or config_dir as appropriate. A no-op is acceptable if logging was already set up in create_agent, but the call must still succeed.

Return. 0 on success; non-zero on failure.

8.1.8. bambu_network_set_cert_file

Parameters.

Name Type Meaning
agent void* Opaque agent from create_agent.
folder std::string Certificate directory under Studio resources (e.g. …/cert).
filename std::string Primary cloud trust file name (Studio passes slicer_base64.cer).

Purpose. Point the agent at Studio's certificate directory and the primary cloud trust file name.

Studio. on_init_network always passes resources_dir()+"/cert" and "slicer_base64.cer".

Studio ships two PEM files under <resources>/cert/:

File Role
slicer_base64.cer Named in the ABI call; BBL / RapidSSL-style bundle for cloud hostnames.
printer.cer BBL CA bundle (root + intermediates). Not the printer device leaf. Observed Studio v02.07 bundles do not include per-model device issuers such as BBL Device CA N7-V2.

Plugin behaviour. Accept (folder, filename) and use them for TLS trust as needed for cloud HTTPS. printer.cer lives in the same folder even though Studio never names it in this call. Printer-side observations (leaf CN=<serial>, missing issuer in printer.cer): §10.6.

Return. 0 on success; non-zero on failure.

TODO: need capture / stock observation of how the closed plugin applies printer.cer vs slicer_base64.cer on LAN MQTT TLS (beyond §10.6 leaf notes).

8.1.9. bambu_network_set_country_code

Parameters.

Name Type Meaning
agent void* Opaque agent from create_agent.
country_code std::string Regional site code from app_config (e.g. US, CN).

Purpose. Set the regional country / site code that selects cloud hosts and related region behaviour.

Studio. After callbacks, with app_config->get_country_code() (GUI_App.cpp:3722-3723) — values such as "US", "CN", ….

Plugin behaviour. Store the code and use it when resolving regional API / MQTT hosts (§6.6). Do not require a network round-trip inside this call.

Return. 0 on success; non-zero on failure.

8.1.10. bambu_network_start

Parameters.

Name Type Meaning
agent void* Opaque agent from create_agent.

Purpose. Start the agent's event loop / worker threads and mark the boundary after which networking is allowed.

Studio. Last ABI call in the successful on_init_network path (GUI_App.cpp:3724; wrapper NetworkAgent.cpp:667-676). SSDP discovery is not started here — see §8.1.1 phase 3.

Plugin behaviour. Bring up internal workers / event loop. Before this call returns successfully, the plugin must not open cloud or printer connections on its own initiative. After start(), later ABI calls (connect_server, connect_printer, HTTP helpers, …) and callbacks may proceed; discovery still waits for an explicit start_discovery.

Return. 0 on success; non-zero on failure.

Hub: §8.