# ctaQueueEvent

Enqueues an event to an event queue in the same process.

#### Prototype

DWORD ctaQueueEvent ( CTA_EVENT *ctaevt)

Argument | Description
ctaevt | Pointer to the event structure to be enqueued. The CTA_EVENT structure is: typedef struct { DWORD id; /* Event code and source service ID */ CTAHD ctahd; /* Natural Access context handle */ DWORD timestamp; /* Timestamp */ DWORD userid; /* Userid(defined by ctaCreateContext) */ DWORD size; /* Size of buffer if buffer != NULL */ void *buffer; /* Buffer pointer */ DWORD value; /* Event status or event-specific data */ DWORD objHD; /* Service object handle */ } CTA_EVENT;

#### Return values

Return value | Description
SUCCESS |
CTAERR_INVALID_CTAHD | An invalid context handle was passed as an argument to a function, or the context was destroyed by another thread.
CTAERR_NOT_INITIALIZED | Natural Access is not initialized. Call ctaInitialize first.
CTAERR_SVR_COMM | Server communication error.

#### Details

ctaQueueEvent routes the event to the event queue of the context specified by the ctahd field in CTA_EVENT.

Applications can create their own events using the valid code identifiers of 0x20002000 through 0x20002FFF. Use the CTA_USER_EVENT macro to convert a user event code in the range of 0 through 0xFFF to a valid Natural Access event code.

#### See also

ctaWaitEvent

#### Example - sending

/* Code fragment for a program responsible for performing call control
* on a Natural Access context. Media functions will be performed by another
* program which attaches to a shared context, i.e., the one on which call
* control is being performed by this program.
*/
CTAQUEUEHD ctaqueuehd = NULL_CTAQUEUEHD;
CTAHD CallCtrlCtahd;
void ExchangeContextName( CTAHD ctahd, char *pNewCtxtName )
{
unsigned userid = 0;
int ret ;
/* Attach to agreed upon context for exchange of application events */
if ((ret = ctaAttachContext( ctaqueuehd, userid, "Common", &ctahd ))
!= SUCCESS)
{
printf("Unable to attach to shared context used with media program\n");
exit(-1);
}
/* Create new context based upon the name provided to the application in the
* startup of the program, i.e., "pNewCtxName". This is the new context
* on which call control and media functions will be performed.
*/
if (ret = ctaCreateContextEx( ctaqueuehd, userid, pNewCtxtName,
&CallCtrlCtahd, 0 ) != SUCCESS)
{
printf("Unable to create context %s\n", pNewCtxtName );
exit(-1);
}
else
{
CTA_EVENT event = { 0 };
/* Fill in the event to be sent to the media program. */
event.id = APPEVN_EXCHANGE_NAME;
event.ctahd = ctahd;
event.value = SUCCESS;
/* Send text buffer with the event */
event.size = strlen( pNewCtxtName ) + 1;
event.buffer = pNewCtxtName;
if ( (ret = ctaQueueEvent( &event )) != SUCCESS )
{
printf("ctaQueueEvent failed with 0x%x", ret );
exit(-1);
}
}
}

#### Example - receiving

/* Code fragment from a program responsible for performing media functions
* on a Natural Access context shared with another program that performs call
* control.
*/
CTAHD commCtahd = NULL_CTAHD, mediaCtahd = NULL_CTAHD;
CTAQUEUEHD ctaqueuehd;
void SetupAndExchange()
{
DWORD ret;
/* Create agreed to context on which exchange of application events
* will occur.
*/
if (ret = ctaCreateContextEx( ctaqueuehd, 0, "Common",
&commCtahd, 0 ) != SUCCESS)
{
printf("Unable to create context %s\n", "Common" );
exit(-1);
}
/* Wait for the call control program to attach to this "common" context
* and send an event message indicating the name of the context on which
* media should be played.
*/
for(;;)
{
CTA_EVENT event = { 0 };
int ctaOwnsBuf = 0;
event.ctahd = commCtahd;
if((ret = ctaWaitEvent( ctaqueuehd, &event,
CTA_WAIT_FOREVER )) != SUCCESS )
{
printf("ctaWaitEvent returns 0x%x -- exiting\n", "ret );
exit( -1 );
}
/* In Natural Access Server mode, certain event buffers are allocated by
* Natural Access and then must be released back to Natural Access.
*/
if ( event.buffer )
{
if ( ctaOwnsBuf = event.size & CTA_INTERNAL_BUFFER )
/* This buffer is owned by Natural Access and will need to be
* released back to Natural Access after processing of the buffer
* is complete. Clear the Natural Access flags from the size field.
*/
event.size &= ~CTA_INTERNAL_BUFFER;
}
switch ( event.id )
{
case APPEVN_EXCHANGE_NAME:
/* This event message contains the name of the context
* to which we should now attach.
*/
if ( event.buffer )
{
if ((ret = ctaAttachContext( ctaqueuehd, userid,
event.buffer, &mediaCtahd)))
!= SUCCESS)
{
printf("Unable to attach to context %s\n",event.buffer);
exit( -1 );
}
}
break;
case APPEVN_PLAY_MSG:
/* The call control program indicates which message to play
* by sending the message number in the event's size field.
*/
int msgNum = event.size;
DemoPlayMessage( mediaCtahd, "ctademo", msgNum,
0, NULL );
break;
default:
break;
}
/* In Natural Access Client/Server mode, ensure proper release of
* Natural Access owned buffers.
*/
if ( ctaOwnsBuf )
{
ctaOwnsBuf = 0;
ctaFreeBuffer( event.buffer );
}
}
}