1.3.
WIRE PROTOCOL FOR REMOTE API CALLS
CHAPTER 1.
INTRODUCTION
<name>John</name>
<value><double>1.2</double></value>
</member>
</struct>
</value>
•
our
Void
type is transmitted as an empty string.
1.3.1
Note on References vs UUIDs
References are opaque types — encoded as XML-RPC strings on the wire — understood only by
the particular server which generated them. Servers are free to choose any concrete representation
they find convenient; clients should not make any assumptions or attempt to parse the string
contents. References are not guaranteed to be permanent identifiers for objects; clients should not
assume that references generated during one session are valid for any future session. References
do not allow objects to be compared for equality. Two references to the same object are not
guaranteed to be textually identical.
UUIDs are intended to be permanent names for objects. They are guaranteed to be in the OSF
DCE UUID presentation format (as output by
uuidgen
. Clients may store UUIDs on disk and
use them to lookup objects in subsequent sessions with the server. Clients may also test equality
on objects by comparing UUID strings.
The API provides mechanisms for translating between UUIDs and opaque references. Each class
that contains a UUID field provides:
•
A “
get by uuid
” method that takes a UUID,
u
, and returns an opaque reference to the
server-side object that has UUID=
u
;
•
A
get uuid
function (a regular “field getter” RPC) that takes an opaque reference,
r
, and
returns the UUID of the server-side object that is referenced by
r
.
1.3.2
Return Values/Status Codes
The return value of an RPC call is an XML-RPC
Struct
.
•
The first element of the struct is named
Status
; it contains a string value indicating whether
the result of the call was a “
Success
” or a “
Failure
”.
If
Status
was set to
Success
then the Struct contains a second element named
Value
:
•
The element of the struct named
Value
contains the function’s return value.
In the case where
Status
is set to
Failure
then the struct contains a second element named
ErrorDescription
:
•
The element of the struct named
ErrorDescription
contains an array of string values. The
first element of the array is an error code; the remainder of the array are strings representing
error parameters relating to that code.
For example, an XML-RPC return value from the
host.get resident VMs
function above may
look like this:
<struct>
<member>
<name>Status</name>
<value>Success</value>
</member>
8