Changes between Version 25 and Version 26 of GuiRpc


Ignore:
Timestamp:
Jun 29, 2010, 1:59:19 PM (14 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GuiRpc

    v25 v26  
    2727== Dealing with versions ==
    2828
    29 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:
    30 
    31     * Create a `GUI_RPC` object and connect. Call [#function-exchange_versions exchange_versions()] to get the client version.
    32     * If [#function-exchange_versions exchange_versions()] fails (it's not supported in pre-5.6 clients) do a [#function-get_state get_state()] RPC, and get the client version from `CC_STATE::version_info`.
    33     * Use the client version number to decide what subsequent RPCs to make (version info is included in the RPC list below).
     29The GUI RPC protocol changes over time.
     30If you're writing a GUI program that needs to communicate with older versions of the BOINC core client,
     31here's what to do:
     32
     33 * 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`.
     37 * Use the client version number to decide what subsequent RPCs to make
     38  (version info is included in the RPC list below).
    3439
    3540{{{
    … …  
    6267=== `get_state(CC_STATE&)` === #function-get_state
    6368
    64 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).
     69Get the core client's 'static' state, i.e. its projects, apps, app_versions, workunits and results.
     70This call is relatively slow and should only be done initially, and when needed later (see below).
    6571
    6672=== `exchange_versions(VERSION_INFO&)` === #function-exchange_versions
    6773
    68 Exchange version info with the core client. The core client's version info is returned.
     74Exchange version info with the core client.
     75The core client's version info is returned.
    6976
    7077=== `get_cc_status(CC_STATUS&)` === #function-get_cc_status
    … …  
    103110=== `set_screensaver_mode``(bool enabled, ``double blank_time, ``DISPLAY_INFO&)` === #function-set_screensaver_mode
    104111
    105 If `enabled` is `true`, the core client should try to get an application to provide screensaver graphics. Blank screen after `blank_time` seconds.
     112If `enabled` is `true`, the core client should try to get an application to provide screensaver graphics.
     113Blank screen after `blank_time` seconds.
    106114
    107115=== `get_file_transfers(FILE_TRANSFERS&)` === #function-get_file_transfers
    108116
    109 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.
     117Get a list of file transfers in progress.
     118Each is linked by name to a project; use `CC_STATE::lookup_project()`
     119to find this project in the current state;
     120if it's not there, call [#function-get_state get_state()] again.
    110121
    111122=== `get_simple_gui_info(SIMPLE_GUI_INFO&)` === #function-get_simple_gui_info
    … …  
    127138=== `get_activity_state(ACTIVITY_STATE&)` === #function-get_activity_state
    128139
    129 Return bitmap of reasons why computation and network are suspended. '''Deprecated''' - for 5.5.13 and later, use [#function-cc_status cc_status()] instead. In 5.5.10 and earlier, it returns a `bool` (suspended) rather than bitmap.
     140Return bitmap of reasons why computation and network are suspended.
     141'''Deprecated''' - for 5.5.13 and later, use [#function-cc_status cc_status()] instead.
     142In 5.5.10 and earlier, it returns a `bool` (suspended) rather than bitmap.
    130143
    131144=== `get_messages(int seqno, MESSAGES&)` === #function-get_messages
    132145
    133 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.
     146Returns a list of messages to be displayed to the user.
     147Each message has a sequence number (1, 2, ...), a priority (1=informational, 2=error) and a timestamp.
     148The RPC requests the messages with sequence numbers greater than `seqno`,
     149in order of increasing sequence number.
    134150
    135151=== `get_message_count(int& seqno)` === #function-get_message_seqno
    136152
    137 Return the greatest message sequence number.  Implemented in 6.10+ client version.
     153Return the greatest message sequence number.
     154 Implemented in 6.10+ client version.
    138155
    139156=== `get_host_info(HOST_INFO&)` === #function-get_host_info
    … …  
    147164=== `network_status(int&)` === #function-network_status
    148165
    149 Find whether the core client has, needs, or is done with a physical network connection. Deprecated - for 5.5.13 and later, use [#function-cc_status cc_status()] instead.
     166Find whether the core client has, needs, or is done with a physical network connection.
     167Deprecated - for 5.5.13 and later, use [#function-cc_status cc_status()] instead.
    150168
    151169=== `get_newer_versions(std::string&)` === #function-get_newer_versions
    … …  
    163181=== `project_op(PROJECT&, char* op)` === #function-project_op
    164182
    165 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".
     183Perform a control operation on the given project (only the `master_url` field needs to be set).
     184`op` is one of "suspend", "resume", "reset", "detach", "update", "allowmorework", "nomorework".
     185Since 5.10.14: "detach_when_done", "dont_detach_when_done".
    166186
    167187=== `project_attach(``char* url, ``char* account_key, ``char* project_name)` === #function-project_attach
    … …  
    171191=== `set_run_mode(int mode, double duration)` === #function-set_run_mode
    172192
    173 Set the run mode (never/auto/always). If duration is zero, mode is permanent. Otherwise revert to last permanent mode after duration seconds elapse.
     193Set the run mode (never/auto/always).
     194If duration is zero, mode is permanent.
     195Otherwise revert to last permanent mode after duration seconds elapse.
    174196
    175197=== `set_network_mode(int mode, double duration)` === #function-set_network_mode
    … …  
    187209=== `network_available()` === #function-network_available
    188210
    189 Tells the core client that a network connection is available, and that it should do as much network activity as it can.
     211Tells the core client that a network connection is available,
     212and that it should do as much network activity as it can.
    190213
    191214=== `file_transfer_op(FILE_TRANSFER&, const char* op)` === #function-file_transfer_op
    … …  
    203226=== `acct_mgr_rpc(``const char* url, ``const char* name, ``const char* passwd, ``bool use_config_file)` === #function-acct_mgr_rpc
    204227
    205 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 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 [#function-acct_mgr_info acct_mgr_info()]). If `url` is the empty string, remove account manager info from disk.
     228Do an Account Manager RPC to the given URL, passing the given name/password.
     229If `use_config_file` is true, then the existing URL, username, and password are used
     230and the core client updates the project information from the account manager.
     231If the RPC is successful,
     232save the account info on disk (it can be retrieved later using [#function-acct_mgr_info acct_mgr_info()]).
     233If `url` is the empty string, remove account manager info from disk.
    206234
    207235=== `acct_mgr_info(ACCT_MGR_INFO&)` === #function-acct_mgr_info
    … …  
    211239=== `read_global_prefs_override()` === #function-read_global_prefs_override
    212240
    213 Tells the core client to reread the [PrefsOverride global_prefs_override.xml] file, modifying the global preferences according to its contents.
     241Tells the core client to reread the [PrefsOverride global_prefs_override.xml] file,
     242modifying the global preferences according to its contents.
    214243
    215244=== `get_global_prefs_override(std::string&)` === #function-get_global_prefs_override
    216245
    217 Reads the contents of the global [PrefsOverride preferences override] file into the given string. Return an error code if the file is not present.
     246Reads the contents of the global [PrefsOverride preferences override] file into the given string.
     247Return an error code if the file is not present.
    218248
    219249=== `set_global_prefs_override(std::string&)` === #function-set_global_prefs_override
    220250
    221 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.
     251Write the given contents to the global preferences override file.
     252If the argument is an empty string, delete the file.
     253Otherwise the argument must be a valid `<global_preferences>` element.
    222254
    223255=== `get_global_prefs_override_struct(GLOBAL_PREFS&)` === #function-get_global_prefs_override_struct
    224256
    225 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.
     257Return the contents of the global preferences override file, parsed into a structure.
     258Default values are zero.
     259Returns an error code if the file is not present.
    226260
    227261=== `set_global_prefs_override_struct(GLOBAL_PREFS&)` === #function-set_global_prefs_override_struct
    … …  
    249283=== `set_debts(std::vector<PROJECT>)` === #function-set_debts
    250284
    251 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). [[T(VersionNew|5.10.11)]]
     285Set the short- and long-term debts of the given projects
     286(only the `master_url`, `short_term_debt`, `long_term_debt`, `cuda_debt` and `ati_debt`
     287fields are used in the `PROJECT` structs).
     288[[T(VersionNew|5.10.11)]]
     289