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