Implementing client-side binding functions

Client-side binding functions are called by the Natural Access dispatcher rather than by the application. These functions provide adjunct functionality. The names of client-side binding functions are standardized and known to the Natural Access dispatcher. The dispatcher determines at runtime whether particular binding functions are implemented by the service interface and calls them appropriately.

Currently, there is only one client-side binding function: xxxEventProcessing. The Natural Access dispatcher calls this synchronous function prior to posting a service event to the client's application queue. (xxx is the service acronym; for example: tikEventProcessing). Natural Access calls this function to enable the service interface to make updates to an event generated by the service implementation before the event is received by the client application. This function is often used in the processing of service object handles as described in the Service object handles section. The function is also used to clear and release event buffers.

The following sample code shows how xxxEventProcessing is used:

xxxSpiGetInfo( CTAHD ctahd )
{
    MY_BUFFER *pbuff;
    DISP_COMMAND cmd = {0};

    cmd.id = XXXCMD_GETINFO;

    pbuff = malloc( sizeof(MY_BUFFER) ); 
    cmd.size1 = sizeof(MY_BUFFER) | CTA_VIRTUAL_BUF;
    cmd.dataptr1 = (void *) pbuff;

    /* etc. */
    dispSendCommand( &cmd );

    /* Data will be returned in asynchronous DONE event */
    return SUCCESS;
}

/* Later, when the service manager generates a XXXEVN_GETINFO_DONE event. */

xxxEventProcessing( CTA_EVENT *event )
{
    /* Must check event's buffer flags just as an
    *  application is required to do.
    */
    bool bCtaOwnsBuffer = pevent->size & CTA_INTERNAL_BUFFER;
    /* Clear any flags in the size field before using it. */
    pevent->size &= ~CTA_INTERNAL_BUFFER;

    if ( event->id == XXXEVN_GETINFO_DONE )
    {
        /* Save information to global area and release the buffer pointer
        *  that was allocated by the SPI function. 
        */
        memcpy( globalBuff, event->buffer, event->size );
        
        if ( bCtaOwnsBuffer )
        {        
             /* This buffer is owned by Natural Access. This event
             *  is being sent on a shared context.
             */
            dispFreeBuffer( event->buffer );
        }
        else
        {
            /* The SPI function invoked by this client allocated this
            *  buffer. Release it.
            */
            free( event->buffer );
        }

        /* Clear the buffer pointer so that it is not used by the 
        *  application when it receives this DONE event.
        */
        event->size = 0;
        event->buffer = NULL;
    }
}