IIapi_wait() Function—Block Application Control Until Outstanding Operation Completes or User-defined Timeout Expires
The IIapi_wait() function enables an application to give control to OpenAPI until an outstanding task completes. Because OpenAPI is asynchronous and many operating systems do not provide an interrupt mechanism for receiving incoming messages, IIapi_wait() provides a way to yield the flow of control to OpenAPI. By occasionally calling IIapi_wait(), an application ensures that it will receive incoming messages from the server.
IIapi_wait() can be used in two programming styles: synchronous and asynchronous. To support the synchronous style of programming, the application can invoke an OpenAPI function and call IIapi_wait() until the application notes the completion of the function (by checking gp_completed) before calling the next function.
In an asynchronous application, the application code itself is event-driven (the events being OpenAPI function completions). Once the first function is invoked, the application calls IIapi_wait() in a continuous top-level loop to drive all subsequent functions asynchronously.
This function has the following syntax:
II_VOID IIapi_wait (IIAPI_WAITPARM *waitParm);
typedef struct _IIAPI_WAITPARM
{
II_LONG wt_timeout;
II_API_STATUS wt_status;
} IIAPI_WAITPARM;
This function has the following parameters:
wt_timeout
Type: input
(Optional.) Indicates the maximum time in milliseconds to wait for the outstanding operations to complete. If timeout is not desired, this parameter is -1.
Support for timeouts is platform-dependent. If timeouts are not supported, all values are treated the same as -1.
wt_status
Type: output
Specifies the status of the function upon its return. Its value is one of the following:
• IIAPI_SUCCESS
• IIAPI_FAILURE