Jump to main content

##

# 1.1.6.4.10 DRV_SDMMC_EventHandlerSet Function

## C

    void DRV_SDMMC_EventHandlerSet (
        const DRV_HANDLE handle,
        const void* eventHandler,
        const uintptr_t context
    );

## Summary

Allows a client to identify an event handling function for the driver to call back when queued operation has completed.

## Description

This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client queues a request for a read or a write operation, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the queued operation has completed.

The event handler should be set before the client performs any read or write 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

The DRV_SDMMC_Initialize routine must have been called for the specified SDMMC driver instance.

The DRV_SDMMC_Open routine 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 function
eventHandler | Pointer to the event handler function implemented by the user
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 CACHE_ALIGN myBuffer[MY_BUFFER_SIZE];
    uint32_t blockStart, nBlock;
    DRV_SDMMC_COMMAND_HANDLE commandHandle;

    // Event Processing Technique. Event is received when operation is done.

    void APP_SDMMCEventHandler(
        DRV_SDMMC_EVENT event,
        DRV_SDMMC_COMMAND_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_SDMMC_EVENT_COMMAND_COMPLETE:
            {
                // This means the data was transferred successfully
                break;
            }

            case DRV_SDMMC_EVENT_COMMAND_ERROR:
            {
                // Error handling here
                break;
            }

            default:
            {
                break;
            }
        }
    }

    // drvSDMMCHandle is the handle returned
    // by the DRV_SDMMC_Open function.

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

    DRV_SDMMC_EventHandlerSet(drvSDMMCHandle, APP_SDMMCEventHandler, (uintptr_t)&myAppObj);

    DRV_SDMMC_AsyncRead(drvSDMMCHandle, &commandHandle, &myBuffer[0], blockStart, nBlock);

    if(commandHandle == DRV_SDMMC_COMMAND_HANDLE_INVALID)
    {
        // Error handling here
    }

## Remarks

If the client does not want to be notified when the queued operation has completed, it does not need to register a callback.