Handles

The Parallels 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

PRL_HANDLE is the only handle type used in the C API. It is a pointer to an integer and it is defined in PrlTypes.h.

PRL_HANDLE can reference any type of object within the API. The type of object that 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 belonging to another handle, which we may call a "parent". 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 type can be obtained. The examples in this guide also demonstrate how to obtain handles of different types.

Freeing a Handle

Parallels API handles 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 program is responsible for freeing any handles that are no longer needed. 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

Parallels API handles 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_INVALID_HANDLE;

PRL_RESULT ret;

ret = PrlSrv_Create(&hServer);

if (PRL_FAILED(ret))

{

fprintf(stderr, "PrlSvr_Create failed, error: %s",

prl_result_to_string(ret));

return PRL_ERR_FAILURE;

}

// Determine the type of the hServer handle.

PRL_HANDLE_TYPE nHandleType;

PrlHandle_GetType(hServer, &nHandleType);