GATT Database#

GATT Database.

Modules#

GATT Attribute Security Requirement Flags

Enumerations#

enum | sl_bt_gattdb_service_type_t { sl_bt_gattdb_primary_service = 0x0, sl_bt_gattdb_secondary_service = 0x1 } | This enum defines GATT service types.

enum | sl_bt_gattdb_value_type_t { sl_bt_gattdb_fixed_length_value = 0x1, sl_bt_gattdb_variable_length_value = 0x2, sl_bt_gattdb_user_managed_value = 0x3 } | This enum defines characteristic and descriptor value types.

Functions#

sl_status_t | sl_bt_gattdb_new_session (uint16_t *session)

sl_status_t | sl_bt_gattdb_add_service (uint16_t session, uint8_t type, uint8_t property, size_t uuid_len, const uint8_t *uuid, uint16_t *service)

sl_status_t | sl_bt_gattdb_remove_service (uint16_t session, uint16_t service)

sl_status_t | sl_bt_gattdb_add_included_service (uint16_t session, uint16_t service, uint16_t included_service, uint16_t *attribute)

sl_status_t | sl_bt_gattdb_remove_included_service (uint16_t session, uint16_t attribute)

sl_status_t | sl_bt_gattdb_add_uuid16_characteristic (uint16_t session, uint16_t service, uint16_t property, uint16_t security, uint8_t flag, sl_bt_uuid_16_t uuid, uint8_t value_type, uint16_t maxlen, size_t value_len, const uint8_t *value, uint16_t *characteristic)

sl_status_t | sl_bt_gattdb_add_uuid128_characteristic (uint16_t session, uint16_t service, uint16_t property, uint16_t security, uint8_t flag, uuid_128 uuid, uint8_t value_type, uint16_t maxlen, size_t value_len, const uint8_t *value, uint16_t *characteristic)

sl_status_t | sl_bt_gattdb_remove_characteristic (uint16_t session, uint16_t characteristic)

sl_status_t | sl_bt_gattdb_add_uuid16_descriptor (uint16_t session, uint16_t characteristic, uint16_t property, uint16_t security, sl_bt_uuid_16_t uuid, uint8_t value_type, uint16_t maxlen, size_t value_len, const uint8_t *value, uint16_t *descriptor)

sl_status_t | sl_bt_gattdb_add_uuid128_descriptor (uint16_t session, uint16_t characteristic, uint16_t property, uint16_t security, uuid_128 uuid, uint8_t value_type, uint16_t maxlen, size_t value_len, const uint8_t *value, uint16_t *descriptor)

sl_status_t | sl_bt_gattdb_remove_descriptor (uint16_t session, uint16_t descriptor)

sl_status_t | sl_bt_gattdb_start_service (uint16_t session, uint16_t service)

sl_status_t | sl_bt_gattdb_stop_service (uint16_t session, uint16_t service)

sl_status_t | sl_bt_gattdb_start_characteristic (uint16_t session, uint16_t characteristic)

sl_status_t | sl_bt_gattdb_stop_characteristic (uint16_t session, uint16_t characteristic)

sl_status_t | sl_bt_gattdb_commit (uint16_t session)

sl_status_t | sl_bt_gattdb_abort (uint16_t session)

Detailed Description#

GATT Database.

These commands and events are used for managing the local GATT database.

Many commands in this class return the handles of created attributes. These handles may change during commit if attributes are not created in the order they present in the database. For example, when creating a new service using the sl_bt_gattdb_add_service command, the service declaration handle returned from this command becomes invalid later when an attribute is added or removed in front of this service. If the user requires that the attribute handles returned from these commands must remain valid after the database update has been committed, attributes must be created in the order they present in the database.

Enumeration Type Documentation#

◆ sl_bt_gattdb_service_type_t#

enum sl_bt_gattdb_service_type_t#

This enum defines GATT service types.

Enumerator#

sl_bt_gattdb_primary_service |

