T(Incomplete)?

GUI RPC protocol

BOINC uses the GUI RPC protocol to make the BOINC Manager communicate with the core client.

Note that the RPC server is the core client, and the RPC client is a GUI or add-on communicating with it (such as BOINC Manager). This may seem confusing. This terminology will be used on the rest of the page.

Basic structure

The protocol is based on XML, and it's strictly request-reply. The client sends requests to the server, and waits for a reply; the server never sends a reply without getting a request from the client first. Both requests and replies are terminated with the control character 0x03. Requests are inside <boinc_gui_rpc_request> elements, and replies from the client are inside <boinc_gui_rpc_reply> elements (in both cases there is a 0x03 byte after the closing tag).

Note that the core client (RPC server) doesn't support pipelining of requests (pipelining means sending a batch of multiple requests without waiting for a reply, then getting all the replies together; this improves latency). For compatibility, pipelining must not be used.

To terminate the RPC session, just close the connection on the client side. Warning: some protocols have a specific "quit" command for this. The GUI RPC protocol has a <quit/> command, but it has a completely different purpose: quitting the core client.

Common replies

If a command requires authentication but the client hasn't authenticated yet, the RPC server will reply

<boinc_gui_rpc_reply>
    <unauthorized/>
</boinc_gui_rpc_reply>

The client should be prepared to receive this in reply to any command.

Successful commands usually get the reply:

<boinc_gui_rpc_reply>
    <success/>
</boinc_gui_rpc_reply>

although individual commands may specify a different reply. For example, any command where the client is requesting information from the server would get that extra information in the command reply, instead of <success/>.

If a command isn't successful, the reply is:

<boinc_gui_rpc_reply>
    <error>human-readable error message</error>
</boinc_gui_rpc_reply>

A notable error message is "unrecognized op", which is returned if the server doesn't recognize a command. The client must be prepared to receive this even in reply to commands documented here, because older core client versions may not support all of them. In fact, it's more reliable to just send a command and fallback to an alternative if "unrecognized op" is returned, than to look at the version number to know what is supported.

Common XML elements

There are some XML elements (like <project>, <result>, <workunit>, and <app>) that are common to many command replies. Such elements are documented in this section.

The XML responses are relatively flat, and are parsed in one pass. The relationship between XML elements is determined by what was parsed before it, instead of based on the tree hierarchy like other XML formats do. For example, <result> elements that come after a particular <project> element are results that belong to that project; instead of those results being inside the <project> element.

Authentication

The RPC protocol allows the RPC client to authenticate itself using a password. Most RPC operations can only be done by an authenticated client. Some can be done without authentication, but only by a client running on the same machine.

Authentication on the RPC protocol is password-based, and negotiated with a challenge-response system. To initiate the authentication process, send an <auth1/> command:

<boinc_gui_rpc_request>
    <auth1/>
</boinc_gui_rpc_request>

The response will be the authentication challenge:

<boinc_gui_rpc_reply>
    <nonce>1198959933.057125</nonce>
</boinc_gui_rpc_reply>

The value of nonce is to be used as a salt with the password. It is randomly generated for each request. To calculate the response, concatenate the nonce and the password (nonce first), then calculate the MD5 hash of the result, i.e: md5(nonce+password). Finally, send an <auth2> request with the calculated hash, in hexadecimal format.

<boinc_gui_rpc_request>
    <auth2>
        <nonce_hash>d41d8cd98f00b204e9800998ecf8427e</nonce_hash>
    </auth2>
</boinc_gui_rpc_request>

The reply will be either <authorized/> or <unauthorized/>.

If the client hasn't authenticated yet, and it is connecting remotely (ie. not via localhost), <auth1/> is the only command that can be sent, and all the rest will return <unauthorized/>.