XML-RPC
One of the reasons the remote framework currently uses XML-RPC for its transfer protocol is that XML-RPC provides many of the network transfer protocol requirements as-is. Readers are encouraged to familiarize themselves with the XML-RPC specification before reading this section.
Administrative methods
Remote calls to the administrative methods are encoded as standard XML-RPC function requests. The name of the administrative method is used as the name of the XML-RPC function, and the remote method's parameter array is encoded as the XML-RPC parameter list. The remote method can be expected to return a single value, which will be deserialized into the logical type model as defined by the XML-RPC specification.
Dispatched methods
Calling a dispatched method is slightly more involved than
calling an administrative method, and is therefore handled
slightly differently. For one, calling a dispatched method
requires a valid connection as set up by
the createSession
administrative method. Since
XML-RPC connections are stateless, this creates the need for
an extra, implicit parameter for each dispatched method call.
(This extra parameter informs the data server which active
connection is making the requested call.) Further, since the
namespace for administrative and dispatched methods are
distinct, we cannot call a dispatched method directly without
the possibility of a namespace clash between the two types of
methods.
For all of these reasons, dispatched method calls are made
with the special dispatch
XML-RPC function name.
The first two elements of the XML-RPC parameter list are,
respectively, the session key of the active connection
(returned by the createSession
method), and the
name of the dispatched method to execute. The parameters to
the dispatched method are then encoded as the remaining
XML-RPC parameters, in order.
As with administrative methods, the caller can expect the result to be a single value, which can be translated into the logical type model as defined by the XML-RPC specification.
Limitations
Null values
The XML-RPC does not define a way to represent null values in
an XML-RPC request or response. Since the logical type model
includes null values, we need a way of representing them in an
XML-RPC stream. We do so by using a special string value:
"*([-NULL-])*
". All client libraries using the
XML-RPC transport protocol should encode null values as this
string, and should turn any instances of this string they see
into a null value.
You might be asking yourself, what if I need to send the
string "*([-NULL-])*
"? Unfortunately, you are
currently out of luck.
Integer values
The XML-RPC specification states that integer XML-RPC values are limited to 32 bits. As stated in the logical type model, this means that you cannot use the XML-RPC transport protocol to call remote methods which require an integer of a larger size.