Obtains an operating-system-specific array of the wait objects that Natural Access is managing internally. This function is used when the application is managing wait objects.
DWORD ctaQueryWaitObjects ( CTAQUEUEHD ctaqueuehd, CTA_WAITOBJ *waitobjs[], unsigned size, unsigned *count)
|
Argument |
Description |
|
ctaqueuehd |
Context handle. |
|
waitobjs |
Pointer to the CTA_WAITOBJ array that is filled in with the wait objects. For Windows, the type is: typedef MUX_HANDLE CTA_WAITOBJ; For UNIX, the type is: struct pollhd |
|
size |
The size of the CTA_WAITOBJ array passed. Set to zero (0) to determine the number of wait objects used by Natural Access. |
|
count |
Pointer to the returned number of the CTA_WAITOBJ array elements. |
|
Return value |
Description |
|
SUCCESS |
|
|
CTAERR_INVALID_CTAQUEUEHD |
An invalid queue handle was passed as an argument to a function, or the queue was destroyed by another thread. |
|
CTAERR_NOT_INITIALIZED |
Natural Access is not initialized. Call ctaInitialize first. |
ctaQueryWaitObjects obtains an operating-system-specific array of the wait objects that Natural Access is managing internally. If the application is managing its own wait objects, the application needs to be notified about Natural Access wait objects so that the Natural Access wait objects and the application-specific wait objects can be passed to the operating system wait functions.
If the application is managing its own wait objects and waiting for operating system events, call ctaQueryWaitObjects immediately after ctaCreateQueue, and when the application receives CTAEVN_UPDATE_WAITOBJS. Applications receive CTAEVN_UPDATE_WAITOBJS only if they specify the CTA_NOTIFY_UPDATE_WAITOBJS flag in the ctaflags field of the initparms parameter to ctaInitialize. If this flag is not specified, the list of Natural Access wait objects may not be complete.
The application must manage all wait objects including those of Natural Access. This requires an application to:
Dynamically create an array of wait objects to contain both Natural Access and application-specific wait objects.
Identify when a Natural Access wait object is signaled and notify Natural Access accordingly.
Complete the following steps to create an array of wait objects:
|
Step |
Action |
|
1 |
Call ctaQueryWaitObjects with a size value of zero (0). This call returns the actual number of wait objects used by Natural Access in the count field without actually returning the wait objects themselves. |
|
2 |
Allocate an array of application-maintained wait objects large enough to hold both the Natural Access wait objects and the application-specific wait objects. |
|
3 |
Call ctaQueryWaitObjects again to retrieve the Natural Access wait objects. Place these wait objects at the beginning of the newly allocated array. The remaining wait objects are available for use by the application. |
Complete the following steps to process signals on a wait object in the array:
|
Step |
Action |
|
1 |
Determine if you classified the wait object as a Natural Access wait object. |
|
2 |
If so, immediately call ctaWaitEvent with a timeout of zero (0). Wait events may return with no event if the event is absorbed internally by Natural Access. |
Note: Do not use ctaQueryWaitObjects if you register wait objects with ctaRegisterWaitObject.
Refer to Using wait objects for more information.
#include "nmstypes.h"
#include "ctademo.h"
#include "ctadef.h"
CTA_WAITOBJ *waitobjs;
unsigned numwaitobjs;
void query_ctaccess_wait_objects(CTAQUEUEHD ctaqueuehd)
{
DWORD ret;
/* Find out how many Natural Access wait objects there are: */
if ((ret = ctaQueryWaitObjects( ctaqueuehd, NULL, 0, &numwaitobjs))
!= SUCCESS)
{
exit( -1 );
}
else
{
unsigned size = sizeof(CTA_WAITOBJ)*numwaitobjs;
/* Allocate one more than the number returned by Natural Access. The
additional one (waitobjs[0]), will be used for the application's
stdin wait object */
waitobjs = (CTA_WAITOBJ *)malloc(size + sizeof(CTA_WAITOBJ));
if (waitobjs == NULL)
exit( -1 );
/* Get the Natural Access wait objects in an array */
if ((ret = ctaQueryWaitObjects( ctaqueuehd, &(waitobjs[1]), size,
&numwaitobjs)) != SUCCESS)
{
exit( -1 );
}
}
numwaitobjs++; /* Total number of wait objects include app wait object */
}