Installing client callbacks

There are three callbacks that the Client application must install.

Client procedure callback

All the procedures initiated by a Client are asynchronous. They rely on exchanging ATT packets over the air.

To be informed of the procedure completion, the application must install a callback with the following signature:

**typedef ****void** (* gattClientProcedureCallback_t )
(
    deviceId_t             deviceId,
    gattProcedureType_t    procedureType,
    gattProcedureResult_t  procedureResult,
    bleResult_t            error
);

For EATT, the following signature should be used:

typedef void (*gattClientEnhancedProcedureCallback_t)
(
   deviceId_t deviceId,
   bearerId_t bearerId,
   gattProcedureType_t procedureType,
   gattProcedureResult_t procedureResult,
   bleResult_t error
);

To install this callback, the following function must be called:

bleResult_t **GattClient\_RegisterProcedureCallback**
(
    gattClientProcedureCallback_t callback
);

The EATT procedure callback should be installed using the following API:

bleResult_t **GattClient\_RegisterEnhancedProcedureCallback**
(
 gattClientEnhancedProcedureCallback_t callback
);

The procedureType parameter can be used to identify the procedure that was started and has reached completion. Only one procedure would be active at a given moment. Trying to start another procedure while a procedure is already in progress returns the error gGattAnotherProcedureInProgress_c.

The procedureResult parameter indicates whether the procedure completes successfully or an error occurs. In the latter case, the error parameter contains the error code.

**void ****gatt ClientProcedureCallback**
(
    deviceId_t             deviceId,
    gattProcedureType_t    procedureType,
    gattProcedureResult_t  procedureResult,
    bleResult_t            error
)
{
    **switch** (procedureType)
    {
        /* ... */
    }
}
GattClient_RegisterProcedureCallback(gattClientProcedureCallback);

Parent topic:Installing client callbacks

Notification and indication callbacks

When the Client receives a notification from the Server, it triggers a callback with the following prototype:

**typedef ****void** (* gattClientNotificationCallback_t )
(
    deviceId_t     deviceId,
    uint16_t       characteristicValueHandle,
    uint8_t *      aValue,
    uint16_t       valueLength
);

The deviceId identifies the Server connection (for multiple connections at the same time). The characteristicValueHandle is the attribute handle of the Characteristic Value declaration in the GATT Database. The Client must have discovered it previously to be able recognize it.

For EATT, the following signature should be used:

typedef void (*gattClientEnhancedNotificationCallback_t)
 ( deviceId_t deviceId,
   bearerId_t bearerId,
   uint16_t characteristicValueHandle,
   uint8_t* aValue,
   uint16_t valueLength );

The callback must be installed with:

bleResult_t **GattClient\_RegisterNotificationCallback**
(
    gattClientNotificationCallback_t callback
);

Very similar definitions exist for indications.

The EATT notification callback should be installed using the following API:

bleResult_t **GattClient\_RegisterEnhancedNotificationCallback**
(
 gattClientEnhancedNotificationCallback_t callback
)

When receiving a notification or indication, the Client uses the characteristicValueHandle to identify which Characteristic was notified. The Client must be aware of the possible Characteristic Value handles that can be notified/indicated at any time, because it has previously activated them by writing its CCCD (see Reading and writing characteristic descriptors).

When the Client receives a multiple value notification from the Server, it triggers a callback with the following prototype:

typedef void (*gattClientMultipleValueNotificationCallback_t)
(
    deviceId_t     deviceId,  
    /*!< Device ID identifying the active connection. */   
    uint8_t* aHandleLenValue, 
    /*!< The array of handle, value length, value tuples. */
    uint16_t totalLength      
    /*!< Value array size. */
);

The callback must be installed with:

bleResult_t **GattClient\_RegisterMultipleValueNotificationCallback**
(
    gattClientMultipleValueNotificationCallback_t callback
);

When using EATT, the following callback prototype and registration APIs should be used:

typedef void (*gattClientEnhancedMultipleValueNotificationCallback_t)
( deviceId_t deviceId,   
    /*!< Device ID identifying the active connection. */   
  bearerId_t bearerId,    
   /*!< Bearer ID identifing the Enhanced ATT bearer used. */    
 uint8_t* aHandleLenValue,   
   /*!< The array of handle, value length, value tuples. */ 
uint16_t totalLength     /*!< Value array size. */
 );

Parent topic:Installing client callbacks

Parent topic:Client APIs