Changes between Version 4 and Version 5 of GuiRpc


Ignore:
Timestamp:
Jun 30, 2007, 4:00:52 PM (17 years ago)
Author:
Nicolas
Comment:

Function names are now headers, so you can make links to specific functions. Some functions were in multiple lines; I had to put them in a single line. I hope it's still clear.

Legend:

Unmodified
Added
Removed
Modified

  • GuiRpc

    v4 v5  
     1{{{
     2#!comment I tried adding [[PageOutline]] too but it seemed too long, and breaking the page layout. 
     3}}}
     4
    15= Controlling the core client via RPC =
    26
    … …  
    711
    812To create an RPC connection, call
    9 {{{
    10 init(char* host)
    11 }}}
     13
     14=== `init(char* host)` === #function-init
     15
    1216Establish RPC connection to the given host
     17
     18== Dealing with versions ==
     19
     20The 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:
     21
     22    * Create a GUI_RPC object and connect. Call exchange_versions() to get the client version.
     23    * 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.
     24    * Use the client version number to decide what subsequent RPCs to make (version info is included in the RPC list below).
     25
     26== Authorization ==
     27
     28GUI RPC authorization is described here. 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.
     29
     30=== `authorize(char* password)` === #function-authorize
     31Do authorization sequence with the peer, using given password
     32
     33== RPC list ==
     34The 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 get_state(), get_results(), get_screensaver_mode(), and set_screensaver_mode() require authorization.
    1335
    1436{{{
    1537#!comment
    16 It would be useful if we could link to individual RPCs. I'm not sure if that would need =headers= or there is another way to make anchors.
     38A few function headers like set_screensaver_mode, project_attach and acct_mgr_rpc have the `monospaced` parts broken that way to allow word wrap.
    1739}}}
    1840
    19 == Dealing with versions ==
    20 
    21 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:
    22 
    23     * Create a GUI_RPC object and connect. Call exchange_versions() to get the client version.
    24     * 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.
    25     * Use the client version number to decide what subsequent RPCs to make (version info is included in the RPC list below).
    26 
    27 == Authorization ==
    28 
    29 GUI RPC authorization is described here. 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.
     41=== `get_state(CC_STATE&)` === #function-get_state
     42
     43Get 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).
     44
     45=== `exchange_versions(VERSION_INFO&)` === #function-exchange_versions
     46
     47Exchange version info with the core client. The core client's version info is returned.
     48
     49=== `get_cc_status(CC_STATUS&)` === #function-get_cc_status
    3050{{{
    31 authorize(char* password)
    32 }}}
    33 
    34 Do authorization sequence with the peer, using given password
    35 
    36 == RPC list ==
    37 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 get_state(), get_results(), get_screensaver_mode(), and set_screensaver_mode() require authorization.
    38 {{{
    39 get_state(CC_STATE&)
    40 }}}
    41 
    42 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).
    43 
    44 {{{
    45 exchange_versions(VERSION_INFO&)
    46 }}}
    47 
    48 Exchange version info with the core client. The core client's version info is returned.
    49 
    50 {{{
    51 get_cc_status(CC_STATUS&);
    5251struct CC_STATUS {
    5352    int network_status;
    … …  
    6362};
    6463}}}
    65    
    6664
    6765Return a structure containing the network status, a flag if there was an account manager password error, and data about task and network suspension.
    6866
    69 {{{
    70 get_results(RESULTS&)
    71 }}}
     67=== `get_results(RESULTS&)` === #function-get_results
    7268
    7369Get a list of 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 get_state() again.
    7470
    75 {{{
    76 get_screensaver_mode(int& status)
    77 }}}
     71=== `get_screensaver_mode(int& status)` === #function-get_screensaver_mode
    7872
    7973Return screensaver mode (values listed in ss_logic.h)
    8074
    81 {{{
    82 set_screensaver_mode(
    83     bool enabled, double blank_time, DISPLAY_INFO&
    84 )
    85 }}}
     75=== `set_screensaver_mode``(bool enabled, ``double blank_time, ``DISPLAY_INFO&)` === #function-set_screensaver_mode
    8676
    8777If enabled is true, the core client should try to get an application to provide screensaver graphics. Blank screen after blank_time seconds.
    8878
    89 {{{
    90 get_file_transfers(FILE_TRANSFERS&)
    91 }}}
     79=== `get_file_transfers(FILE_TRANSFERS&)` === #function-get_file_transfers
    9280
    9381Get 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() again.
    9482
    95 {{{
    96 get_simple_gui_info(SIMPLE_GUI_INFO&)
    97 }}}
     83=== `get_simple_gui_info(SIMPLE_GUI_INFO&)` === #function-get_simple_gui_info
    9884
    9985Return the list of projects and of active results.
    10086
    101 {{{
    102 get_project_status(vector<PROJECT>&)
    103 }}}
     87=== `get_project_status(vector<PROJECT>&)` === #function-get_project_status
    10488
    10589Get a list of projects, with only basic fields filled in.
    10690
    107 {{{
    108 get_disk_usage(vector<PROJECT>&)
    109 }}}
     91=== `get_disk_usage(vector<PROJECT>&)` === #function-get_disk_usage
    11092
    11193Get a list of projects, with disk usage fields filled in.
    11294
    113 {{{
    114 get_proxy_settings(PROXY_INFO&)
    115 }}}
     95=== `get_proxy_settings(PROXY_INFO&)` === #function-get_proxy_settings
    11696
    11797Get proxy settings
    11898
    119 {{{
    120 get_activity_state(ACTIVITY_STATE&)
    121 }}}
     99=== `get_activity_state(ACTIVITY_STATE&)` === #function-get_activity_state
    122100
    123101Return 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 bool (suspended) rather than bitmap.
    124102
    125 {{{
    126 get_messages(int seqno, MESSAGES&)
    127 }}}
     103=== `get_messages(int seqno, MESSAGES&)` === #function-get_messages
    128104
    129105Returns 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.
    130106
    131 {{{
    132 get_host_info(HOST_INFO&)
    133 }}}
     107=== `get_host_info(HOST_INFO&)` === #function-get_host_info
    134108
    135109Get information about host hardware and usage
    136110
    137 {{{
    138 get_statistics(PROJECTS&)
    139 }}}
     111=== `get_statistics(PROJECTS&)` === #function-get_statistics
    140112
    141113Get information about project credit history (the PROJECT::statistics field is populated)
    142114
    143 {{{
    144 network_status(int&)
    145 }}}
     115=== `network_status(int&)` === #function-network_status
    146116
    147117Find whether the core client has, needs, or is done with a physical network connection. Deprecated - for 5.5.13 and later, use cc_status() instead.
    148118
    149 {{{
    150 get_newer_versions(std::string&)
    151 }}}
     119=== `get_newer_versions(std::string&)` === #function-get_newer_versions
    152120
    153121Get a string describing newer versions of the core client, if any.
    … …  
    155123The following operations require authentication for both local and remote clients:
    156124
    157 {{{
    158 show_graphics(char* result_name, bool full_screen)
    159 }}}
     125=== `show_graphics(char* result_name, bool full_screen)` === #function-show_graphics
    160126
    161127Request that the application processing the given result create a graphics window
    162128
    163 {{{
    164 project_op(PROJECT&, char* op)
    165 }}}
     129=== `project_op(PROJECT&, char* op)` === #function-project_op
    166130
    167131Perform a control operation on the given project. op is one of "suspend", "resume", "reset", "detach", or "update".
    168132
    169 {{{
    170 project_attach(
    171     char* url,
    172     char* account_id,
    173     bool use_config_file
    174 )
    175 }}}
     133=== `project_attach(``char* url, ``char* account_id, ``bool use_config_file)` === #function-project_attach
    176134
    177135Attach to the given project. If 'use_config_file' is true, use the project URL (and account key, if present) in the project_init.xml file.
    178136
    179 {{{
    180 set_run_mode(int mode, double duration)
    181 }}}
     137=== `set_run_mode(int mode, double duration)` === #function-set_run_mode
    182138
    183139Set the run mode (never/auto/always). If duration is zero, mode is permanent. Otherwise revert to last permanent mode after duration seconds elapse.
    184140
    185 {{{
    186 set_network_mode(int mode, double duration)
    187 }}}
     141=== `set_network_mode(int mode, double duration)` === #function-set_network_mode
    188142
    189143Set the network mode (never/auto/always).
    190144
    191 {{{
    192 run_benchmarks()
    193 }}}
     145=== `run_benchmarks()` === #function-run_benchmarks
    194146
    195147Run benchmarks
    196148
    197 {{{
    198 set_proxy_settings(PROXY_INFO&)
    199 }}}
     149=== `set_proxy_settings(PROXY_INFO&)` === #function-set_proxy_settings
    200150
    201151Set proxy settings
    202152
    203 {{{
    204 network_available()
    205 }}}
     153=== `network_available()` === #function-network_available
    206154
    207155Tells the core client that a network connection is available, and that it should do as much network activity as it can.
    208156
    209 {{{
    210 file_transfer_op(FILE_TRANSFER&, char* op)
    211 }}}
     157=== `file_transfer_op(FILE_TRANSFER&, char* op)` === #function-file_transfer_op
    212158
    213159Perform a control operation on a file transfer. op is one of "abort" or "retry".
    214160
    215 {{{
    216 result_op(FILE_TRANSFER&, char* op)
    217 }}}
     161=== `result_op(FILE_TRANSFER&, char* op)` === #function-result_op
    218162
    219163Perform a control operation on an active result. op is one of "suspend", "resume", or "abort".
    220164
    221 {{{
    222 quit()
    223 }}}
     165=== `quit()` === #function-quit
    224166
    225167Tell the core client to exit.
    226168
    227 {{{
    228 acct_mgr_rpc(
    229     const char* url,
    230     const char* name,
    231     const char* passwd,
    232     bool use_cached_credentials
    233 )
    234 }}}
     169=== `acct_mgr_rpc(``const char* url, ``const char* name, ``const char* passwd, ``bool use_cached_credentials)` === #function-acct_mgr_rpc
    235170
    236171Do an Account Manager RPC to the given URL, passing the given name/password. If use_cached_credentials 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 acct_mgr_info(), see below). If URL is the empty string, remove account manager info from disk.
    237172
    238 {{{
    239 acct_mgr_info(ACCT_MGR_INFO&)
    240 }}}
     173=== `acct_mgr_info(ACCT_MGR_INFO&)` === #function-acct_mgr_info
    241174
    242175Return the URL/name of the current account manager (if any), and the user name and password.
    243176
    244 {{{
    245 read_global_prefs_override()
    246 }}}
     177=== `read_global_prefs_override()` === #function-read_global_prefs_override
    247178
    248179Tells the core client to reread the 'global_prefs_override.xml' file, modifying the global preferences according to its contents.
    249180
    250 {{{
    251 get_global_prefs_override(std::string&)
    252 }}}
     181=== `get_global_prefs_override(std::string&)` === #function-get_global_prefs_override
    253182
    254183Reads the contents of the global preferences override file into the given string. Return an error code if the file is not present.
    255184
    256 {{{
    257 set_global_prefs_override(std::string&)
    258 }}}
     185=== `set_global_prefs_override(std::string&)` === #function-set_global_prefs_override
    259186
    260187Write 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.
    261188
    262 {{{
    263 get_global_prefs_override_struct(GLOBAL_PREFS&)
    264 }}}
     189=== `get_global_prefs_override_struct(GLOBAL_PREFS&)` === #function-get_global_prefs_override_struct
    265190
    266191Return 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.
    267192
    268 {{{
    269 set_global_prefs_override_struct(GLOBAL_PREFS&)
    270 }}}
     193=== `set_global_prefs_override_struct(GLOBAL_PREFS&)` === #function-set_global_prefs_override_struct
    271194Convert the given structure to XML and write it to the global preferences override file.
    272195
    273 {{{
    274 set_debts(std::vector<PROJECT>)
    275 }}}
     196=== `set_debts(std::vector<PROJECT>)` === #function-set_debts
    276197Set the short- and long-term debts of the given projects
    277198(only the master_url, short_term_debt, and long_term_debt fields
    278199are used in the PROJECT structs).
     200