GATT Server#

GATT Server.

Modules#

sl_bt_evt_gatt_server_attribute_value Indicates that the value of an attribute in the local GATT database was changed by a remote GATT client.

sl_bt_evt_gatt_server_user_read_request Indicates that a remote GATT client is attempting to read a value of an attribute from the local GATT database, where the attribute was defined in the GATT database XML file to have the type="user".

sl_bt_evt_gatt_server_user_write_request Indicates that a remote GATT client is attempting to write a value of an attribute into the local GATT database, where the attribute was defined in the GATT database XML file to have the type="user".

sl_bt_evt_gatt_server_characteristic_status Indicates either that a local Client Characteristic Configuration descriptor was changed by the remote GATT client, or that a confirmation from the remote GATT client was received upon a successful reception of the indication.

sl_bt_evt_gatt_server_execute_write_completed Execute write completed event indicates that the execute write command from a remote GATT client has completed with the given result.

sl_bt_evt_gatt_server_indication_timeout This event indicates confirmation from the remote GATT client has not been received within 30 seconds after an indication was sent.

Enumerations#

enum | sl_bt_gatt_server_client_configuration_t { sl_bt_gatt_server_disable = 0x0, sl_bt_gatt_server_notification = 0x1, sl_bt_gatt_server_indication = 0x2, sl_bt_gatt_server_notification_and_indication = 0x3 } | These values define whether the server is to sent notifications or indications to a remote GATT server.

enum | sl_bt_gatt_server_characteristic_status_flag_t { sl_bt_gatt_server_client_config = 0x1, sl_bt_gatt_server_confirmation = 0x2 } | These values describe whether the characteristic client configuration was changed or whether a characteristic confirmation was received.

Functions#

sl_status_t | sl_bt_gatt_server_set_max_mtu (uint16_t max_mtu, uint16_t *max_mtu_out)

sl_status_t | sl_bt_gatt_server_get_mtu (uint8_t connection, uint16_t *mtu)

sl_status_t | sl_bt_gatt_server_find_attribute (uint16_t start, size_t type_len, const uint8_t type, uint16_tattribute)

sl_status_t | sl_bt_gatt_server_read_attribute_value (uint16_t attribute, uint16_t offset, size_t max_value_size, size_t value_len, uint8_tvalue)

sl_status_t | sl_bt_gatt_server_read_attribute_type (uint16_t attribute, size_t max_type_size, size_t type_len, uint8_ttype)

sl_status_t | sl_bt_gatt_server_write_attribute_value (uint16_t attribute, uint16_t offset, size_t value_len, const uint8_t *value)

sl_status_t | sl_bt_gatt_server_send_user_read_response (uint8_t connection, uint16_t characteristic, uint8_t att_errorcode, size_t value_len, const uint8_t value, uint16_tsent_len)

sl_status_t | sl_bt_gatt_server_send_user_write_response (uint8_t connection, uint16_t characteristic, uint8_t att_errorcode)

SL_BGAPI_DEPRECATED sl_status_t | sl_bt_gatt_server_send_characteristic_notification (uint8_t connection, uint16_t characteristic, size_t value_len, const uint8_t value, uint16_tsent_len)

sl_status_t | sl_bt_gatt_server_send_notification (uint8_t connection, uint16_t characteristic, size_t value_len, const uint8_t *value)

sl_status_t | sl_bt_gatt_server_send_indication (uint8_t connection, uint16_t characteristic, size_t value_len, const uint8_t *value)

sl_status_t | sl_bt_gatt_server_notify_all (uint16_t characteristic, size_t value_len, const uint8_t *value)

sl_status_t | sl_bt_gatt_server_read_client_configuration (uint8_t connection, uint16_t characteristic, uint16_t *client_config_flags)

sl_status_t | sl_bt_gatt_server_send_user_prepare_write_response (uint8_t connection, uint16_t characteristic, uint8_t att_errorcode, uint16_t offset, size_t value_len, const uint8_t *value)

sl_status_t | sl_bt_gatt_server_set_capabilities (uint32_t caps, uint32_t reserved)

sl_status_t | sl_bt_gatt_server_enable_capabilities (uint32_t caps)