(0x0) Primary service

sl_bt_gattdb_secondary_service |

(0x1) Secondary service

◆ sl_bt_gattdb_value_type_t#

enum sl_bt_gattdb_value_type_t#

This enum defines characteristic and descriptor value types.

Enumerator#

sl_bt_gattdb_fixed_length_value |

(0x1) A fixed-length value managed by the local GATT server for responding the read and write requests of remote GATT clients

sl_bt_gattdb_variable_length_value |

(0x2) A variable-length value managed by the local GATT server for responding the read and write requests of remote GATT clients

sl_bt_gattdb_user_managed_value |

(0x3) A value managed by the user application for responding the read and write requests of remote GATT clients.

Function Documentation#

◆ sl_bt_gattdb_new_session()#

sl_status_t sl_bt_gattdb_new_session | ( | uint16_t * | session| ) | ---|---|---|---|---|---

Start a new GATT database update session. If the operation is successful, the Bluetooth stack returns a session ID, with which the GATT database can be updated by calling other database management APIs of this class. Changes in the database are not immediately saved. Unsaved changes are invisible to a connected remote GATT client.

After all changes were performed successfully, commit the changes using the sl_bt_gattdb_commit command. The Bluetooth stack will save the changes and handle GATT caching as needed. Unsaved database changes can also be canceled by calling the sl_bt_gattdb_abort command. In either case, after a commit or abort command is called, the current session is closed and the session ID becomes invalid.

Only one session is allowed at a time. Error SL_STATUS_ALREADY_EXISTS is returned if another session has been started already.

Parameters

 [out]| `session`| The database update session ID

---|---|---

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_add_service()#


sl_status_t sl_bt_gattdb_add_service	(	uint16_t
	uint8_t	`type,`
	uint8_t	`property,`
	size_t	`uuid_len,`
	const uint8_t *	`uuid,`
	uint16_t *	`service`
)

Add a service into the local GATT database. When successful, the service is appended to the service list and is in stopped state. Use sl_bt_gattdb_start_service command to set it visible to remote GATT clients.

You are not allowed to add the Generic Attribute Profile service. If the application needs GATT caching, enable the feature in the configuration of this component and the GATT server will handle GATT caching according to the procedures specified by the Bluetooth core specification.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| type| Enum sl_bt_gattdb_service_type_t. The service type. Values:

sl_bt_gattdb_primary_service (0x0): Primary service
sl_bt_gattdb_secondary_service (0x1): Secondary service

[in]| property| Service properties. Value: 0 or bit flag SL_BT_GATTDB_ADVERTISED_SERVICE [in]| uuid_len| Length of data in uuid [in]| uuid| The service UUID in little endian format [out]| service| The service declaration attribute handle. This handle is ensured valid in current session. It may change after the session if attributes have been inserted or deleted in front of it.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_remove_service()#


sl_status_t sl_bt_gattdb_remove_service	(	uint16_t	`session,`
	uint16_t	`service`
)

Remove a service and its characteristics from the local GATT database.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| service| The service declaration attribute handle of the service

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_add_included_service()#


sl_status_t sl_bt_gattdb_add_included_service	(	uint16_t
	uint16_t	`service,`
	uint16_t	`included_service,`
	uint16_t *	`attribute`
)

Add an included-service attribute to a service.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| service| The service declaration attribute handle of the service which the included-service attribute is added to [in]| included_service| The service declaration attribute handle of the service to be included [out]| attribute| The included-service attribute handle. This handle is ensured valid in current session. It may change after the session if attributes have been inserted or deleted in front of it.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_remove_included_service()#

sl_status_t sl_bt_gattdb_remove_included_service | ( | uint16_t | session, ---|---|---|--- | | uint16_t | attribute | ) | |

Remove an included-service attribute from a service.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| attribute| The included-service attribute handle

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_add_uuid16_characteristic()#

