Changes between Version 4 and Version 5 of GuiRpcProtocol

Timestamp:

May 15, 2008, 5:51:41 PM (16 years ago)

Author:

Nicolas

Comment:

Some more work on this documentation. Added a whole new section with the basic protocol structure (moving some information from the introduction).

GuiRpcProtocol

@@ -2 +2 @@
 = GUI RPC protocol =
 
-BOINC uses the GUI RPC protocol to make the BOINC Manager communicate with the core client. The protocol is based on XML. Both requests and responses are terminated with the control character `0x03`. Requests are inside `<boinc_gui_rpc_request>` tags, and replies from the client are inside `<boinc_gui_rpc_reply>` tags. A response is never sent without getting a request first.
+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). It may seem confusing. This terminology will be used on the rest of the page.
+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; a reply is never sent back by the server without getting a request 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 %x03 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.
+
+If a command requires [#auth authentication] but the client hasn't authenticated yet, the RPC server will reply
+{{{
+#!xml
+<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:
+{{{
+#!xml
+<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:
+{{{
+#!xml
+<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.
 
 == Authentication == #auth
@@ -10 +43 @@
 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 based on a challenge-response system. To initiate the authentication process, send an <code><auth1/></code> command:
+Authentication on the RPC protocol is password-based, and negotiated with a challenge-response system. To initiate the authentication process, send an {{{<auth1/>}}} command:
 {{{
 #!xml