XenServer Software Development Kit Guide 4.1.0

Using the API

session.xenapi.VM.start(vm, False, False)

All API calls are by default synchronous and will not return until the operation has completed or failed. For

example in the case of VM.start the call does not return until the VM has started booting.

Note

When the VM.start call returns the VM will be booting. To determine when the booting has finished,

wait for the in-guest agent to report internal statistics through the VM_guest_metrics object

4.1.5. Using Tasks to manage asynchronous operations

To simplify managing operations which take quite a long time (e.g. VM.clone and VM.copy) functions are

available in two forms: synchronous (the default) and asynchronous. Each asynchronous function returns

a reference to a task object which contains information about the in-progress operation including:

• whether it is pending; has succeeded or failed;

• progress in the range 0-1; and

• the result or error code returned by the operation.

An application which wanted to track the progress of a VM.clone operation and display a progress bar

would have code like the following:

vm = session.xenapi.VM.get_by_name_label('my vm')

task = session.xenapi.Async.VM.clone(vm)

while session.xenapi.Task.get_status(task) == "pending":

progress = session.xenapi.Task.get_progress(task)

update_progress_bar(progress)

time.sleep(1)

session.xenapi.Task.destroy(task)

Note

Note that a well-behaved client should remember to delete tasks created by asynchronous oper-

ations when it has finished reading the result or error. If the number of tasks exceeds a built-in

threshold then the server will delete the oldest of the completed tasks.

4.1.6. Subscribing to and listening for events

With the exception of the task and metrics classes, whenever an object is modified the server generates

an event. Clients can subscribe to this event stream on a per-class basis and receive updates rather than

resorting to frequent polling. Events come in three types:

• add: generated when an object has been created;

• del: generated immediately before an object is destroyed; and

• mod: generated when an object's field has changed.