Creating a GATT database dynamically

To define a GATT Database at runtime, the gGattDbDynamic_d macro must be defined in app_preinclude.h with the value equal to 1.

Then, the application must use the APIs provided by the gatt_db_dynamic.h interface to add and remove Services and Characteristics as needed.

See Creating static GATT database for a detailed description of Service and Characteristic parameters.

Memory considerations

The GATT Dynamic database module internally manages the memory allocation for the database. If the gMemManagerLightExtendHeapAreaUsage define is set to 1 in the desired application, the whole available heap is used. In such as case, the user does not have to allocate space for the dynamic database. If this is not done, the user only needs to make sure that the MinimalHeapSize_c define is set to a high enough value considering all attributes and attribute values they want to add to the database, as well as other memory requirements the application might have.

Internally, two buffers are used by the dynamic database module: an attribute buffer and a value buffer. The attribute buffer size increases with the addition of each attribute to the database. The value buffer size increases depending on the UUID type and value lengths required by the application. The two buffers start with a minimum size and are reallocated whenever new requests to add entries are received and there is not enough available memory left. If the user removes these entries from the database, the memory reserved for those entries is not freed, but shifted, leaving room for new entries. Thus, an add operation after a remove operation might not necessarily reallocate the buffer if the new entries fit. The two buffers used by the Dynamic database module will not be available to the application until the user releases the database.

Parent topic:Creating a GATT database dynamically

Initialization and release

Before anything can be added to the database, it must be initialized with an empty collection of attributes.

The GattDbDynamic_Init() API is automatically called by the GattDb_Init() implementation provided in the gatt_database.c source file. Application-specific code does not need to call this API again, unless at some point it destroys the database with GattDb_ReleaseDatabase().

Parent topic:Creating a GATT database dynamically

Adding services

The APIs that can be used to add Services are self-explanatory:

• GattDbDynamic_AddPrimaryServiceDeclaration

  • The Service UUID is specified as parameter.

    Memory requirements: one entry in the attribute buffer and UUID size in value buffer.

• GattDbDynamic_AddSecondaryServiceDeclaration

  • The Service UUID is specified as parameter.

    Memory requirements: one entry in the attribute buffer and UUID size in value buffer.

• GattDbDynamic_AddIncludeDeclaration

  • The Service UUID and handle range are specified as parameters.

    Memory requirements: one entry in the attribute buffer and 6 bytes in value buffer.

The functions have an optional out parameter pOutHandle. If its value is not NULL, the execution writes a 16-bit value in the pointed location representing the attribute handle of the added declaration. The application can use this handle as parameter in few GattDbApp APIs or in the Service removal functions.

At least one Service must be added before any Characteristic.

Parent topic:Creating a GATT database dynamically

Adding characteristics and descriptors

The APIs for adding Characteristics and Descriptors are enumerated below:

• GattDbDynamic_AddCharacteristicDeclarationAndValue

  • The Characteristic UUID, properties, access permissions, and initial value are specified as parameters.

• GattDbDynamic_AddCharacteristicDeclarationWithUniqueValue

  • Multiple calls to this API allocate a unique 512-byte value buffer as an optimization for application that deal with large value buffers that do not always need to be stored separately.

• GattDbDynamic_AddCharacteristicDescriptor

  • The Descriptor UUID, access permissions and initial value are specified as parameters.

• GattDbDynamic_AddCccd

  • Shortcut for a CCCD.

Characteristics and descriptors are automatically added at the end of the database. Thus, a service declaration should be followed by all desired characteristic and descriptor definitions before adding a new service to the database.

Parent topic:Creating a GATT database dynamically

Removing services and characteristics

To remove a Service or a Characteristic, the following APIs may be used, both of which only require the declaration handle as parameter:

• GattDbDynamic_RemoveService

• GattDbDynamic_RemoveCharacteristic

Parent topic:Creating a GATT database dynamically

Parent topic:Creating GATT database