sl_status_t sl_bt_gattdb_add_uuid16_characteristic | ( | uint16_t | session, ---|---|---|--- | | uint16_t | service, | | uint16_t | property, | | uint16_t | security, | | uint8_t | flag, | | sl_bt_uuid_16_t | uuid, | | uint8_t | value_type, | | uint16_t | maxlen, | | size_t | value_len, | | const uint8_t * | value, | | uint16_t * | characteristic | ) | |

Add a 16-bits UUID characteristic to a service. On success, the characteristic is appended to the characteristic list of the service and it inherits the started or stopped state of the service. In addition, it can be started and stopped separately with the sl_bt_gattdb_start_characteristic and sl_bt_gattdb_stop_characteristic commands.

If the flag parameter does not set SL_BT_GATTDB_NO_AUTO_CCCD, the stack will automatically add a Client Characteristic Configuration descriptor to this characteristic when it has the notify or indicate property. If SL_BT_GATTDB_NO_AUTO_CCCD is set, the user application should add the descriptor separately as needed.

A Characteristic Extended Properties descriptor is automatically added if the reliable write property is set.

Use the sl_bt_gattdb_add_uuid128_characteristic command to add a 128-bits UUID characteristic.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| service| The service declaration attribute handle of the service which the characteristic is added to [in]| property| Characteristic value properties. Value: bitmask of GATT Characteristic Property Flags [in]| security| Security requirement. Value: 0 or bitmask of GATT Attribute Security Requirement Flags. A security requirement flag for a property is ignored if the property is not set for the characteristic value. [in]| flag| Option flags. Value: 0 or bitmask of GATT Database Flags. [in]| uuid| The 16-bits UUID in little endian format [in]| value_type| Enum sl_bt_gattdb_value_type_t. The value type. Values:

sl_bt_gattdb_fixed_length_value (0x1): A fixed-length value managed by the local GATT server for responding the read and write requests of remote GATT clients
sl_bt_gattdb_variable_length_value (0x2): A variable-length value managed by the local GATT server for responding the read and write requests of remote GATT clients
sl_bt_gattdb_user_managed_value (0x3): A value managed by the user application for responding the read and write requests of remote GATT clients.

[in]| maxlen| The maximum length of the characteristic value. Ignored if value_type is sl_bt_gattdb_user_managed_value. [in]| value_len| Length of data in value [in]| value| The initial characteristic value. Length of this value must be less than or equal to maxlen. Ignored if value_type is sl_bt_gattdb_user_managed_value. [out]| characteristic| The characteristic value attribute handle. This handle is ensured valid in current session. It may change after the session if attributes have been inserted or deleted in front of it.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_add_uuid128_characteristic()#

sl_status_t sl_bt_gattdb_add_uuid128_characteristic | ( | uint16_t | session, ---|---|---|--- | | uint16_t | service, | | uint16_t | property, | | uint16_t | security, | | uint8_t | flag, | | uuid_128 | uuid, | | uint8_t | value_type, | | uint16_t | maxlen, | | size_t | value_len, | | const uint8_t * | value, | | uint16_t * | characteristic | ) | |

Add a 128-bits UUID characteristic to a service. When successful, the characteristic is appended to the characteristic list of the service and inherits the started or stopped state of the service. Additionally, it can be started and stopped separately with the sl_bt_gattdb_start_characteristic and sl_bt_gattdb_stop_characteristic commands.

A Characteristic Extended Properties descriptor is automatically added if the reliable write property is set.

Use the sl_bt_gattdb_add_uuid16_characteristic command to add a 16-bits UUID characteristic.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| service| The service declaration attribute handle of the service which the characteristic is added to [in]| property| Characteristic value properties. Value: bitmask of GATT Characteristic Property Flags [in]| security| Security requirement. Value: 0 or bitmask of GATT Attribute Security Requirement Flags. A security requirement flag for a property is ignored if the property is not set for the characteristic value. [in]| flag| Option flags. Value: 0 or bitmask of GATT Database Flags. [in]| uuid| The 128-bits UUID in little endian format [in]| value_type| Enum sl_bt_gattdb_value_type_t. The value type. Values:

