# 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 );
}
}