mirror of https://github.com/BOINC/boinc.git
Update GuiRpc.md file
Signed-off-by: Vitalii Koshura <lestat.de.lionkur@gmail.com>
parent
a31dc6968e
commit
3c924adbd9
392
GuiRpc.md
392
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<PROJECT>&)`::
|
||||
Get a list of projects, with disk usage fields filled in.
|
||||
### `get_disk_usage(vector\<PROJECT>&)`
|
||||
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<PROJECT>&)`::
|
||||
Get a list of projects, with only basic fields filled in.
|
||||
### `get_project_status(vector\<PROJECT>&)`
|
||||
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<OLD_RESULT>)`::
|
||||
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\<OLD_RESULT>)`
|
||||
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<PROJECT>)`::
|
||||
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 `<global_preferences>` 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 `<global_preferences>` 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
|
||||
|
|
Loading…
Reference in New Issue