DRV_AT25_EventHandlerSet Function

C

void DRV_AT25_EventHandlerSet(
    const DRV_HANDLE handle,
    const DRV_AT25_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 the requested transfer has finished.

Description

This function allows a client to register a transfer event handling function with the driver to call back when the requested transfer has finished.

The event handler should be set before the client submits any transfer requests 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_AT25_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.
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

#define BUFFER_SIZE 256
#define MEM_ADDRESS 0x00

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

uint8_t myBuffer[BUFFER_SIZE];

// myHandle is the handle returned from DRV_AT25_Open API.

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

DRV_AT25_EventHandlerSet( myHandle, APP_AT25TransferEventHandler, (uintptr_t)&myAppObj );

if (DRV_AT25_Read(myHandle, myBuffer, BUFFER_SIZE, MEM_ADDRESS) == false)
{
    // Error handling here
}

// The registered event handler is called when the request is complete.

void APP_AT25TransferEventHandler(DRV_AT25_TRANSFER_STATUS event, 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_AT25_TRANSFER_STATUS_COMPLETED:
        {
            // This means the data was transferred.
            break;
        }
        
        case DRV_AT25_TRANSFER_STATUS_ERROR:
        {
            // Error handling here.
            break;
        }
        
        default:
        {
            break;
        }
    }
}

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.