1.4.
MAKING XML-RPC CALLS
CHAPTER 1.
INTRODUCTION
<member>
<name>Value</name>
<value>
<array>
<data>
<value>81547a35-205c-a551-c577-00b982c5fe00</value>
<value>61c85a22-05da-b8a2-2e55-06b0847da503</value>
<value>1d401ec4-3c17-35a6-fc79-cee6bd9811fe</value>
</data>
</array>
</value>
</member>
</struct>
1.4
Making XML-RPC Calls
1.4.1
Transport Layer
The following transport layers are currently supported:
•
HTTP/S for remote administration
•
HTTP over Unix domain sockets for local administration
1.4.2
Session Layer
The XML-RPC interface is session-based; before you can make arbitrary RPC calls you must login
and initiate a session. For example:
session_id
session.login_with_password(string uname, string pwd)
Where
uname
and
password
refer to your username and password respectively, as defined by the
Xen administrator. The
session id
returned by
session.login with password
is passed to
subequent RPC calls as an authentication token.
A session can be terminated with the
session.logout
function:
void
session.logout(session_id session)
1.4.3
Synchronous and Asynchronous invocation
Each method call (apart from methods on “Session” and “Task” objects and “getters” and “set-
ters” derived from fields) can be made either synchronously or asynchronously. A synchronous
RPC call blocks until the return value is received; the return value of a synchronous RPC call is
exactly as specified in Section 1.3.2.
Only synchronous API calls are listed explicitly in this document. All asynchronous versions are
in the special
Async
namespace. For example, synchronous call
VM.clone(...)
(described in
Chapter 2) has an asynchronous counterpart,
Async.VM.clone(...)
, that is non-blocking.
Instead of returning its result directly, an asynchronous RPC call returns a
task-id
; this identifier
is subsequently used to track the status of a running asynchronous RPC. Note that an asychronous
call may fail immediately, before a
task-id
has even been created—to represent this eventuality,
the returned
task-id
is wrapped in an XML-RPC struct with a
Status
,
ErrorDescription
and
Value
fields, exactly as specified in Section 1.3.2.
The
task-id
is provided in the
Value
field if
Status
is set to
Success
.
The RPC call
(ref_task Set)
Task.get_all(session_id s)
9