Jump to main content

##

# 1.1.9.4.10 DRV_USART_BufferCompletedBytesGet Function

## C

    size_t DRV_USART_BufferCompletedBytesGet
    (
        DRV_USART_BUFFER_HANDLE bufferHandle
    );

## Summary

Returns the number of bytes that have been processed for the specified buffer request.

## Description

The client can use this function, in a case where the buffer is terminated due to an error, to obtain the number of bytes that have been processed. Or in any other use case. This function can be used for non-DMA buffer transfers only. It cannot be used when the USART driver is configured to use DMA.

## Precondition

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

Either the DRV_USART_ReadBufferAdd or DRV_USART_WriteBufferAdd function must have been called and a valid buffer handle returned.

## Parameters

Param | Description
--- | ---
bufferhandle | Handle for the buffer of which the processed number of bytes to be obtained.

## Returns

Returns the number of bytes that have been processed for this buffer.

Returns DRV_USART_BUFFER_HANDLE_INVALID for an invalid or an expired buffer handle.

## Example

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

    uint8_t mybuffer[MY_BUFFER_SIZE];
    DRV_USART_BUFFER_HANDLE bufferHandle;

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

    void APP_USARTBufferEventHandler(
        DRV_USART_BUFFER_EVENT event,
        DRV_USART_BUFFER_HANDLE bufferHandle,
        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;
        size_t processedBytes;

        switch(event)
        {
            case DRV_USART_BUFFER_EVENT_COMPLETE:
            {
                // This means the data was transferred.
                break;
            }

            case DRV_USART_BUFFER_EVENT_ERROR:
            {
                // Error handling here.
                // We can find out how many bytes have been processed in this
                // buffer request prior to the error.

                processedBytes= DRV_USART_BufferCompletedBytesGet(bufferHandle);

                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
    }

## Remarks

This function is expected to work in non-DMA mode only. This function is thread safe when used in a RTOS application.