[[PageOutline]] = Controlling the BOINC client via RPC = The BOINC client provides a set of RPCs (remote procedure calls) for control and state interrogation. This enables the development of GUI (graphical user interface) programs. These RPCs send XML request and reply messages over a TCP connection. The XML formats are documented in GuiRpcProtocol. The following bindings are available: * BOINC has a C++ binding, consisting of the RPC_CLIENT class. The interface is in [https://github.com/BOINC/boinc/blob/master/lib/gui_rpc_client.h lib/gui_rpc_client.h], and the program [https://github.com/BOINC/boinc/blob/master/client/boinc_cmd.cpp boinc_cmd.cpp] gives a usage example. * Another C++ binding is part of [https://github.com/suleman1971/boinctui boinctui]. * A Java binding: [https://github.com/BOINC/boinc/tree/master/android/BOINC/src/edu/berkeley/boinc/rpc]. * A .Net binding: https://github.com/chausner/BoincRpc * An older .Net binding: https://boincguirpc.codeplex.com/ * A Python binding: https://github.com/MestreLion/boinc-indicator It should be easy to generate bindings in other languages. GUI programs connect to the 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. The rest of this document describes the C++ interface. The functions listed are members of the '''RPC_CLIENT''' class. All member functions return an integer error code. == Connecting == To establish an RPC connection to a host: {{{ RPC_CLIENT rpc; rpc.init(char* 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 client: {{{ exchange_versions("your program name", VERSION_INFO& v)); }}} The client's version is returned in v. Use the client version number to decide what subsequent RPCs to make (some version info is included in the RPC list below). == Authorization == The RPC protocol allows the GUI program to authenticate itself using a [https://boinc.berkeley.edu/wiki/Controlling_BOINC_remotely 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. {{{ retval = rpc.authorize(char* password) }}} Authorize with the peer, using given password. == RPC list == The following functions require authorization for remote clients, but not for local clients. {{{ #!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_cc_status(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_daily_xfer_history(DAILY_XFER_HISTORY&)`:: Get a daily history of number of bytes uploaded and downloaded. Implemented in 6.13.7+ clients. `get_disk_usage(vector&)`:: Get a list of projects, with disk usage fields filled in. `get_file_transfers(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_host_info(HOST_INFO&)`:: Get information about host hardware and usage. `get_messages(int seqno, MESSAGES&, bool translatable=false)`:: 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. If '''translatable''' is true, messages from 6.11+ clients may include translatable parts. These parts are enclosed in '''_("...")'''. They should be translated according to the translation files in boinc/locale/*/BOINC-Client.po `get_message_count(int& seqno)`:: Return the greatest message sequence number. Implemented in 6.10+ client version. `get_newer_versions(string& version, string& url)`:: Get strings describing newer versions of the client, if any. `get_notices(int seqno, NOTICES& notices)`:: Returns a list of notices with sequence number greater than seqno. Notices are returned in order of increasing sequence number (which is the same as increasing arrival time). Unlike messages, notices can be removed. In this case, notices.complete is set to true, and notices.notices contains all notices. Otherwise notices.notices contains only new notices. Implemented in 6.11+ client version. `get_project_status(vector&)`:: Get a list of projects, with only basic fields filled in. `get_proxy_settings(PROXY_INFO&)`:: Get proxy settings. `get_results(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_old_results(vector)`:: Get a list of results that have been completed in the last hour and have been reported to their project. (These results are not returned by [#function-get_results get_results()]). `get_screensaver_mode(int& status)`:: Return screensaver mode (values are listed in [source:boinc/lib/common_defs.h common_defs.h]). `get_simple_gui_info(SIMPLE_GUI_INFO&)`:: Return the list of projects and of active results. `get_state(CC_STATE&)`:: Get the 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). `get_statistics(PROJECTS&)`:: Get information about project credit history (the `PROJECT::statistics` field is populated). `set_screensaver_mode``(bool enabled, ``double blank_time, ``DISPLAY_INFO&)`:: If `enabled` is `true`, the client should try to get an application to provide screensaver graphics. Blank screen after `blank_time` seconds. ---- The following operations require authentication for both local and remote clients: `acct_mgr_info(ACCT_MGR_INFO&)`:: Return the URL/name of the current account manager (if any), and the user name and password. `acct_mgr_rpc(``const char* url, ``const char* name, ``const char* passwd, ``bool use_config_file)`:: 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 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. `file_transfer_op(FILE_TRANSFER&, const char* op)`:: Perform a control operation on a file transfer. `op` is one of "abort" or "retry". `get_global_prefs_override(string&)`:: Reads the contents of the global [PrefsOverride preferences override] file into the given string. Return an error code if the file is not present. `get_global_prefs_override_struct(GLOBAL_PREFS&)`:: 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. `network_available()`:: Tells the client that a network connection is available, and that it should do as much network activity as it can. `project_attach(``char* url, ``char* account_key, ``char* project_name)`:: Attach to the given project. `project_op(PROJECT&, char* 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". `quit()`:: Tell the client to exit. `read_global_prefs_override()`:: Tells the client to reread the [PrefsOverride global_prefs_override.xml] file, modifying the global preferences according to its contents. `report_device_status(DEVICE_STATUS&)`:: Report power, battery, and WiFi status to the client. This is used on Android, where the interfaces for this info are in Java and therefore easier to access from the GUI than from the client. `reset_host_info()`:: Tell the client to get host parameters (RAM and disk sizes, #CPUs) again. Do this if you're running the client in a container, and you change the parameters of the container. `result_op(RESULT&, const char* op)`:: Perform a control operation on an active result. `op` is one of "suspend", "resume", or "abort". `run_benchmarks()`:: Run benchmarks. `set_global_prefs_override(string&)`:: 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. `set_global_prefs_override_struct(GLOBAL_PREFS&)`:: 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_network_mode(int mode, double duration)`:: Set the network mode (never/auto/always). `set_proxy_settings(PROXY_INFO&)`:: Set proxy settings. `set_run_mode(int mode, double duration)`:: Set the run mode (never/auto/always). If duration is zero, mode is permanent. Otherwise revert to last permanent mode after duration seconds elapse. == Android-specific RPCs == The RPC {{{ int report_device_status(DEVICE_STATUS&); }}} is used to convey information from Android GUIs to the BOINC client, including * whether the device is plugged in via USB or AC power * the battery charge level, state, and temperature * whether the device is connected via !WiFi * whether the user is active (e.g. whether the screen is on) * the device name (supplied by the user) This RPC also serves as a "keep-alive": if the BOINC client doesn't get one in 30 seconds, it will suspend computation. So Android GUIs should call it fairly often (every 10 sec at least). There is no C++ binding for this RPC; there's a Java binding in the Android GUI code: android/BOINC/src/edu/berkeley/boinc/rpc/RpcClient.java