{{{ #!comment I tried adding [[PageOutline]] too but it seemed too long, and breaking the page layout. }}} = Controlling the core client via RPC = The BOINC core client provides a set of RPCs (remote procedure calls) for control and state interrogation. This enables the development of GUI (graphical user interface) programs separately from the core client. These RPCs send XML request and reply messages over a TCP connection. The XML formats are not documented, but can be deduced from the source code. BOINC provides a C++ interface to these RPCs, consisting of the GUI_RPC class. The interface is in [source:trunk/boinc/lib/gui_rpc_client.h lib/gui_rpc_client.h], and the program [source:trunk/boinc/client/boinc_cmd.cpp boinc_cmd.cpp] gives a usage example. All member functions return an integer error code. It should be fairly easy to generate client interfaces in languages other than C++. GUI programs connect to the core client by opening a TCP socket at port 31416. They can then do repeated RPCs over this connection. Each reply message ends with the character \003. To create an RPC connection, call === `init(char* host)` === #function-init Establish RPC connection to the given host. == Dealing with versions == The GUI RPC protocol changes over time. If you're writing a GUI program that needs to communicate with older versions of the BOINC core client, here's what to do: * Create a `GUI_RPC` object and connect. Call [#function-exchange_versions exchange_versions()] to get the client version. * If [#function-exchange_versions exchange_versions()] fails (it's not supported in pre-5.6 clients) do a [#function-get_state get_state()] RPC, and get the client version from `CC_STATE::version_info`. * Use the client version number to decide what subsequent RPCs to make (version info is included in the RPC list below). {{{ #!comment Most RPCs on the list *lack* version information saying since when they're available. }}} == Authorization == The RPC protocol allows the GUI program to authenticate itself using a password. Some of the RPC operations can be done without authentication; others can be done without authentication, but only by a GUI program running on the same machine. === `authorize(char* password)` === #function-authorize Do authorization sequence with the peer, using given password. == RPC list == The following functions require authorization for remote clients, but not for local clients. Note: for core client versions 5.5.12 and earlier, all functions except [#function-get_state get_state()], [#function-get_results get_results()], [#function-get_screensaver_mode get_screensaver_mode()], and [#function-set_screensaver_mode set_screensaver_mode()] require authorization. {{{ #!comment A few function headers like set_screensaver_mode, project_attach and acct_mgr_rpc have the `monospaced` parts broken that way to allow word wrap. }}} === `get_state(CC_STATE&)` === #function-get_state Get the core client's 'static' state, i.e. its projects, apps, app_versions, workunits and results. This call is relatively slow and should only be done initially, and when needed later (see below). === `exchange_versions(VERSION_INFO&)` === #function-exchange_versions Exchange version info with the core client. The core client's version info is returned. === `get_cc_status(CC_STATUS&)` === #function-get_cc_status {{{ struct CC_STATUS { int network_status; bool ams_password_error; int task_suspend_reason; int network_suspend_reason; int task_mode; int network_mode; int task_mode_perm; int network_mode_perm; double task_mode_delay; double network_mode_delay; bool disallow_attach; bool simple_gui_only; }; }}} Return a structure containing the network status, a flag if there was an account manager password error, and data about task and network suspension. === `get_results(RESULTS&)` === #function-get_results Get a list of [JobIn results]. Those that are in progress will have information such as CPU time and fraction done. Each result includes a name; use `CC_STATE::lookup_result()` to find this result in the current static state; if it's not there, call [#function-get_state get_state()] again. === `get_screensaver_mode(int& status)` === #function-get_screensaver_mode Return screensaver mode (values are listed in [source:trunk/boinc/lib/common_defs.h common_defs.h]). === `set_screensaver_mode``(bool enabled, ``double blank_time, ``DISPLAY_INFO&)` === #function-set_screensaver_mode If `enabled` is `true`, the core client should try to get an application to provide screensaver graphics. Blank screen after `blank_time` seconds. === `get_file_transfers(FILE_TRANSFERS&)` === #function-get_file_transfers Get a list of file transfers in progress. Each is linked by name to a project; use `CC_STATE::lookup_project()` to find this project in the current state; if it's not there, call [#function-get_state get_state()] again. === `get_simple_gui_info(SIMPLE_GUI_INFO&)` === #function-get_simple_gui_info Return the list of projects and of active results. === `get_project_status(vector&)` === #function-get_project_status Get a list of projects, with only basic fields filled in. === `get_disk_usage(vector&)` === #function-get_disk_usage Get a list of projects, with disk usage fields filled in. === `get_proxy_settings(PROXY_INFO&)` === #function-get_proxy_settings Get proxy settings. === `get_activity_state(ACTIVITY_STATE&)` === #function-get_activity_state Return bitmap of reasons why computation and network are suspended. '''Deprecated''' - for 5.5.13 and later, use [#function-cc_status cc_status()] instead. In 5.5.10 and earlier, it returns a `bool` (suspended) rather than bitmap. === `get_messages(int seqno, MESSAGES&)` === #function-get_messages Returns a list of messages to be displayed to the user. Each message has a sequence number (1, 2, ...), a priority (1=informational, 2=error) and a timestamp. The RPC requests the messages with sequence numbers greater than `seqno`, in order of increasing sequence number. === `get_message_count(int& seqno)` === #function-get_message_seqno Return the greatest message sequence number. === `get_host_info(HOST_INFO&)` === #function-get_host_info Get information about host hardware and usage. === `get_statistics(PROJECTS&)` === #function-get_statistics Get information about project credit history (the `PROJECT::statistics` field is populated). === `network_status(int&)` === #function-network_status Find whether the core client has, needs, or is done with a physical network connection. Deprecated - for 5.5.13 and later, use [#function-cc_status cc_status()] instead. === `get_newer_versions(std::string&)` === #function-get_newer_versions Get a string describing newer versions of the core client, if any. ---- The following operations require authentication for both local and remote clients: === `show_graphics(char* result_name, bool full_screen)` === #function-show_graphics Request that the application processing the given result create a graphics window. === `project_op(PROJECT&, char* op)` === #function-project_op Perform a control operation on the given project (only the `master_url` field needs to be set). `op` is one of "suspend", "resume", "reset", "detach", "update", "allowmorework", "nomorework". Since 5.10.14: "detach_when_done", "dont_detach_when_done". === `project_attach(``char* url, ``char* account_key, ``char* project_name)` === #function-project_attach Attach to the given project. === `set_run_mode(int mode, double duration)` === #function-set_run_mode Set the run mode (never/auto/always). If duration is zero, mode is permanent. Otherwise revert to last permanent mode after duration seconds elapse. === `set_network_mode(int mode, double duration)` === #function-set_network_mode Set the network mode (never/auto/always). === `run_benchmarks()` === #function-run_benchmarks Run benchmarks. === `set_proxy_settings(PROXY_INFO&)` === #function-set_proxy_settings Set proxy settings. === `network_available()` === #function-network_available Tells the core client that a network connection is available, and that it should do as much network activity as it can. === `file_transfer_op(FILE_TRANSFER&, const char* op)` === #function-file_transfer_op Perform a control operation on a file transfer. `op` is one of "abort" or "retry". === `result_op(RESULT&, const char* op)` === #function-result_op Perform a control operation on an active result. `op` is one of "suspend", "resume", or "abort". === `quit()` === #function-quit Tell the core client to exit. === `acct_mgr_rpc(``const char* url, ``const char* name, ``const char* passwd, ``bool use_config_file)` === #function-acct_mgr_rpc Do an Account Manager RPC to the given URL, passing the given name/password. If `use_config_file` is true, then the existing URL, username, and password are used and the core client updates the project information from the account manager. If the RPC is successful, save the account info on disk (it can be retrieved later using [#function-acct_mgr_info acct_mgr_info()]). If `url` is the empty string, remove account manager info from disk. === `acct_mgr_info(ACCT_MGR_INFO&)` === #function-acct_mgr_info Return the URL/name of the current account manager (if any), and the user name and password. === `read_global_prefs_override()` === #function-read_global_prefs_override Tells the core client to reread the [PrefsOverride global_prefs_override.xml] file, modifying the global preferences according to its contents. === `get_global_prefs_override(std::string&)` === #function-get_global_prefs_override Reads the contents of the global [PrefsOverride preferences override] file into the given string. Return an error code if the file is not present. === `set_global_prefs_override(std::string&)` === #function-set_global_prefs_override Write the given contents to the global preferences override file. If the argument is an empty string, delete the file. Otherwise the argument must be a valid `` element. === `get_global_prefs_override_struct(GLOBAL_PREFS&)` === #function-get_global_prefs_override_struct Return the contents of the global preferences override file, parsed into a structure. Default values are zero. Returns an error code if the file is not present. === `set_global_prefs_override_struct(GLOBAL_PREFS&)` === #function-set_global_prefs_override_struct Convert the given structure to XML and write it to the global [PrefsOverride preferences override] file. To modify a particular preference (e.g., CPU throttle): {{{ GLOBAL_PREFS prefs; GLOBAL_PREFS_MASK prefs_mask; RPC_CLIENT rpc; char password[256]; read_gui_rpc_password(password); rpc.init("localhost"); rpc.authorize(password); rpc.get_global_prefs_override_struct(prefs, prefs_mask); prefs.cpu_usage_limit = 0.5; prefs_mask.cpu_usage_limit = true; rpc.set_global_prefs_override_struct(prefs, prefs_mask); rpc.read_global_prefs_override(); }}} === `set_debts(std::vector)` === #function-set_debts Set the short- and long-term debts of the given projects (only the `master_url`, `short_term_debt`, and `long_term_debt` fields are used in the `PROJECT` structs). [[T(VersionNew|5.10.11)]]