T(Incomplete)?

GUI RPC protocol

The GUI RPC protocol lets GUIs like 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 anything without getting a request from the client first. Both requests and replies are terminated with the control character 0x03.

Self-closing tags must not have a space before the slash, or current client and server will not parse it correctly. For example, send <authorized/>, not <authorized />.

Requests are inside <boinc_gui_rpc_request> elements, and replies from the RPC server are inside <boinc_gui_rpc_reply> elements (in both cases there is a 0x03 byte after the closing tag). The current RPC server implementation doesn't require the <boinc_gui_rpc_request> tag, which is handy for debugging (you can connect via ​netcat and just type <auth1/>); however, clients must not rely on this, and must always send the <boinc_gui_rpc_request> root tag.

The current 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: telling the core client to quit!

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, especially those that retrieve data, may return the requested information 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>

Clients should not try to parse the error message. The current gui_rpc_client.cpp library sometimes tries to parse errors, but this is very unreliable, since the message wording can change (and has changed) between RPC server versions. (r15942 even changed "unrecognized op")

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 lowercase 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/>.

Common XML elements

There are some XML elements (like <project>, <result>, <workunit>, and <app>) that are common to many command replies. Such elements are will be 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. They won't be inside the <project> element.