sl_status_t | sl_bt_gatt_server_disable_capabilities (uint32_t caps)

sl_status_t | sl_bt_gatt_server_get_enabled_capabilities (uint32_t *caps)

sl_status_t | sl_bt_gatt_server_read_client_supported_features (uint8_t connection, uint8_t *client_features)

Detailed Description#

GATT Server.

These commands and events are used for accessing to the local GATT server and database.

Enumeration Type Documentation#

◆ sl_bt_gatt_server_client_configuration_t#

enum sl_bt_gatt_server_client_configuration_t#

These values define whether the server is to sent notifications or indications to a remote GATT server.

Enumerator#

sl_bt_gatt_server_disable |

(0x0) Disable notifications and indications.

sl_bt_gatt_server_notification |

(0x1) The characteristic value shall be notified.

sl_bt_gatt_server_indication |

(0x2) The characteristic value shall be indicated.

sl_bt_gatt_server_notification_and_indication |

(0x3) The characteristic value notification and indication are enabled, application decides which one to send.

◆ sl_bt_gatt_server_characteristic_status_flag_t#

enum sl_bt_gatt_server_characteristic_status_flag_t#

These values describe whether the characteristic client configuration was changed or whether a characteristic confirmation was received.

Enumerator#

sl_bt_gatt_server_client_config |

(0x1) Characteristic client configuration has been changed.

sl_bt_gatt_server_confirmation |

(0x2) Characteristic confirmation has been received.

Function Documentation#

◆ sl_bt_gatt_server_set_max_mtu()#

Set the maximum size of ATT Message Transfer Units (MTU). The functionality is the same as sl_bt_gatt_set_max_mtu and this setting applies to both GATT client and server. If the given value is too large according to the maximum BGAPI payload size, the system will select the maximum possible value as the maximum ATT_MTU. If the maximum ATT_MTU is larger than 23, the GATT client in the stack will automatically send an MTU exchange request after a Bluetooth connection was established.

Parameters

 [in]| `max_mtu`|

Maximum size of Message Transfer Units (MTU) allowed

• Range: 23 to 250

Default: 247

---|---|--- [out]| max_mtu_out| The maximum ATT_MTU selected by the system if this command succeeded

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_get_mtu()#

Get the size of ATT Message Transfer Units (MTU) for a connection.

Parameters

 [in]| `connection`| Connection handle

---|---|--- [out]| mtu| The maximum ATT_MTU used by the connection

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_find_attribute()#

Find attributes of a certain type from a local GATT database. The type is usually given as a 16-bit or 128-bit UUID in little endian format.

Parameters

 [in]| `start`| Search start handle

---|---|--- [in]| type_len| Length of data in type [in]| type| The attribute type UUID [out]| attribute| Attribute handle

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_read_attribute_value()#

sl_status_t sl_bt_gatt_server_read_attribute_value | ( | uint16_t | attribute, ---|---|---|--- | | uint16_t | offset, | | size_t | max_value_size, | | size_t * | value_len, | | uint8_t* | value | ) | |

Read the value of an attribute from a local GATT database. Only (maximum BGAPI payload size - 3) amount of data can be read at once. The application can continue reading with increased offset value if it receives (maximum BGAPI payload size - 3) amount of data.

Parameters

 [in]| `attribute`| Attribute handle

---|---|--- [in]| offset| Value offset [in]| max_value_size| Size of output buffer passed in value [out]| value_len| On return, set to the length of output data written to value [out]| value| The attribute value

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_read_attribute_type()#

sl_status_t sl_bt_gatt_server_read_attribute_type | ( | uint16_t | attribute, ---|---|---|--- | | size_t | max_type_size, | | size_t * | type_len, | | uint8_t* | type | ) | |

Read the type of an attribute from a local GATT database. The type is a UUID, usually 16 or 128 bits long in little endian format.

Parameters

 [in]| `attribute`| Attribute handle

---|---|--- [in]| max_type_size| Size of output buffer passed in type [out]| type_len| On return, set to the length of output data written to type [out]| type| The attribute type UUID

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_write_attribute_value()#

sl_status_t sl_bt_gatt_server_write_attribute_value | ( | uint16_t | attribute, ---|---|---|--- | | uint16_t | offset, | | size_t | value_len, | | const uint8_t * | value | ) | |