sl_bt_gattdb_fixed_length_value (0x1): A fixed-length value managed by the local GATT server for responding the read and write requests of remote GATT clients
sl_bt_gattdb_variable_length_value (0x2): A variable-length value managed by the local GATT server for responding the read and write requests of remote GATT clients
sl_bt_gattdb_user_managed_value (0x3): A value managed by the user application for responding the read and write requests of remote GATT clients.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_remove_characteristic()#


sl_status_t sl_bt_gattdb_remove_characteristic	(	uint16_t	`session,`
	uint16_t	`characteristic`
)

Remove a characteristic and its descriptors from a service.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| characteristic| The characteristic value attribute handle of the characteristic

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_add_uuid16_descriptor()#


sl_status_t sl_bt_gattdb_add_uuid16_descriptor	(	uint16_t
	uint16_t	`characteristic,`
	uint16_t	`property,`
	uint16_t	`security,`
	sl_bt_uuid_16_t	`uuid,`
	uint8_t	`value_type,`
	uint16_t	`maxlen,`
	size_t	`value_len,`
	const uint8_t *	`value,`
	uint16_t *	`descriptor`
)

Add a 16-bits UUID descriptor to a characteristic. When successful, the descriptor is appended to the descriptor list of the characteristic and inherits the started or stopped state of the characteristic.

This command does not support adding Characteristic Extended Properties descriptors. This descriptor is automatically added if the characteristic value has the reliable-write property or when a Characteristic User Description descriptor is added and the user description has the write property.

Use the sl_bt_gattdb_add_uuid128_descriptor command to add a 128-bits UUID descriptor.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| characteristic| The characteristic value attribute handle of the characteristic the descriptor is added to [in]| property| The descriptor properties. Value: bitmask of GATT Descriptor Property Flags [in]| security| Security requirement. Value: 0 or bitmask of GATT Attribute Security Requirement Flags. A security requirement flag for a property is ignored if the property is not set for the descriptor. [in]| uuid| The 16-bits UUID in little endian format [in]| value_type| Enum sl_bt_gattdb_value_type_t. The value type. Ignored if this is a Client Characteristic Configuration descriptor. Values:

sl_bt_gattdb_fixed_length_value (0x1): A fixed-length value managed by the local GATT server for responding the read and write requests of remote GATT clients
sl_bt_gattdb_variable_length_value (0x2): A variable-length value managed by the local GATT server for responding the read and write requests of remote GATT clients
sl_bt_gattdb_user_managed_value (0x3): A value managed by the user application for responding the read and write requests of remote GATT clients.

[in]| maxlen| The maximum length of the descriptor value. Ignored if value_type is sl_bt_gattdb_user_managed_value, or if this is a Client Characteristic Configuration descriptor. [in]| value_len| Length of data in value [in]| value| The initial descriptor value. Length of this value must be less than or equal to maxlen. Ingored if value type is sl_bt_gattdb_user_managed_value, or if this is a Client Characteristic Configuration descriptor. [out]| descriptor| The descriptor attribute handle. This handle is ensured valid in current session. It may change after the session if attributes have been inserted or deleted in front of it.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_add_uuid128_descriptor()#


sl_status_t sl_bt_gattdb_add_uuid128_descriptor	(	uint16_t
	uint16_t	`characteristic,`
	uint16_t	`property,`
	uint16_t	`security,`
	uuid_128	`uuid,`
	uint8_t	`value_type,`
	uint16_t	`maxlen,`
	size_t	`value_len,`
	const uint8_t *	`value,`
	uint16_t *	`descriptor`
)

Add a 128-bits UUID descriptor to a characteristic. When successful, the descriptor is appended to the descriptor list of the characteristic and inherits the started or stopped state of the characteristic.

