|
|
|
|
The C API is a set of functions that operate on objects. Objects are not accessed directly. Instead, references to these objects are used. These references are known as handles .
Handle Types
A
PRL_HANDLE
type is the only type of handle in the C API. It is a pointer to an integer, and it is defined in
PrlTypes.h
.
A
PRL_HANDLE
can reference any type of object within the API. The type of object that a
PRL_HANDLE
references determines the
PRL_HANDLE
type. A list of handle types can be found in the
PRL_HANDLE_TYPE
enumeration in
PrlEnums.h
.
A handles' type can be extracted using the
PrlHandle_GetType
function. A string representation of the handle type can then be obtained using the
handle_type_to_string
function
.
Obtaining a Handle
A handle is usually obtained by calling a function that operate on another (we may call it a "parent") handle. For example, a virtual machine handle is obtained by calling a function that operates on the server handle. A virtual device handle is obtained by calling a function that operates on the virtual machine handle, and so forth. The Parallels C API Reference guide contains a description of every available handle and explains how each particular handle can be obtained. The examples in this guide also demonstrate how to obtain handles of different types.
Freeing a Handle
Handles used within the API are reference counted. Each handle contains a count of the number of references to it held by other objects. A handle stays in memory for as long as the reference count is greater than zero. A client application is responsible for freeing any handles that are no longer required. A handle can be freed using the
PrlHandle_Free
function. The function decreases the reference count by one. When the count reaches zero, the object is destroyed. Failing to free a handle after it has been used will result in a memory leak.
Multithreading
Handles used within the Parallels API are thread safe. They can be used in multiple threads at the same time. To maintain the proper reference counting, the count should be increased each time a handle is passed to another thread by calling the
PrlHandle_AddRef
function. If this is not done, freeing a handle in one thread may destroy it while other threads are still using it.
Example
The following code snippet demonstrates how to obtain a handle, how to determine its type, and how to free it when it's no longer needed. The code is a part of the bigger example that demonstrates how to log in to a Parallels Service (the full example is provided later in this guide).
PRL_HANDLE hServer;
PRL_RESULT ret;
ret = PrlSrv_Create(&hServer);
if (PRL_FAILED(ret))
{
fprintf(stderr, "PrlSvr_Create failed, error: %s",
prl_result_to_string(ret));
PrlHandle_Free(hServer);
return -1;
}
// Get hServer handle type.
PRL_HANDLE_TYPE nHandleType;
PrlHandle_GetType(hServer, &nHandleType);
printf("Handle type: %s\n",
handle_type_to_string(nHandleType));
// Free the handle when it is no longer needed.
PrlHandle_Free(hServer);
