ctaRegisterWaitObject

Registers a wait object so that Natural Access waits on application wait objects and Natural Access internal objects. Use this function when Natural Access is managing wait objects.

Prototype

DWORD ctaRegisterWaitObject ( CTAQUEUEHD ctaqueuehd, CTA_WAITOBJ *waitobj, CTA_WAITFN waitfn, void *arg, unsigned priority)

Argument

Description

ctaqueuehd

Context handle.

waitobj

Pointer to the handle of the application wait object.

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;

waitfn

Callback function to be called when waitobj wait object is signaled. Refer to the Details section for the wait function prototype.

arg

Pointer to the argument to be passed to the callback function waitfn.

priority

Relative priority of the wait object compared to Natural Access wait objects. Refer to the Details section for the valid priorities.


Return values

Return value

Description

SUCCESS

 

CTAERR_DUPLICATE_WAITOBJ

Attempted to register a wait object that was already registered.

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.


Details

ctaRegisterWaitObject registers a wait object with Natural Access so that ctaWaitEvent waits on application wait objects and Natural Access internal objects. A wait object can be registered only once with Natural Access. An attempt to register a wait object a second time returns CTAERR_DUPLICATE_WAITOBJ.

Natural Access calls the function waitfn. Whenever the wait object waitobj is signaled, Natural Access passes the argument arg to the function waitfn. Natural Access gives up the queue lock before calling the function so that the function can call other Natural Access functions without a deadlock. On return from the function, Natural Access reacquires the queue lock.

Note: ctaDestroyQueue and ctaWaitEvent cannot be called from inside the function waitfn.

The function prototype is:

DWORD NMSSTDCALL yourwaitfn ( CTAQUEUEHD ctaqueuehd, CTA_WAITOBJ *waitobj, void *arg)

priority can be specified as either of the following values:

Value

Description

CTA_PRIORITY_HIGH

Natural Access checks the application's wait objects before checking its own wait objects.

CTA_PRIORITY_NORMAL

Natural Access checks its own wait objects before checking the application's wait objects.


Note: Do not use ctaRegisterWaitObject if the application is managing and waiting on wait objects outside of ctaWaitEvent (in ctaInitialize, ctaflags field in initparms is set to CTA_NOTIFY_UPDATE_WAITOBJS).

Call ctaUnregisterWaitObject to unregister the wait object.

Refer to Using wait objects for more information.

See also

ctaQueryWaitObjects

Example

#include "nmstypes.h"
#include "ctademo.h"
#include "ctadef.h"
extern DWORD NMSSTDCALL MyKbdEventHandler( CTAQUEUEHD  ctaqueuehd,
                                           CTA_WAITOBJ *waitobj,
                                           void       *arg);

CTA_WAITOBJ waitobj;
CTAHD kbdhd;

void register_stdin_waitobj(CTAQUEUEHD ctaqueuehd)
{
    DWORD ret;

#if defined (WIN32)
    /* Get a handle for stdin */
    HANDLE hConsoleInput = GetStdHandle( STD_INPUT_HANDLE ) ;
    if (hConsoleInput == INVALID_HANDLE_VALUE)
        exit( -1 );
#endif

#if defined (WIN32)
    waitobj = hConsoleInput;
#elif defined (UNIX)
    /* Use the STDIN file descriptor */
    waitobj.fd = STDIN_FILENO;
    waitobj.events = POLLIN;
    waitobj.revents = 0;
#endif

    /* Register the wait object */
    if ((ret=ctaRegisterWaitObject(ctaqueuehd, 
                                   &waitobj, 
                                   MyKbdEventHandler,
                                   (void *)kbdhd,
                                   CTA_PRIORITY_NORMAL)) != SUCCESS)
    {
        exit( -1 );
    }
}