Changes between Version 30 and Version 31 of GuiRpc


Ignore:
Timestamp:
Nov 30, 2010, 3:50:39 PM (14 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GuiRpc

    v30 v31  
    1 {{{
    2 #!comment I tried adding [[PageOutline]] too but it seemed too long, and breaking the page layout. 
    3 }}}
     1[[PageOutline]]
    42
    53= Controlling the core client via RPC =
     
    2119To create an RPC connection, call
    2220
    23 === `init(char* host)` === #function-init
    24 
    25 Establish RPC connection to the given host.
     21 `init(char* host)`::
     22 Establish RPC connection to the given host.
    2623
    2724== Dealing with versions ==
     
    3229
    3330 * Create a `GUI_RPC` object and connect.
    34   Call [#function-exchange_versions exchange_versions()] to get the client version.
    35  * If [#function-exchange_versions exchange_versions()] fails (it's not supported in pre-5.6 clients)
    36   do a [#function-get_state get_state()] RPC, and get the client version from `CC_STATE::version_info`.
     31  Call `exchange_versions()` to get the client version.
     32 * If `exchange_versions()` fails (it's not supported in pre-5.6 clients)
     33  do a `get_state()` RPC, and get the client version from `CC_STATE::version_info`.
    3734 * Use the client version number to decide what subsequent RPCs to make
    3835  (version info is included in the RPC list below).
     
    5047but only by a GUI program running on the same machine.
    5148
    52 === `authorize(char* password)` === #function-authorize
    53 Do authorization sequence with the peer, using given password.
     49 `authorize(char* password)`::
     50 Do authorization sequence with the peer, using given password.
    5451
    5552== RPC list ==
    5653The following functions require authorization for remote clients, but not for local clients.
    5754Note: for core client versions 5.5.12 and earlier,
    58 all functions except [#function-get_state get_state()],
    59 [#function-get_results get_results()], [#function-get_screensaver_mode get_screensaver_mode()],
    60 and [#function-set_screensaver_mode set_screensaver_mode()] require authorization.
     55all functions except `get_state()`,
     56`get_results()`, `get_screensaver_mode()`,
     57and `set_screensaver_mode()` require authorization.
    6158
    6259{{{
    6360#!comment
    64 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.
    65 }}}
    66 
    67 === `get_state(CC_STATE&)` === #function-get_state
    68 
    69 Get the core client's 'static' state, i.e. its projects, apps, app_versions, workunits and results.
    70 This call is relatively slow and should only be done initially, and when needed later (see below).
    71 
    72 === `exchange_versions(VERSION_INFO&)` === #function-exchange_versions
    73 
    74 Exchange version info with the core client.
    75 The core client's version info is returned.
    76 
    77 === `get_cc_status(CC_STATUS&)` === #function-get_cc_status
     61A few function headers like set_screensaver_mode, project_attach and acct_mgr_rpc have the `monospaced`
     62parts broken that way to allow word wrap.
     63}}}
     64
     65 `exchange_versions(VERSION_INFO&)`::
     66 Exchange version info with the core client.
     67 The core client's version info is returned.
     68
     69 `get_activity_state(ACTIVITY_STATE&)`::
     70 Return bitmap of reasons why computation and network are suspended.
     71 '''Deprecated''' - for 5.5.13 and later, use cc_status() instead.
     72 In 5.5.10 and earlier, it returns a `bool` (suspended) rather than bitmap.
     73
     74 `get_cc_status(CC_STATUS&)`::
    7875{{{
    7976struct CC_STATUS {
     
    9289};
    9390}}}
    94 
    95 Return a structure containing the network status,
    96 a flag if there was an account manager password error,
    97 and data about task and network suspension.
    98 
    99 === `get_results(RESULTS&)` === #function-get_results
    100 
    101 Get a list of [JobIn results].
    102 Those that are in progress will have information such as CPU time and fraction done.
    103 Each result includes a name; use `CC_STATE::lookup_result()` to find this result in the current static state;
    104 if it's not there, call [#function-get_state get_state()] again.
    105 
    106 === `get_screensaver_mode(int& status)` === #function-get_screensaver_mode
    107 
    108 Return screensaver mode (values are listed in [source:trunk/boinc/lib/common_defs.h common_defs.h]).
    109 
    110 === `set_screensaver_mode``(bool enabled, ``double blank_time, ``DISPLAY_INFO&)` === #function-set_screensaver_mode
    111 
    112 If `enabled` is `true`, the core client should try to get an application to provide screensaver graphics.
    113 Blank screen after `blank_time` seconds.
    114 
    115 === `get_file_transfers(FILE_TRANSFERS&)` === #function-get_file_transfers
    116 
    117 Get a list of file transfers in progress.
    118 Each is linked by name to a project; use `CC_STATE::lookup_project()`
    119 to find this project in the current state;
    120 if it's not there, call [#function-get_state get_state()] again.
    121 
    122 === `get_simple_gui_info(SIMPLE_GUI_INFO&)` === #function-get_simple_gui_info
    123 
    124 Return the list of projects and of active results.
    125 
    126 === `get_project_status(vector<PROJECT>&)` === #function-get_project_status
    127 
    128 Get a list of projects, with only basic fields filled in.
    129 
    130 === `get_disk_usage(vector<PROJECT>&)` === #function-get_disk_usage
    131 
    132 Get a list of projects, with disk usage fields filled in.
    133 
    134 === `get_proxy_settings(PROXY_INFO&)` === #function-get_proxy_settings
    135 
    136 Get proxy settings.
    137 
    138 === `get_activity_state(ACTIVITY_STATE&)` === #function-get_activity_state
    139 
    140 Return bitmap of reasons why computation and network are suspended.
    141 '''Deprecated''' - for 5.5.13 and later, use [#function-cc_status cc_status()] instead.
    142 In 5.5.10 and earlier, it returns a `bool` (suspended) rather than bitmap.
    143 
    144 === `get_messages(int seqno, MESSAGES&, bool translatable=false)` === #function-get_messages
    145 
    146 Returns a list of messages to be displayed to the user.
    147 Each message has a sequence number (1, 2, ...), a priority (1=informational, 2=error) and a timestamp.
    148 The RPC requests the messages with sequence numbers greater than `seqno`,
    149 in order of increasing sequence number.
    150 
    151 If '''translatable''' is true, messages from 6.11+ clients may include translatable parts.
    152 These parts are enclosed in '''_("...")'''.
    153 They should be translated according to the translation files in boinc/locale/*/BOINC-Client.po
    154 
    155 === `get_message_count(int& seqno)` === #function-get_message_seqno
    156 
    157 Return the greatest message sequence number.
     91 Return a structure containing the network status,
     92 a flag if there was an account manager password error,
     93 and data about task and network suspension.
     94
     95 `get_disk_usage(vector<PROJECT>&)`::
     96 Get a list of projects, with disk usage fields filled in.
     97
     98 `get_file_transfers(FILE_TRANSFERS&)`::
     99 Get a list of file transfers in progress.
     100 Each is linked by name to a project; use `CC_STATE::lookup_project()`
     101 to find this project in the current state;
     102 if it's not there, call [#function-get_state get_state()] again.
     103
     104 `get_host_info(HOST_INFO&)`::
     105 Get information about host hardware and usage.
     106
     107 `get_messages(int seqno, MESSAGES&, bool translatable=false)`::
     108 Returns a list of messages to be displayed to the user.
     109 Each message has a sequence number (1, 2, ...), a priority (1=informational, 2=error) and a timestamp.
     110 The RPC requests the messages with sequence numbers greater than `seqno`,
     111 in order of increasing sequence number.
     112
     113 If '''translatable''' is true, messages from 6.11+ clients may include translatable parts.
     114 These parts are enclosed in '''_("...")'''.
     115 They should be translated according to the translation files in boinc/locale/*/BOINC-Client.po
     116
     117 `get_message_count(int& seqno)`::
     118 Return the greatest message sequence number.
    158119 Implemented in 6.10+ client version.
    159120
    160 === `get_notices(int seqno, NOTICES& notices)` === #function-get_notices
    161 
    162 Returns a list of notices with sequence number greater than seqno.
    163 Notices are returned in order of increasing sequence number
    164 (which is the same as increasing arrival time).
    165 
    166 Unlike messages, notices can be removed.
    167 In this case, notices.complete is set to true,
    168 and notices.notices contains all notices.
    169 Otherwise notices.notices contains only new notices.
    170 
    171 Implemented in 6.11+ client version.
    172 
    173 === `get_host_info(HOST_INFO&)` === #function-get_host_info
    174 
    175 Get information about host hardware and usage.
    176 
    177 === `get_statistics(PROJECTS&)` === #function-get_statistics
    178 
    179 Get information about project credit history (the `PROJECT::statistics` field is populated).
    180 
    181 === `network_status(int&)` === #function-network_status
    182 
    183 Find whether the core client has, needs, or is done with a physical network connection.
    184 Deprecated - for 5.5.13 and later, use [#function-cc_status cc_status()] instead.
    185 
    186 === `get_newer_versions(std::string&)` === #function-get_newer_versions
    187 
    188 Get a string describing newer versions of the core client, if any.
     121 `get_newer_versions(string&)`::
     122 Get a string describing newer versions of the core client, if any.
     123
     124 `get_notices(int seqno, NOTICES& notices)`::
     125 Returns a list of notices with sequence number greater than seqno.
     126 Notices are returned in order of increasing sequence number
     127 (which is the same as increasing arrival time).
     128
     129 Unlike messages, notices can be removed.
     130 In this case, notices.complete is set to true,
     131 and notices.notices contains all notices.
     132 Otherwise notices.notices contains only new notices.
     133
     134 Implemented in 6.11+ client version.
     135
     136 `get_project_status(vector<PROJECT>&)`::
     137 Get a list of projects, with only basic fields filled in.
     138
     139 `get_proxy_settings(PROXY_INFO&)`::
     140 Get proxy settings.
     141
     142 `get_results(RESULTS&)`::
     143 Get a list of [JobIn results].
     144 Those that are in progress will have information such as CPU time and fraction done.
     145 Each result includes a name; use `CC_STATE::lookup_result()` to find this result in the current static state;
     146 if it's not there, call [#function-get_state get_state()] again.
     147
     148 `get_screensaver_mode(int& status)`::
     149 Return screensaver mode (values are listed in [source:trunk/boinc/lib/common_defs.h common_defs.h]).
     150
     151 `get_simple_gui_info(SIMPLE_GUI_INFO&)`::
     152 Return the list of projects and of active results.
     153
     154 `get_state(CC_STATE&)`::
     155  Get the core client's 'static' state, i.e. its projects, apps, app_versions, workunits and results.
     156  This call is relatively slow and should only be done initially, and when needed later (see below).
     157
     158 `get_statistics(PROJECTS&)`::
     159 Get information about project credit history (the `PROJECT::statistics` field is populated).
     160
     161 `network_status(int&)`::
     162 Find whether the core client has, needs, or is done with a physical network connection.
     163 Deprecated - for 5.5.13 and later, use [#function-cc_status cc_status()] instead.
     164
     165 `set_screensaver_mode``(bool enabled, ``double blank_time, ``DISPLAY_INFO&)`::
     166 If `enabled` is `true`, the core client should try to get an application to provide screensaver graphics.
     167 Blank screen after `blank_time` seconds.
    189168
    190169----
     
    192171The following operations require authentication for both local and remote clients:
    193172
    194 === `show_graphics(char* result_name, bool full_screen)` === #function-show_graphics
    195 
    196 Request that the application processing the given result create a graphics window.
    197 
    198 === `project_op(PROJECT&, char* op)` === #function-project_op
    199 
    200 Perform a control operation on the given project (only the `master_url` field needs to be set).
    201 `op` is one of "suspend", "resume", "reset", "detach", "update", "allowmorework", "nomorework".
    202 Since 5.10.14: "detach_when_done", "dont_detach_when_done".
    203 
    204 === `project_attach(``char* url, ``char* account_key, ``char* project_name)` === #function-project_attach
    205 
    206 Attach to the given project.
    207 
    208 === `set_run_mode(int mode, double duration)` === #function-set_run_mode
    209 
    210 Set the run mode (never/auto/always).
    211 If duration is zero, mode is permanent.
    212 Otherwise revert to last permanent mode after duration seconds elapse.
    213 
    214 === `set_network_mode(int mode, double duration)` === #function-set_network_mode
    215 
    216 Set the network mode (never/auto/always).
    217 
    218 === `run_benchmarks()` === #function-run_benchmarks
    219 
    220 Run benchmarks.
    221 
    222 === `set_proxy_settings(PROXY_INFO&)` === #function-set_proxy_settings
    223 
    224 Set proxy settings.
    225 
    226 === `network_available()` === #function-network_available
    227 
    228 Tells the core client that a network connection is available,
    229 and that it should do as much network activity as it can.
    230 
    231 === `file_transfer_op(FILE_TRANSFER&, const char* op)` === #function-file_transfer_op
    232 
    233 Perform a control operation on a file transfer. `op` is one of "abort" or "retry".
    234 
    235 === `result_op(RESULT&, const char* op)` === #function-result_op
    236 
    237 Perform a control operation on an active result. `op` is one of "suspend", "resume", or "abort".
    238 
    239 === `quit()` === #function-quit
    240 
    241 Tell the core client to exit.
    242 
    243 === `acct_mgr_rpc(``const char* url, ``const char* name, ``const char* passwd, ``bool use_config_file)` === #function-acct_mgr_rpc
    244 
    245 Do an Account Manager RPC to the given URL, passing the given name/password.
    246 If `use_config_file` is true, then the existing URL, username, and password are used
    247 and the core client updates the project information from the account manager.
    248 If the RPC is successful,
    249 save the account info on disk (it can be retrieved later using [#function-acct_mgr_info acct_mgr_info()]).
    250 If `url` is the empty string, remove account manager info from disk.
    251 
    252 === `acct_mgr_info(ACCT_MGR_INFO&)` === #function-acct_mgr_info
    253 
    254 Return the URL/name of the current account manager (if any), and the user name and password.
    255 
    256 === `read_global_prefs_override()` === #function-read_global_prefs_override
    257 
    258 Tells the core client to reread the [PrefsOverride global_prefs_override.xml] file,
    259 modifying the global preferences according to its contents.
    260 
    261 === `get_global_prefs_override(std::string&)` === #function-get_global_prefs_override
    262 
    263 Reads the contents of the global [PrefsOverride preferences override] file into the given string.
    264 Return an error code if the file is not present.
    265 
    266 === `set_global_prefs_override(std::string&)` === #function-set_global_prefs_override
    267 
    268 Write the given contents to the global preferences override file.
    269 If the argument is an empty string, delete the file.
    270 Otherwise the argument must be a valid `<global_preferences>` element.
    271 
    272 === `get_global_prefs_override_struct(GLOBAL_PREFS&)` === #function-get_global_prefs_override_struct
    273 
    274 Return the contents of the global preferences override file, parsed into a structure.
    275 Default values are zero.
    276 Returns an error code if the file is not present.
    277 
    278 === `set_global_prefs_override_struct(GLOBAL_PREFS&)` === #function-set_global_prefs_override_struct
    279 
    280 Convert the given structure to XML and write it to the global [PrefsOverride preferences override] file.
    281 
    282 To modify a particular preference (e.g., CPU throttle):
     173 `acct_mgr_info(ACCT_MGR_INFO&)`::
     174 Return the URL/name of the current account manager (if any), and the user name and password.
     175
     176 `acct_mgr_rpc(``const char* url, ``const char* name, ``const char* passwd, ``bool use_config_file)`::
     177 Do an Account Manager RPC to the given URL, passing the given name/password.
     178 If `use_config_file` is true, then the existing URL, username, and password are used
     179 and the core client updates the project information from the account manager.
     180 If the RPC is successful,
     181 save the account info on disk (it can be retrieved later using [#function-acct_mgr_info acct_mgr_info()]).
     182 If `url` is the empty string, remove account manager info from disk.
     183
     184 `file_transfer_op(FILE_TRANSFER&, const char* op)`::
     185 Perform a control operation on a file transfer. `op` is one of "abort" or "retry".
     186
     187 `get_global_prefs_override(string&)`::
     188 Reads the contents of the global [PrefsOverride preferences override] file into the given string.
     189 Return an error code if the file is not present.
     190
     191 `get_global_prefs_override_struct(GLOBAL_PREFS&)`::
     192 Return the contents of the global preferences override file, parsed into a structure.
     193 Default values are zero.
     194 Returns an error code if the file is not present.
     195
     196 `network_available()`::
     197 Tells the core client that a network connection is available,
     198 and that it should do as much network activity as it can.
     199
     200 `project_attach(``char* url, ``char* account_key, ``char* project_name)`::
     201 Attach to the given project.
     202
     203 `project_op(PROJECT&, char* op)`::
     204 Perform a control operation on the given project (only the `master_url` field needs to be set).
     205 `op` is one of "suspend", "resume", "reset", "detach", "update", "allowmorework", "nomorework".
     206 Since 5.10.14: "detach_when_done", "dont_detach_when_done".
     207
     208 `quit()`::
     209 Tell the core client to exit.
     210
     211 `read_global_prefs_override()`::
     212 Tells the core client to reread the [PrefsOverride global_prefs_override.xml] file,
     213 modifying the global preferences according to its contents.
     214
     215 `result_op(RESULT&, const char* op)`::
     216 Perform a control operation on an active result. `op` is one of "suspend", "resume", or "abort".
     217
     218 `run_benchmarks()`::
     219 Run benchmarks.
     220
     221 `set_debts(vector<PROJECT>)`::
     222 Set the short- and long-term debts of the given projects
     223 (only the `master_url`, `short_term_debt`, `long_term_debt`, `cuda_debt` and `ati_debt`
     224 fields are used in the `PROJECT` structs).
     225
     226 `set_global_prefs_override(string&)`::
     227 Write the given contents to the global preferences override file.
     228 If the argument is an empty string, delete the file.
     229 Otherwise the argument must be a valid `<global_preferences>` element.
     230
     231 `set_global_prefs_override_struct(GLOBAL_PREFS&)`::
     232 Convert the given structure to XML and write it to the global [PrefsOverride preferences override] file.
     233
     234 To modify a particular preference (e.g., CPU throttle):
    283235{{{
    284236GLOBAL_PREFS prefs;
     
    298250}}}
    299251
    300 === `set_debts(std::vector<PROJECT>)` === #function-set_debts
    301 
    302 Set the short- and long-term debts of the given projects
    303 (only the `master_url`, `short_term_debt`, `long_term_debt`, `cuda_debt` and `ati_debt`
    304 fields are used in the `PROJECT` structs).
    305 [[T(VersionNew|5.10.11)]]
    306 
     252 `set_network_mode(int mode, double duration)`::
     253 Set the network mode (never/auto/always).
     254
     255 `set_proxy_settings(PROXY_INFO&)`::
     256 Set proxy settings.
     257
     258 `set_run_mode(int mode, double duration)`::
     259 Set the run mode (never/auto/always).
     260 If duration is zero, mode is permanent.
     261 Otherwise revert to last permanent mode after duration seconds elapse.
     262
     263 `show_graphics(char* result_name, bool full_screen)`::
     264 Request that the application processing the given result create a graphics window.
     265