# dispRegisterWaitObject

Used by services to register wait objects and their respective processing functions with a Natural Access queue.

#### Prototype

DWORD dispRegisterWaitObject (CTAQUEUEHD ctaqueuehd, CTA_WAITOBJ *waitobj, CTA_WAITFN waitfn, void *arg)

Argument | Description
ctaqueuehd | Handle returned by ctaCreateQueue.
waitobj | Pointer to wait object to register.
waitfn | Function to call when a wait object needs servicing. Typically this is xxxFetchAndProcess when handling events from the managed resource.
arg | Pointer to the argument to be passed to a wait function when signaled. Typically this is a queuecontext or mgrcontext.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | Function argument has an invalid value, or a required pointer argument is NULL.
CTAERR_OUT_OF_RESOURCES | Unable to find free space in internal tables.
CTAERR_DUPLICATE_CTAWAITOBJ | Already registered wait object was passed as an argument to ctaRegisterWaitObject.
CTAERR_OUT_OF_MEMORY | Unable to allocate memory.

#### Details

dispRegisterWaitObject is used by services and service managers to register wait objects with the Natural Access queue. Wait objects must be handles to objects that can be waited upon using an operating system specific wait function (poll in Unix, WaitForMultipleObjects in Windows). They are waited upon either by ctaWaitEvent or by the application. Requests for servicing cause the dispatcher to invoke the wait function passed as an argument to dispRegisterWaitObject. dispRegisterWaitObject is invoked with waitobj and arg as arguments. If the function results in the generation of a Natural Access event, it should call dispQueueEvent to place the event in the dispatcher event queue or in the application event queue.

The wait object structure is operating system dependent. For UNIX it is a pollfd structure with the fd field identifying the muxable handle. For Windows, the wait object is the manual reset event object.

#ifdef UNIX
#include <stropts.h>
#include <poll.h>
typedef struct pollfd CTA_WAITOBJ;

The signature for xxxFetchAndProcess is:

DWORD xxxFetchAndProcess (CTAQUEUEHD ctaqueuehd, CTA_WAITOBJ *waitobj, void *arg)

Argument | Description
ctaqueuehd | Handle returned by ctaCreateQueue.
waitobj | Pointer to the newly created wait object.
arg | Pointer to a data structure used to help process the event. Typically this is a queuecontext or mgrcontext.

#### See also

dispUnregisterWaitObject, xxxAttachServiceManager, xxxOpenServiceManager