Use the sl_bt_gattdb_add_uuid16_descriptor command to add a 16-bits UUID descriptor.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| characteristic| The characteristic value attribute handle of the characteristic the descriptor is added to [in]| property| Bitmask of characteristic descriptor properties [in]| security| Security requirement. Value: 0 or bitmask of GATT Attribute Security Requirement Flags. A security requirement flag for a property is ignored if the property is not set for the descriptor. [in]| uuid| The 128-bits UUID in little endian format [in]| value_type| Enum sl_bt_gattdb_value_type_t. The value type. Ignored if this is a Client Characteristic Configuration descriptor. Values:

sl_bt_gattdb_fixed_length_value (0x1): A fixed-length value managed by the local GATT server for responding the read and write requests of remote GATT clients
sl_bt_gattdb_variable_length_value (0x2): A variable-length value managed by the local GATT server for responding the read and write requests of remote GATT clients
sl_bt_gattdb_user_managed_value (0x3): A value managed by the user application for responding the read and write requests of remote GATT clients.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_remove_descriptor()#


sl_status_t sl_bt_gattdb_remove_descriptor	(	uint16_t	`session,`
	uint16_t	`descriptor`
)

Remove a descriptor from a characteristic.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| descriptor| The descriptor handle

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_start_service()#


sl_status_t sl_bt_gattdb_start_service	(	uint16_t	`session,`
	uint16_t	`service`
)

Start a service, so that the service and its attributes including characteristics and descriptors become visible to remote GATT clients after this change has been committed.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| service| The service declaration attribute handle of the service

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_stop_service()#


sl_status_t sl_bt_gattdb_stop_service	(	uint16_t	`session,`
	uint16_t	`service`
)

Stop a service, so that the service and its attributes including characteristics and descriptors become invisible to remote GATT clients after this change has been committed.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| service| The service declaration attribute handle of the service

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_start_characteristic()#


sl_status_t sl_bt_gattdb_start_characteristic	(	uint16_t	`session,`
	uint16_t	`characteristic`
)

Start a characteristic, so that the characteristic and its attributes become visible to remote GATT clients after this change has been committed. SL_STATUS_INVALID_STATE error is returned if the parent service is not started.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| characteristic| The characteristic value attribute handle of the characteristic

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_stop_characteristic()#


sl_status_t sl_bt_gattdb_stop_characteristic	(	uint16_t	`session,`
	uint16_t	`characteristic`
)

Stop a characteristic, so that the characteristic and its attributes become invisible to remote GATT clients after this change has been committed.

Parameters

 [in]| `session`| The database update session ID

---|---|--- [in]| characteristic| The characteristic value attribute handle of the characteristic

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_commit()#

sl_status_t sl_bt_gattdb_commit | ( | uint16_t | session| ) | ---|---|---|---|---|---

Save all changes performed in the current session and close the session. The stack will assign final handles to new and affected attributes and handle GATT caching as needed. The stack removes the client characteristic configurations of non-connected GATT clients except the service-changed configuration. For connected GATT clients during this database change, the stack removes the configurations to the removed characteristics. The session ID, temporary attribute handles returned during this session, and other existing attribute handles that are after newly added or removed attributes are invalidated.

Some attribute handles returned in this session may become invalid if attributes are not created in the order they present in the database. In this case, attribute handle cache of the database in the user application must be refreshed to avoid accidentally using an invalidated handle in subsequent operations.

Parameters

 [in]| `session`| The database update session ID

---|---|---

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gattdb_abort()#

sl_status_t sl_bt_gattdb_abort | ( | uint16_t | session| ) | ---|---|---|---|---|---

Cancel all changes performed in the current session and close the session. The database remains in the same state it was in just before the session was started. The session ID and all temporary attribute handles returned during this session are invalidated.

Parameters

 [in]| `session`| The database update session ID

---|---|---

Returns

SL_STATUS_OK if successful. Error code otherwise.