Jump to main content

##

# 1.1.2.4.11 DRV_I2C_TransferEventHandlerSet Function

## C

    void DRV_I2C_TransferEventHandlerSet
    (
        const DRV_HANDLE handle,
        const DRV_I2C_TRANSFER_EVENT_HANDLER eventHandler,
        const uintptr_t context
    )

## Summary

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

## Description

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

The event handler should be set before the client performs any "transfer 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).

## Precondition

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

## Parameters

Param | Description
--- | ---
handle | A valid open-instance handle, returned from the driver's open routine DRV_I2C_Open function.
eventHandler | Pointer to the event handler function.
context | The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure).

## Returns

None.

## Example

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

    uint8_t myBuffer[MY_BUFFER_SIZE];
    DRV_I2C_TRANSFER_HANDLE transferHandle;

    // The registered event handler is called when the transfer is completed.

    void APP_I2CTransferEventHandler(DRV_I2C_TRANSFER_EVENT event, DRV_I2C_TRANSFER_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* pMyAppObj = (MY_APP_OBJ *) context;

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

            case DRV_I2C_TRANSFER_EVENT_ERROR:
            {
                // Error handling here.
                break;
            }

            default:
            {
                break;
            }
        }
    }

    // myI2CHandle is the handle returned
    // by the DRV_I2C_Open function.

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

    DRV_I2C_TransferEventHandlerSet( myI2CHandle, APP_I2CTransferEventHandler, (uintptr_t)&myAppObj );

    DRV_I2C_ReadTransferAdd(myI2CHandle, slaveAddress, myBuffer, MY_BUFFER_SIZE, &transferHandle);

    if(transferHandle == DRV_I2C_TRANSFER_HANDLE_INVALID)
    {
        // Error handling here
    }

## Remarks

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. This function is available only in the asynchronous mode.