Write the value of an attribute in the local GATT database. Writing the value of a characteristic of the local GATT database will not trigger notifications or indications to the remote GATT client if the characteristic has a property to indicate or notify and the client has enabled notification or indication. Notifications and indications are sent to the remote GATT client using sl_bt_gatt_server_send_notification or sl_bt_gatt_server_send_indication commands.

Parameters

 [in]| `attribute`| Attribute handle

---|---|--- [in]| offset| Value offset [in]| value_len| Length of data in value [in]| value| Value

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_send_user_read_response()#

sl_status_t sl_bt_gatt_server_send_user_read_response | ( | uint8_t | connection, ---|---|---|--- | | uint16_t | characteristic, | | uint8_t | att_errorcode, | | size_t | value_len, | | const uint8_t * | value, | | uint16_t* | sent_len | ) | |

Send a response to a sl_bt_evt_gatt_server_user_read_request event. The response needs to be sent within 30 seconds, otherwise no more GATT transactions are allowed by the remote side. If attr_errorcode is set to 0, the characteristic value is sent to the remote GATT client in the standard way. Other attr_errorcode values will cause the local GATT server to send an attribute protocol error response instead of the actual data. At most, ATT_MTU - 1 amount of data can be sent at one time. The client will continue reading by sending new read request with an increased offset value if it receives ATT_MTU - 1 amount of data.

Parameters

 [in]| `connection`| Connection handle

---|---|--- [in]| characteristic| GATT characteristic handle received in the sl_bt_evt_gatt_server_user_read_request event. [in]| att_errorcode| Attribute protocol error code

• 0: No error

• Non-zero: See Bluetooth specification, Host volume, Attribute Protocol, Error Codes table.

[in]| value_len| Length of data in value [in]| value| Characteristic value to send to the GATT client. Ignored if att_errorcode is not 0. [out]| sent_len| The length of data sent to the remote GATT client

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_send_user_write_response()#

sl_status_t sl_bt_gatt_server_send_user_write_response | ( | uint8_t | connection, ---|---|---|--- | | uint16_t | characteristic, | | uint8_t | att_errorcode | ) | |

Send a response to a sl_bt_evt_gatt_server_user_write_request event when parameter att_opcode in the event is sl_bt_gatt_write_request or sl_bt_gatt_execute_write_request (see sl_bt_gatt_att_opcode_t). The response needs to be sent within 30 seconds, otherwise no more GATT transactions are allowed by the remote side. When responding to sl_bt_gatt_execute_write_request, the value of parameter characteristic is ignored. If attr_errorcode is set to 0, the ATT protocol's write response is sent to indicate to the remote GATT client that the write operation was processed successfully. Other values will cause the local GATT server to send an ATT protocol error response.

Parameters

 [in]| `connection`| Connection handle

---|---|--- [in]| characteristic| GATT characteristic handle received in the sl_bt_evt_gatt_server_user_write_request event [in]| att_errorcode| Attribute protocol error code

• 0: No error

• Non-zero: See Bluetooth specification, Host volume, Attribute Protocol, Error Codes table.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_send_characteristic_notification()#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_gatt_server_send_characteristic_notification | ( | uint8_t | connection, ---|---|---|--- | | uint16_t | characteristic, | | size_t | value_len, | | const uint8_t * | value, | | uint16_t* | sent_len | ) | |

Deprecated and replaced by sl_bt_gatt_server_send_notification, sl_bt_gatt_server_send_indication and sl_bt_gatt_server_notify_all commands.

A notification or indication is sent only if the client has enabled it by setting the corresponding flag to the Client Characteristic Configuration descriptor. If the Client Characteristic Configuration descriptor supports both notifications and indications, the stack will always send a notification even when the client has enabled both.

Send notifications or indications to one or more remote GATT clients. At most, ATT_MTU - 3 amount of data can be sent one time.

A new indication to a GATT client can't be sent until an outstanding indication procedure with the same client has completed. The procedure is completed when a confirmation from the client is received. The confirmation is indicated by sl_bt_evt_gatt_server_characteristic_status.

