GATT database application interface

For over-the-air packet exchanges between a Client and a Server, the GATT Server module automatically retrieves data from the GATT database and responds to all ATT Requests from the peer Client, provided it passes the security checks. This ensures that the Server application does not have to perform any kind of searches over the database.

However, the application must have access to the database to write meaningful data into its characteristics. For example, a temperature sensor must periodically write the temperature, which is measured by an external thermometer, into the Temperature Characteristic.

For these kinds of situations, a few APIs are provided in the gatt_db_app_interface.h file.

Note: All functions provided by this interface are executed synchronously. The result of the operation is saved in the return value and it generates no event.

Writing and reading attributes

These are the two functions to perform basic attribute operations from the application:

bleResult_t **GattDb\_WriteAttribute
**(
    uint16_t           handle,
    uint16_t           valueLength,
    const uint8_t *    aValue
);

The value length must be valid, as defined when the database is created. Otherwise, a gGattInvalidValueLength_c error is returned.

Also, if the database is created statically, as explained in Creating GATT database, the handle may be referenced through the enumeration member with a friendly name defined in the gatt_db.h.

bleResult_t **GattDb\_ReadAttribute**
(
    uint16_t     handle,
    uint16_t     maxBytes,
    uint8_t *    aOutValue,
    uint16_t *   pOutValueLength
);

The aOutValue array must be allocated with the size equal to maxBytes.

Parent topic:GATT database application interface

Finding attribute handles

Although the application should be fully aware of the contents of the GATT Database, in certain situations it might be useful to perform some dynamic searches of certain attribute handles.

To find the handle value for a Service for which only the UUID is know the following API can be used:

bleResult_t GattDb_FindServiceHandle
(
 uint16_t startHandle,
 bleUuidType_t serviceUuidType,
 const bleUuid_t* pServiceUuid,
 uint16_t* pOutServiceHandle
);

To find a specific Characteristic Value Handle in a Service whose declaration handle is known, the following API is provided:

bleResult_t **GattDb\_FindCharValueHandleInService**
(
    uint16_t               serviceHandle,
    bleUuidType_t          characteristicUuidType,
    const bleUuid_t *      pCharacteristicUuid,
    uint16_t *             pOutCharValueHandle
);

If the return value is gBleSuccess_c, the handle is written at pOutCharValueHandle. If the serviceHandle is invalid or not a valid Service declaration, the gBleGattDbInvalidHandle_c is returned. Otherwise, the search is performed starting with the serviceHandle+1. If no Characteristic of the given UUID is found, the function returns the gBleGattDbCharacteristicNotFound_c value.

To find a Characteristic Descriptor of a given type in a Characteristic, when the Characteristic Value Handle is known, the following API is provided:

bleResult_t **GattDb\_FindDescriptorHandleForCharValueHandle**
(
    uint16_t           charValueHandle,
    bleUuidType_t      descriptorUuidType,
    const bleUuid_t *  pDescriptorUuid,
    uint16_t *         pOutDescriptorHandle
);

Similarly, the function returns gBleGattDbInvalidHandle_c is the handle is invalid. Otherwise, it starts searching from the charValueHandle+1. Then, gBleGattDbDescriptorNotFound_c is returned if no Descriptor of the specified type is found. Otherwise, its attribute handle is written at the pOutDescriptorHandle and the function returns gBleSuccess_c.

One of the most commonly used Characteristic Descriptors is the Client Configuration Characteristic Descriptor (CCCD), which has the UUID equal to gBleSig_CCCD_d. For this specific type, a special API is used as a shortcut:

bleResult_t **GattDb\_FindCccdHandleForCharValueHandle**
(
    uint16_t     charValueHandle,
    uint16_t *   pOutCccdHandle
);

Parent topic:GATT database application interface