HP BL680c XenServer Software Development Kit Guide 4.1.0 - Page 22

Using the API

16

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.

Section	Page
XenServer Software Development Kit Guide	1
Table of Contents	4
Chapter 1. Introduction	7
Chapter 2. Getting Started	8
2.1. System Requirements and Preparation	8
2.2. Downloading	8
2.3. Installation	8
2.4. What's new	8
2.5. Content Map	8
2.6. Building Samples for the Linux Platform	9
2.7. Building Samples for the Windows Platform	9
2.8. Running the CLI	9
2.8.1. Tab Completion	9
2.9. Accessing SDK reference	9
Chapter 3. Overview of the XenServer API	11
3.1. Getting Started with the API	11
3.1.1. Authentication: acquiring a session reference	11
3.1.2. Acquiring a list of templates to base a new VM installation on	11
3.1.3. Installing the VM based on a template	12
3.1.4. Taking the VM through a start/suspend/resume/stop cycle	12
3.1.5. Logging out	12
3.1.6. \	13
3.2. Object Model Overview	13
3.3. Working with VIFs and VBDs	15
3.3.1. Creating disks and attaching them to VMs	15
3.3.1.1. Creating a new blank disk image	16
3.3.1.2. Attaching the disk image to a VM	16
3.3.1.3. Hotplugging the VBD	17
3.3.2. Creating and attaching Network Devices to VMs	17
3.3.3. Host configuration for networking and storage	17
3.3.3.1. Host storage configuration: PBDs	18
3.3.3.2. Host networking configuration: PIFs	18
3.4. Exporting and Importing VMs	18
3.5. Where to look next	19
Chapter 4. Using the API	20
4.1. Anatomy of a typical application	20
4.1.1. Choosing a low-level transport	20
4.1.2. Authentication and session handling	20
4.1.3. Finding references to useful objects	21
4.1.4. Invoking synchronous operations on objects	21
4.1.5. Using Tasks to manage asynchronous operations	22
4.1.6. Subscribing to and listening for events	22
4.2. Language bindings	23
4.2.1. C	23
4.2.2. C#	24
4.2.3. Python	24
4.2.4. Command Line Interface (CLI)	25
4.3. Complete application examples	25
4.3.1. Simultaneously migrating VMs using XenMotion	25
4.3.2. Cloning a VM via the XE CLI	28
Chapter 5. XenServer API extensions	30
5.1. VM console forwarding	30
5.1.1. Retrieving VNC consoles via the API	30
5.1.2. Disabling VNC forwarding for Linux VM	31
5.2. Paravirtual Linux installation	32
5.2.1. Red Hat Enterprise Linux 4.1/4.4	32
5.2.2. Red Hat Enterprise Linux 4.5/5.0	32
5.2.3. SUSE Enterprise Linux 10 SP1	33
5.2.4. CentOS 4.5/5.0	33
5.3. Adding Xenstore entries to VMs	33
5.4. Security enhancements	33
5.5. Advanced settings for network interfaces	34
5.5.1. ethtool settings	34
5.5.2. Miscellaneous settings	35
5.6. Internationalization for SR names	35
5.7. Hiding objects from XenCenter	36

HP BL680c XenServer Software Development Kit Guide 4.1.0 - Page 22

Using Tasks to manage asynchronous operations, 4.1.6. Subscribing to and listening for events

Page 22 highlights