As a demonstration, let's select a task and see how we can use this guide to find the technical information that will help us to implement it. We will use the task of starting a virtual machine. Follow these steps:
- Everything in the Parallels C API begins with a handle. If you want to perform a task, you need to know the name of the handle that provides the corresponding functionality (you can browse the Functions by Handle chapter and read the summary for each handle). In our case, the name of the handle is PHT_VIRTUAL_MACHINE.
- Read the handle description and find the information about how to obtain it. That's what it says: "A handle is obtained from the PHT_JOB object returned by the PrlSrv_GetVmList function." Follow the link to the PrlSrv_GetVmList function.
- When the topic describing the PrlSrv_GetVmList function displays, you will see a detailed description of the function and a sample demonstrating how to use it. The function accepts a handle of type PHT_SERVER as parameter. Follow its link to see how it is obtained (or see the included code sample). The PHT_JOB object that the PrlSrv_GetVmList function returns will contain the PHT_VIRTUAL_MACHINE handle that we want. The information on how to extract the handle from the Job object is included in the function description. You can also follow the PHT_JOB link and see more info about it if you wish.
- Now that you know how to obtain the PHT_VIRTUAL_MACHINE handle, go back to its topic (use the document viewer options or click the link if it's available on the current page).
- In the PHT_VIRTUAL_MACHINE function list, find the PrlVm_Start function (functions are listed alphabetically). This is the function that starts a virtual machine. Follow its link and see the syntax, parameters, and return codes. As you can see, the function accepts a single parameter, which is a handle of type PHT_VIRTUAL_MACHINE that we've obtained in the previous steps. You now have all the information needed to implement the task in your program.
Once again, if you are just starting with the Parallels Virtualization SDK, your best source of information is Parallels Virtualization SDK Programmer's Guide. It explain the concepts and provides descriptions and step-by-step instructions on how to use the API to perform the most common tasks. Once you are familiar with the basic principles of the SDK design, you will find it very easy to work with both guides and the API itself.