1.1.9.4.7 DRV_USART_BufferEventHandlerSet Function

void DRV_USART_BufferEventHandlerSet
(
    const DRV_HANDLE handle,
    const DRV_USART_BUFFER_EVENT_HANDLER eventHandler,
    const uintptr_t context
)

Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished.

This function allows a client to register a buffer event handling function with the driver to call back when queued buffer transfers have finished. When a client calls either the DRV_USART_ReadBufferAdd or DRV_USART_WriteBufferAdd function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed.

The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback).

DRV_USART_Open must have been called to obtain a valid opened device handle.

None.

// myAppObj is an application specific state data object.
MY_APP_OBJ myAppObj;

uint8_t mybuffer[MY_BUFFER_SIZE];
DRV_USART_BUFFER_HANDLE bufferHandle;

// Event is received when the buffer is processed.

void APP_USARTBufferEventHandler(
    DRV_USART_BUFFER_EVENT event,
    DRV_USART_BUFFER_HANDLE handle,
    uintptr_t context
)
{
    // The context handle was set to an application specific
    // object. It is now retrievable easily in the event handler.
    MY_APP_OBJ* myAppObj = (MY_APP_OBJ *) context;
    
    switch(event)
    {
        case DRV_USART_BUFFER_EVENT_COMPLETE:
        {
            // This means the data was transferred.
            break;
        }
        
        case DRV_USART_BUFFER_EVENT_ERROR:
        {
            // Error handling here.
            break;
        }
        
        default:
        {
            break;
        }
    }
}

// myUSARTHandle is the handle returned
// by the DRV_USART_Open function.

// Client registers an event handler with driver. This is done once

DRV_USART_BufferEventHandlerSet(
    myUSARTHandle,
    APP_USARTBufferEventHandler,
    (uintptr_t)&myAppObj
);

DRV_USART_ReadBufferAdd(
    myUSARThandle,
    myBuffer,
    MY_BUFFER_SIZE,
    &bufferHandle
);

if(bufferHandle == DRV_USART_BUFFER_HANDLE_INVALID)
{
    // Error handling here
}

If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. This function is thread safe when called in a RTOS application.