PrlJob_Wait Function

The PrlJob_Wait function allows to use asynchronous functions synchronously.

Syntax

PRL_RESULT PrlJob_Wait(
    PRL_HANDLE hJob, 
    PRL_UINT32 msecs
);

File

PrlApiCore.h

Parameters

hJob

A handle of type PHT_JOB identifying the job.

msecs

Timeout in milliseconds. The timeout must be long enough for the job to complete. The optimal value is determined empirically. For an infinite timeout, use the UINT_MAX value.

Returns

PRL_RESULT. Possible values:

PRL_ERR_INVALID_ARG - an invalid PHT_JOB handle was passed.

PRL_ERR_TIMEOUT - the specified timeout limit was reached.

PRL_ERR_SUCCESS - operation completed successfully.

Remarks

The function should be called immediately after the corresponding asynchronous function call. It suspends the main thread for the specified number of milliseconds and waits for the job to complete. If the job completes before the timeout value is reached, the function returns and the execution of the main thread continues normally. If the function times out, it returns an error. On function return, the job object will not be destroyed and could be queried until its destruction with the call to PrlHandle_Free.

Example

// Log in to Virtuozzo Service.
// This is an asynchronous call.
// Returns a handle to the Job object.
PRL_HANDLE hJob = PrlSrv_Login(
    hServer, "10.30.23.105", "miket", "1q2w3e",
    0, 0, 0, PRL_SECURITY_LEVEL::PSL_LOW_SECURITY);

// Wait for the Job object to receive the results of the operation.
ret = PrlJob_Wait( hJob, 1000 );
if (PRL_FAILED(ret))
{
    printf("PrlJob_Wait returned with error (%s)\n",
        PRL_RESULT_TO_STRING(ret));
    return -1;
}

// Get the results from the Job object.
PRL_RESULT nJobResult;
ret = PrlJob_GetRetCode( hJob, &nJobResult );
if (PRL_FAILED( nJobResult ))
{
    printf("login job returned with error (%s)\n",
        PRL_RESULT_TO_STRING( nJobResult ));
    return -1;
}
else
    printf( "Login succeeded.\n" );

// Delete the Job handle.
PrlHandle_Free( hJob );

Links

PHT_JOB, Example