The error SL_STATUS_INVALID_STATE is returned if the characteristic does not have the notification property, or if the client has not enabled the notification. The same applies to the indication property, and in addition, SL_STATUS_INVALID_STATE is returned if an indication procedure with the same client is outstanding. Always check the response for this command for errors before trying to send more data.

Parameters

 [in]| `connection`| A handle of the connection over which the notification or indication is sent. Values:

• 0xff: Sends notification or indication to all connected devices.

• Other: Connection handle

---|---|--- [in]| characteristic| Characteristic handle [in]| value_len| Length of data in value [in]| value| Value to be notified or indicated [out]| sent_len| The length of data sent if only one connected device is the receiver; otherwise an unused value.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_send_notification()#

sl_status_t sl_bt_gatt_server_send_notification | ( | uint8_t | connection, ---|---|---|--- | | uint16_t | characteristic, | | size_t | value_len, | | const uint8_t * | value | ) | |

Send a notification to a remote GATT client. At most ATT_MTU - 3 amount of data can be sent in a notification. An error SL_STATUS_COMMAND_TOO_LONG is returned if the given value length exceeds ATT_MTU - 3.

A notification is sent only if the client has enabled it by setting the corresponding flag to the Client Characteristic Configuration descriptor. The error SL_STATUS_INVALID_PARAMETER is returned if the characteristic does not have the notification property. The error SL_STATUS_INVALID_STATE is returned if the client has not enabled the notification.

Parameters

 [in]| `connection`| A handle of the connection over which the notification is sent.

---|---|--- [in]| characteristic| Characteristic handle [in]| value_len| Length of data in value [in]| value| Value to be notified

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_send_indication()#

Send an indication to a remote GATT client. At most, ATT_MTU - 3 amount of data can be sent in an indication. An error SL_STATUS_COMMAND_TOO_LONG is returned if the given value length exceeds ATT_MTU - 3.

An indication is sent only if the client has enabled it by setting the corresponding flag to the Client Characteristic Configuration descriptor. The error SL_STATUS_INVALID_PARAMETER is returned if the characteristic does not have the indication property. The error SL_STATUS_INVALID_STATE is returned if the client has not enabled the indication.

A new indication to a GATT client can't be sent until an outstanding indication procedure with the same client has completed. The procedure is completed when a confirmation from the client is received. The confirmation is indicated by sl_bt_evt_gatt_server_characteristic_status.

The error SL_STATUS_IN_PROGRESS is returned if an indication procedure with the same client is outstanding. Always wait for confirmation for previous indication before sending a new indication.

Parameters

 [in]| `connection`| A handle of the connection over which the indication is sent.

---|---|--- [in]| characteristic| Characteristic handle [in]| value_len| Length of data in value [in]| value| Value to be indicated

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_server_characteristic_status - This event is triggered after the confirmation from the client is received.

• sl_bt_evt_gatt_server_indication_timeout - This event indicates confirmation from the remote GATT client has not been received within 30 seconds after an indication was sent. Further GATT transactions over this connection are not allowed by the stack.

◆ sl_bt_gatt_server_notify_all()#

Send notifications or indications to all connected remote GATT clients. At most ATT_MTU - 3 amount of data can be sent in a notification or indication. If the given value length exceeds the limit, first ATT_MTU - 3 bytes will be sent without error, and rest of data will be ignored.

A notification or indication is sent only if the client has enabled it by setting the corresponding flag to the Client Characteristic Configuration descriptor. If the Client Characteristic Configuration descriptor supports both notifications and indications, the stack will always send a notification even when the client has enabled both.

A new indication to a GATT client can't be sent until an outstanding indication procedure with the same client has completed, and the operation will continue for the next client. The procedure is completed when a confirmation from the client is received. The confirmation is indicated by sl_bt_evt_gatt_server_characteristic_status.

Parameters

 [in]| `characteristic`| Characteristic handle

---|---|--- [in]| value_len| Length of data in value [in]| value| Value to be notified or indicated

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_read_client_configuration()#

sl_status_t sl_bt_gatt_server_read_client_configuration | ( | uint8_t | connection, ---|---|---|--- | | uint16_t | characteristic, | | uint16_t * | client_config_flags | ) | |

Read client characteristic configuration of a remote GATT client.

