1.1.9.4.20 DRV_USART_BUFFER_EVENT_HANDLER Typedef

typedef void (*DRV_USART_BUFFER_EVENT_HANDLER )( DRV_USART_BUFFER_EVENT event, DRV_USART_BUFFER_HANDLE bufferHandle, uintptr_t context );

Pointer to a USART Driver Buffer Event handler function

This data type defines the required function signature for the USART driver buffer event handling callback function. A client must register a pointer using the buffer event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive buffer related event calls back from the driver.

The parameters and return values are described here and a partial example implementation is provided.

None.

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

If the event is DRV_USART_BUFFER_EVENT_COMPLETE, it means that the data was transferred successfully.

If the event is DRV_USART_BUFFER_EVENT_ERROR, it means that the data was not transferred successfully. The DRV_USART_BufferCompletedBytesGet function can be called to find out how many bytes were processed.

The bufferHandle parameter contains the buffer handle of the buffer that associated with the event. And bufferHandle will be valid while the buffer request is in the queue and during callback, unless an error occurred. After callback returns, the driver will retire the buffer handle.

The context parameter contains the a handle to the client context, provided at the time the event handling function was registered using the DRV_USART_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request.

The event handler function executes in the peripheral's interrupt context. It is recommended of the application to not perform process intensive or blocking operations within this function.

The DRV_USART_ReadBufferAdd and DRV_USART_WriteBufferAdd functions can be called in the event handler to add a buffer to the driver queue. These functions can only be called to add buffers to the driver whose event handler is running. For example, USART2 driver buffers cannot be added in USART1 driver event handler.