Jump to main content

##

# 1.1.9.4.8 DRV_USART_WriteBufferAdd Function

## C

    void DRV_USART_WriteBufferAdd
    (
        const DRV_HANDLE handle,
        void* buffer,
        size_t size,
        DRV_USART_BUFFER_HANDLE* bufferHandle
    );

## Summary

Queues a write operation.

## Description

This function schedules a non-blocking write operation. The function returns with a valid buffer handle in the bufferHandle argument if the write request was scheduled successfully. The function adds the request to the driver instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. On returning, the bufferHandle parameter may be DRV_USART_BUFFER_HANDLE_INVALID for the following reasons:

- if a buffer could not be allocated to the request because the queue is full
- if the input buffer handle is NULL
- if the input buffer pointer is NULL
- if the buffer size (number of bytes to write) is 0
- if the driver handle is invalid

If the requesting client registered an event callback with the driver, the driver will issue a DRV_USART_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or a DRV_USART_BUFFER_EVENT_ERROR event if the buffer was not processed successfully.

## Precondition

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

## Parameters

Param | Description
--- | ---
handle | Handle of the communication channel as return by the DRV_USART_Open function.
buffer | Data to be transmitted.
size | Buffer size in bytes.
bufferHandle | Pointer to an argument that will contain the return buffer handle.

## Returns

The bufferHandle parameter will contain the return buffer handle. This will be DRV_USART_BUFFER_HANDLE_INVALID if the function was not successful.

## Example

    MY_APP_OBJ myAppObj;
    uint8_t mybuffer[MY_BUFFER_SIZE];
    DRV_USART_BUFFER_HANDLE bufferHandle;

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

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

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

    // Event is received when
    // the buffer is processed.

## Remarks

This function is thread safe in a RTOS application. It can be called from within the USART Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another USART driver instance. It should not otherwise be called directly in an ISR.