Parameters

 [in]| `connection`| A handle of the connection to a remote client.

---|---|--- [in]| characteristic| Characteristic handle [out]| client_config_flags| Enum sl_bt_gatt_server_client_configuration_t. Client characteristic configuration of a remote client.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_send_user_prepare_write_response()#

sl_status_t sl_bt_gatt_server_send_user_prepare_write_response | ( | uint8_t | connection, ---|---|---|--- | | uint16_t | characteristic, | | uint8_t | att_errorcode, | | uint16_t | offset, | | size_t | value_len, | | const uint8_t * | value | ) | |

Send a response to a sl_bt_evt_gatt_server_user_write_request event when parameter att_opcode in the event is sl_bt_gatt_prepare_write_request (see sl_bt_gatt_att_opcode_t). The response needs to be sent within 30 seconds, otherwise no more GATT transactions are allowed by the remote side. If att_errorcode is set to 0, the ATT protocol's prepare write response is sent to indicate to the remote GATT client that the write operation was processed successfully. Other values will cause the local GATT server to send an ATT protocol error response. The application should set values of parameters offset and value to identical values from the sl_bt_evt_gatt_server_user_write_request event, the values will be verified on the client side in case the request is a reliable write (by Bluetooth Core Specification Volume 3, Part G, 4.9.5).

Parameters

 [in]| `connection`| Connection handle

---|---|--- [in]| characteristic| GATT characteristic handle. This value is normally received from the gatt_characteristic event. [in]| att_errorcode| Attribute protocol error code

• 0: No error

• Non-zero: See Bluetooth specification, Host volume, Attribute Protocol, Error Codes table.

[in]| offset| Value offset [in]| value_len| Length of data in value [in]| value| Value

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_set_capabilities()#

Reset capabilities that should be enabled by the GATT database. A service is visible to remote GATT clients if at least one of its capabilities is enabled. The same applies to a characteristic and its attributes. Capability identifiers and their corresponding bit flag values are in the auto-generated database header file. See UG118: Blue Gecko Bluetooth Profile Toolkit Developer's Guide for how to declare capabilities in the GATT database.

Changing the capabilities of a database effectively causes a database change (attributes being added or removed) from a remote GATT client point of view. If the database has a Generic Attribute service and Service Changed characteristic, the stack will monitor the local database change status and manage service changed indications for a GATT client that has enabled the indication configuration of the Service Changed characteristic.

Parameters

 [in]| `caps`| Bit flags of capabilities to reset. Value 0 sets the default database capabilities.

---|---|--- [in]| reserved| Use the value 0 on this reserved field. Do not use none-zero values because they are reserved for future use.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_enable_capabilities()#

sl_status_t sl_bt_gatt_server_enable_capabilities | ( | uint32_t | caps| ) | ---|---|---|---|---|---

Enable additional capabilities in the local GATT database. Already enabled capabilities keep unchanged after this command. See sl_bt_gatt_server_set_capabilities for more information.

Parameters

 [in]| `caps`| Capabilities to enable

---|---|---

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_disable_capabilities()#

sl_status_t sl_bt_gatt_server_disable_capabilities | ( | uint32_t | caps| ) | ---|---|---|---|---|---

Disable the given capabilities in the local GATT database. See sl_bt_gatt_server_set_capabilities for more information.

Parameters

 [in]| `caps`| Capabilities to disable

---|---|---

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_get_enabled_capabilities()#

sl_status_t sl_bt_gatt_server_get_enabled_capabilities | ( | uint32_t * | caps| ) | ---|---|---|---|---|---

Get capabilities currently enabled in the local GATT database.

Parameters

 [out]| `caps`| Enabled capabilities

---|---|---

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_gatt_server_read_client_supported_features()#

sl_status_t sl_bt_gatt_server_read_client_supported_features | ( | uint8_t | connection, ---|---|---|--- | | uint8_t * | client_features | ) | |

Read client supported features of a remote GATT client.

Parameters

 [in]| `connection`| A handle of the connection to a remote client.

---|---|--- [out]| client_features| Bit field describing client supported features of a remote client. See Bluetooth specification Vol 3, Part G, 7.2 for the values.

Returns

SL_STATUS_OK if successful. Error code otherwise.