From 3c924adbd9141ad21cf6471a405c34cdc8750509 Mon Sep 17 00:00:00 2001 From: Vitalii Koshura Date: Thu, 6 Apr 2023 10:50:53 +0200 Subject: [PATCH] Update GuiRpc.md file Signed-off-by: Vitalii Koshura --- GuiRpc.md | 392 ++++++++++++++++++++++++++---------------------------- 1 file changed, 189 insertions(+), 203 deletions(-) diff --git a/GuiRpc.md b/GuiRpc.md index ccd1041..e584146 100644 --- a/GuiRpc.md +++ b/GuiRpc.md @@ -1,21 +1,24 @@ -[[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 not documented, but can be inferred from the source code. +The XML formats are documented in [GuiRpcProtocol](GuiRpcProtocol). The following bindings are available: -* BOINC has a C++ binding, consisting of the GUI_RPC class. - The interface is in [lib/gui_rpc_client.h](source:boinc-v2/lib/gui_rpc_client.h), - and the program [boinc_cmd.cpp](source:boinc-v2/client/boinc_cmd.cpp) +* BOINC has a C++ binding, consisting of the RPC_CLIENT class. + The interface is in + [lib/gui_rpc_client.h](https://github.com/BOINC/boinc/blob/master/lib/gui_rpc_client.h), + and the program + [boinc_cmd.cpp](https://github.com/BOINC/boinc/blob/master/client/boinc_cmd.cpp) gives a usage example. - All member functions return an integer error code. -* Another C++ binding is part of [boinctui](https://code.google.com/p/boinctui/). -* A Java binding: [source:boinc-v2/android/BOINC/src/edu/berkeley/boinc/rpc/]. -* A .Net binding: https://boincguirpc.codeplex.com/ +* Another C++ binding is part of [boinctui](https://github.com/suleman1971/boinctui). +* A Java binding: + [https://github.com/BOINC/boinc/tree/master/android/BOINC/src/edu/berkeley/boinc/rpc](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. @@ -24,123 +27,108 @@ 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. +The functions listed are members of the **RPC_CLIENT** class. +All member functions return an integer error code. -# Connecting +## Connecting -To establish RPC connection to a host, -create a `RPC_CLIENT` object and call - - `init(char* host)`. - +To establish an RPC connection to a host: -# Dealing with versions +``` +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). -* Call `exchange_versions()` to get the client version. -* If `exchange_versions()` fails (it's not supported in pre-5.6 clients) - do a `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). +## Authorization - - #!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. +The RPC protocol allows the GUI program to authenticate itself using a +[password](https://boinc.berkeley.edu/wiki/Controlling_BOINC_remotely). 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)`:: - Do authorization sequence with the peer, using given password. +``` +retval = rpc.authorize(char* password) +``` +Authorize with the peer, using given password. + +## RPC list -# RPC list The following functions require authorization for remote clients, but not for local clients. -Note: for client versions 5.5.12 and earlier, -all functions except `get_state()`, -`get_results()`, `get_screensaver_mode()`, -and `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. - +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. - `exchange_versions(VERSION_INFO&)`:: - Exchange version info with the client. - The client's version info is returned. - - `get_activity_state(ACTIVITY_STATE&)`:: - Return bitmap of reasons why computation and network are suspended. -*Deprecated* - for 5.5.13 and later, use cc_status() instead. - In 5.5.10 and earlier, it returns a `bool` (suspended) rather than bitmap. - - `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; - }; - +### `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_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_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 [get_state()](#function-get_state) again. +### `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 [get_state()](#function-get_state) again. - `get_host_info(HOST_INFO&)`:: - Get information about host hardware and usage. +### `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. +### `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 *_("...")*. + 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_message_count(int& seqno)` +Return the greatest message sequence number. +Implemented in 6.10+ client version. - `get_newer_versions(string&)`:: - Get a string describing newer versions of the client, if any. +### `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). +### `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, @@ -149,149 +137,147 @@ and `set_screensaver_mode()` require authorization. Implemented in 6.11+ client version. - `get_project_status(vector&)`:: - Get a list of projects, with only basic fields filled in. +### `get_project_status(vector\&)` +Get a list of projects, with only basic fields filled in. - `get_proxy_settings(PROXY_INFO&)`:: - Get proxy settings. +### `get_proxy_settings(PROXY_INFO&)` +Get proxy settings. - `get_results(RESULTS&)`:: - Get a list of [results](JobIn). - 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 [get_state()](#function-get_state) again. +### `get_results(RESULTS&)` +Get a list of [results](JobIn). +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 [get_state()](#function-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 [get_results()](#function-get_results)). +### `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 [get_results()](#function-get_results)). - `get_screensaver_mode(int& status)`:: - Return screensaver mode (values are listed in [common_defs.h](source:boinc/lib/common_defs.h)). +### `get_screensaver_mode(int& status)` +Return screensaver mode (values are listed in [common_defs.h](source:boinc/lib/common_defs.h)). - `get_simple_gui_info(SIMPLE_GUI_INFO&)`:: - Return the list of projects and of active results. +### `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_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). +### `get_statistics(PROJECTS&)` +Get information about project credit history (the `PROJECT::statistics` field is populated). - `network_status(int&)`:: - Find whether the client has, needs, or is done with a physical network connection. - Deprecated - for 5.5.13 and later, use [cc_status()](#function-cc_status) instead. - - `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. +### `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_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 [acct_mgr_info()](#function-acct_mgr_info)). - If `url` is the empty string, remove account manager info from disk. +### `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 [acct_mgr_info()](#function-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". +### `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 [preferences override](PrefsOverride) file into the given string. - Return an error code if the file is not present. +### `get_global_prefs_override(string&)` +Reads the contents of the global [preferences override](PrefsOverride) 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. +### `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. +### `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_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". +### `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. +### `quit()` +Tell the client to exit. - `read_global_prefs_override()`:: - Tells the client to reread the [global_prefs_override.xml](PrefsOverride) file, - modifying the global preferences according to its contents. +### `read_global_prefs_override()` +Tells the client to reread the [global_prefs_override.xml](PrefsOverride) 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. +### `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. - `result_op(RESULT&, const char* op)`:: - Perform a control operation on an active result. `op` is one of "suspend", "resume", or "abort". +[=#reset_host_info] +### `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. - `run_benchmarks()`:: - Run benchmarks. +### `result_op(RESULT&, const char* op)` +Perform a control operation on an active result. `op` is one of "suspend", "resume", or "abort". - `set_debts(vector)`:: - Set the short- and long-term debts of the given projects - (only the `master_url`, `short_term_debt`, `long_term_debt`, `cuda_debt` and `ati_debt` - fields are used in the `PROJECT` structs). +### `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(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 [preferences override](PrefsOverride) file. +### `set_global_prefs_override_struct(GLOBAL_PREFS&)` +Convert the given structure to XML and write it to the global [preferences override](PrefsOverride) 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(); - +``` +GLOBAL_PREFS prefs; +GLOBAL_PREFS_MASK prefs_mask; +RPC_CLIENT rpc; +char password[256]; - `set_network_mode(int mode, double duration)`:: - Set the network mode (never/auto/always). +read_gui_rpc_password(password); +rpc.init("localhost"); +rpc.authorize(password); - `set_proxy_settings(PROXY_INFO&)`:: - Set proxy settings. +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_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. +### `set_network_mode(int mode, double duration)` +Set the network mode (never/auto/always). -# Android-specific RPCs +### `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&); - +``` +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