HP BL680c XenServer Software Development Kit Guide 4.1.0 - Page 12

Overview of the XenServer API enumeration of the templates on a XenServer installation for yourself then you can execute the "xe template-list" CLI command.) To get a list of templates via the API, we need to find the VM objects on the server that have their "is_a_template" field set to true. One way to do this by calling VM.get_all_records(session) where the session parameter is the reference we acquired from our Session.login_with_password call earlier. This call queries the server, returning a snapshot (taken at the time of the call) containing all the VM object references and their field values. (Remember that at this stage we are not concerned about the particular mechanisms by which the returned object references and field values can be manipulated in any particular client language: that detail is dealt with by our language-specific API bindings and described concretely in the following chapter. For now it suffices just to assume the existence of an abstract mechanism for reading and manipulating objects and field values returned by API calls.) Now that we have a snapshot of all the VM objects' field values in the memory of our client application we can simply iterate through them and find the ones that have their "is_a_template" set to true. At this stage let's assume that our example application further iterates through the template objects and remembers the reference corresponding to the one that has its "name_label" set to "Debian Etch 4.0" (one of the default Linux templates supplied with XenServer). 3.1.3. Installing the VM based on a template Continuing through our example, we must now install a new VM based on the template we selected. The installation process requires 2 API calls: • First we must now invoke the API call VM.clone(session, t_ref, "my first VM"). This tells the server to clone the VM object referenced by t_ref in order to make a new VM object. The return value of this call is the VM reference corresponding to the newly-created VM. Let's call this new_vm_ref. • At this stage the object referred to by new_vm_ref is still a template (just like the VM object referred to by t_ref, from which it was cloned). To make new_vm_ref into a VM object we need to call VM.provision(session, new_vm_ref). When this call returns the new_vm_ref object will have had its is_a_template field set to false, indicating that new_vm_ref now refers to a regular VM ready for starting. Note that the provision operation may take a few minutes, as it is as during this call that the template's disk images are created. In the case of the Debian template, the newly created disks are actually populated with a Debian root filesystem at this stage too. 3.1.4. Taking the VM through a start/suspend/resume/stop cycle Now we have an object reference representing our newly-installed VM, it is trivial to take it through a few lifecycle operations: • To start our VM we can just call VM.start(session, new_vm_ref) • After it's running, we can suspend it by calling VM.suspend(session, new_vm_ref); • and then resume it by calling VM.resume(session, new_vm_ref). • We can call VM.shutdown(session, new_vm_ref) to shutdown the VM cleanly. 3.1.5. Logging out Once an application is finished interacting with a XenServer Host it is good practice to call Session.logout(session). This invalidates the session reference (so it can not be used in subsequent API calls) and simultaneously deallocates server-side memory used to store the session object. 6