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.

dispQueueEvent

Prototype

Return values

Details

See also