1.3.
WIRE PROTOCOL FOR REMOTE API CALLS
CHAPTER 1.
INTRODUCTION
1.3
Wire Protocol for Remote API Calls
API calls are sent over a network to a Xen-enabled host using the XML-RPC protocol. In this
Section we describe how the higher-level types used in our API Reference are mapped to primitive
XML-RPC types.
In our API Reference we specify the signatures of API functions in the following style:
(ref_vm Set)
VM.get_all()
This specifies that the function with name
VM.get all
takes no parameters and returns a Set of
ref vm
s. These types are mapped onto XML-RPC types in a straight-forward manner:
•
Floats, Bools, DateTimes and Strings map directly to the XML-RPC
double
,
boolean
,
dateTime.iso8601
, and
string
elements.
•
all “
ref
” types are opaque references, encoded as the XML-RPC’s
String
type. Users of
the API should not make assumptions about the concrete form of these strings and should
not expect them to remain valid after the client’s session with the server has terminated.
•
fields named “
uuid
” of type “
String
” are mapped to the XML-RPC
String
type. The
string itself is the OSF DCE UUID presentation format (as output by
uuidgen
, etc).
•
ints are all assumed to be 64-bit in our API and are encoded as a string of decimal digits
(rather than using XML-RPC’s built-in 32-bit
i4
type).
•
values of enum types are encoded as strings. For example, a value of
destroy
of type
on normal exit
, would be conveyed as:
<value><string>destroy</string></value>
•
for all our types,
t
, our type
t Set
simply maps to XML-RPC’s
Array
type, so for example
a value of type
String Set
would be transmitted like this:
<array>
<data>
<value><string>CX8</string></value>
<value><string>PSE36</string></value>
<value><string>FPU</string></value>
</data>
</array>
•
for types
k
and
v
, our type
(k, v) Map
maps onto an XML-RPC struct, with the key as
the name of the struct. Note that the
(k, v) Map
type is only valid when
k
is a
String
,
Ref
, or
Int
, and in each case the keys of the maps are stringified as above. For example,
the
(String, double) Map
containing a the mappings Mike
→
2.3 and John
→
1.2 would
be represented as:
<value>
<struct>
<member>
<name>Mike</name>
<value><double>2.3</double></value>
</member>
<member>
7
