ctaQueryWaitObjects

Obtains an operating-system-specific array of wait objects that Natural Access is managing internally. This function is used when the application will be managing wait objects.

Prototype

DWORD ctaQueryWaitObjects ( CTAQUEUEHD ctaqueuehd, CTA_WAITOBJ waitobjs[], unsigned size, unsigned *count)

Argument	Description
ctaqueuehd	Context handle.
waitobjs	Pointer to the CTA_WAITOBJ array that will be filled in with the wait objects. For Windows, the type is: typedef MUX_HANDLE CTA_WAITOBJ; For UNIX, the type is: struct pollhd { int fd; int events; int revents; } typedef struct pollhd CTA_WAITOBJ;
size	The size of the CTA_WAITOBJ array passed in. Set to zero (0) to determine the number of wait objects being used by Natural Access.
count	Pointer to the returned number of the CTA_WAITOBJ array elements.

Return values

Return value	Description
SUCCESS
CTAERR_INVALID_CTAQUEUEHD
CTAERR_NOT_INITIALIZED	Natural Access is not initialized. Call ctaInitialize first.

Events

None.

Details

This function obtains an operating-system-specific array of 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 the CTAEVN_UPDATE_WAITOBJS event. Applications receive this event 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.

To create an array of wait objects

Call ctaQueryWaitObjects with a size value of zero (0). This returns the actual number of wait objects being used by Natural Access in the count field without actually returning the wait objects themselves.
Allocate an array of application-maintained wait objects that will be large enough to hold both the Natural Access wait objects and the application-specific wait objects.
Call ctaQueryWaitObjects again to retrieve the Natural Access wait objects. Place these wait objects into the newly allocated array. Place the Natural Access wait objects at the beginning of the array. The remaining wait objects are available for use by the application.

To process signals on a wait object in the array:

Determine if the wait object has been classified (by you) as a Natural Access wait object.
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.

Example

#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 */
}