# dispQueueEvent

Queues events to other services or to the application.

#### Prototype

DWORD dispQueueEvent (DISP_EVENT *ctaevt)

Argument | Description
ctaevt | Pointer to the event structure to queue. The event structure contains the following fields: typedef struct { DWORD id; /* Event code (and source service ID) */ CTAHD ctahd; /* Natural Access context handle */ DWORD timestamp;/* timestamp */ DWORD userid; /* User ID (defined by ctaCreateContext) */ DWORD size; /* Size and type of buffer if buffer != NULL */ void *buffer; /* Buffer pointer */ DWORD value; /* Event status or event-specific data */ DWORD extra; /* Extra internal event field */ unsigned objHd; /*Service object handle (formerly "reserved")*/ MESSAGE_ADDR addr; /* Source/Destination service ID */ } DISP_EVENT; typedef struct { WORD source /* source service ID */ WORD destination /* destination service ID */ } MESSAGE_ADDR

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | ctaevt is NULL.
CTAERR_INVALID_CTAHD | Specified ctahd is invalid.
CTAERR_NOT_IMPLEMENTED | Function was called from the service interface.
CTAERR_NOT_INITIALIZED | Natural Access is not initialized.
CTAERR_OUT_OF_MEMORY | Unable to allocate memory for the queue, the driver, or the context.
CTAERR_SERVICE_NOT_AVAILABLE | Specified destination service is not available.

#### Details

dispQueueEvent can be used by services or service managers to send events to other services or to the application. The event is placed either in the dispatcher internal event queue or in the application queue (based on the destination) associated with the context referenced in the event.

The caller must fill in the id, ctahd, value, and addr fields. The context can be any valid context on any queue. source is typically the service ID. destination can be one of the following values:

- A service ID

- CTA_APP_SVCID

- CTA_SYS_SVCID

The size and buffer fields can be used to pass data to the application. If buffer = NULL, size can contain data.

The size field is also used to indicate to the dispatcher whether the event's buffer is static or dynamic. To do this, set one of the following flags in the field if buffer is not NULL:

Flag | Indicates...
--- | ---
CTA_INTERNAL_BUFFER_STATIC | Static buffer.
CTA_INTERNAL_BUFFER | Dynamic buffer. If the service implementation sets this flag, Natural Access or the application ensures the proper release of this buffer. The service implementation does not need to perform this task. Use dispAllocBuffer to allocate this buffer.

For more information about these flags, refer to DISP_EVENT structure.

The dispatcher sets the userid and timestamp fields.

#### See also

dispMakeAndQueueEvent