Synchronous Functions

The Parallels C API provides synchronous and asynchronous functions. Synchronous functions run in the same thread as the caller. When a synchronous function is called it completes executing before returning control to the caller. Synchronous functions return PRL_RESULT, which is a integer indicating success or failure of the operation. Consider the PrlSrv_Create function. The purpose of this function is to obtain a handle of type PHT_SERVER. The handle is required to access most of the functionality within the Parallels C API. The syntax of PrlSrv_Create is as follows:

PRL_RESULT PrlSrv_Create(

    PRL_HANDLE_PTR handle

);

The following is an example of the PrlSrv_Create function call:

// Declare a handle variable.

PRL_HANDLE hServer = PRL_INVALID_HANDLE;

// Call the PrlSrv_Create to obtain the handle.

PRL_RESULT res = PrlSrv_Create(&hServer);

// Examine the function return code.

// PRL_FAILED is a macro that evaluates a variable of type PRL_RESULT.

// A return value of True indicates success; False indicates failure.

if (PRL_FAILED(res))

{

    printf("PrlSrv_Create returned error: %s\n",

        prl_result_to_string(res));

    exit(ret);

}