Functions

Retrieve the attribute UUID and/or metadata.

Parameters

[in]	handle	Attribute handle
[out]	p_uuid	UUID of the attribute. Use NULL to omit this field.
[out]	p_md	Metadata of the attribute. Use NULL to omit this field.

Return values

NRF_SUCCESS	Successfully retrieved the attribute metadata,
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameters supplied. Returned when both p_uuid and p_md are NULL.
NRF_ERROR_NOT_FOUND	Attribute was not found.

Add a characteristic declaration, a characteristic value declaration and optional characteristic descriptor declarations to the Attribute Table.

Note

It is currently only possible to add a characteristic to the last added service (i.e. only sequential population is supported at this time).

Several restrictions apply to the parameters, such as matching permissions between the user description descriptor and the writable auxiliaries bits, readable (no security) and writable (selectable) CCCDs and SCCDs and valid presentation format values.

If no metadata is provided for the optional descriptors, their permissions will be derived from the characteristic permissions.

Relevant Message Sequence Charts

BLE_GATTS_ATT_TABLE_POP_MSC

Parameters

[in]	service_handle	Handle of the service where the characteristic is to be placed, if BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
[in]	p_char_md	Characteristic metadata.
[in]	p_attr_char_value	Pointer to the attribute structure corresponding to the characteristic value.
[out]	p_handles	Pointer to the structure where the assigned handles will be stored.

Return values

NRF_SUCCESS	Successfully added a characteristic.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied, service handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints.
NRF_ERROR_INVALID_STATE	Invalid state to perform operation, a service context is required.
NRF_ERROR_FORBIDDEN	Forbidden value supplied, certain UUIDs are reserved for the stack.
NRF_ERROR_NO_MEM	Not enough memory to complete operation.
NRF_ERROR_DATA_SIZE	Invalid data size(s) supplied, attribute lengths are restricted by Maximum attribute lengths .

Add a descriptor to the Attribute Table.

Note

It is currently only possible to add a descriptor to the last added characteristic (i.e. only sequential population is supported at this time).

Relevant Message Sequence Charts

BLE_GATTS_ATT_TABLE_POP_MSC

Parameters

[in]	char_handle	Handle of the characteristic where the descriptor is to be placed, if BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
[in]	p_attr	Pointer to the attribute structure.
[out]	p_handle	Pointer to a 16-bit word where the assigned handle will be stored.

Return values

NRF_SUCCESS	Successfully added a descriptor.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied, characteristic handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints.
NRF_ERROR_INVALID_STATE	Invalid state to perform operation, a characteristic context is required.
NRF_ERROR_FORBIDDEN	Forbidden value supplied, certain UUIDs are reserved for the stack.
NRF_ERROR_NO_MEM	Not enough memory to complete operation.
NRF_ERROR_DATA_SIZE	Invalid data size(s) supplied, attribute lengths are restricted by Maximum attribute lengths .

Reply to an ATT_MTU exchange request by sending an Exchange MTU Response to the client.

This function is only used to reply to a BLE_GATTS_EVT_EXCHANGE_MTU_REQUEST event.

The SoftDevice sets ATT_MTU to the minimum of:

• The Client RX MTU value from BLE_GATTS_EVT_EXCHANGE_MTU_REQUEST , and
• The Server RX MTU value.

However, the SoftDevice never sets ATT_MTU lower than BLE_GATT_ATT_MTU_DEFAULT .

Relevant Message Sequence Charts

BLE_GATTS_MTU_EXCHANGE

Parameters

[in]	conn_handle	The connection handle identifying the connection to perform this procedure on.
[in]	server_rx_mtu	Server RX MTU size. The minimum value is BLE_GATT_ATT_MTU_DEFAULT . The maximum value is ble_gatt_conn_cfg_t::att_mtu in the connection configuration used for this connection. The value must be equal to Client RX MTU size given in sd_ble_gattc_exchange_mtu_request if an ATT_MTU exchange has already been performed in the other direction.

Return values

NRF_SUCCESS	Successfully sent response to the client.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_STATE	Invalid Connection State or no ATT_MTU exchange request pending.
NRF_ERROR_INVALID_PARAM	Invalid Server RX MTU size supplied.
NRF_ERROR_TIMEOUT	There has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.

Notify or Indicate an attribute value.

This function checks for the relevant Client Characteristic Configuration descriptor value to verify that the relevant operation (notification or indication) has been enabled by the client. It is also able to update the attribute value before issuing the PDU, so that the application can atomically perform a value update and a server initiated transaction with a single API call.

Note

The local attribute value may be updated even if an outgoing packet is not sent to the peer due to an error during execution. The Attribute Table has been updated if one of the following error codes is returned: NRF_ERROR_INVALID_STATE , NRF_ERROR_BUSY , NRF_ERROR_FORBIDDEN , BLE_ERROR_GATTS_SYS_ATTR_MISSING and NRF_ERROR_RESOURCES . The caller can check whether the value has been updated by looking at the contents of *( ble_gatts_hvx_params_t::p_len ).

Only one indication procedure can be ongoing per connection at a time. If the application tries to indicate an attribute value while another indication procedure is ongoing, the function call will return NRF_ERROR_BUSY . A BLE_GATTS_EVT_HVC event will be issued as soon as the confirmation arrives from the peer.

The number of Handle Value Notifications that can be queued is configured by ble_gatts_conn_cfg_t::hvn_tx_queue_size When the queue is full, the function call will return NRF_ERROR_RESOURCES . A BLE_GATTS_EVT_HVN_TX_COMPLETE event will be issued as soon as the transmission of the notification is complete.

The application can keep track of the available queue element count for notifications by following the procedure below:

• Store initial queue element count in a variable.
• Decrement the variable, which stores the currently available queue element count, by one when a call to this function returns NRF_SUCCESS .
• Increment the variable, which stores the current available queue element count, by the count variable in BLE_GATTS_EVT_HVN_TX_COMPLETE event.

Events generated

BLE_GATTS_EVT_HVN_TX_COMPLETE	Notification transmission complete.
BLE_GATTS_EVT_HVC	Confirmation received from the peer.

Relevant Message Sequence Charts

BLE_GATTS_HVX_SYS_ATTRS_MISSING_MSC

BLE_GATTS_HVN_MSC

BLE_GATTS_HVI_MSC

BLE_GATTS_HVX_DISABLED_MSC

Parameters

[in]	conn_handle	Connection handle.
[in,out]	p_hvx_params	Pointer to an HVx parameters structure. If ble_gatts_hvx_params_t::p_data contains a non-NULL pointer the attribute value will be updated with the contents pointed by it before sending the notification or indication. If the attribute value is updated, ble_gatts_hvx_params_t::p_len is updated by the SoftDevice to contain the number of actual bytes written, else it will be set to 0.

Return values

NRF_SUCCESS	Successfully queued a notification or indication for transmission, and optionally updated the attribute value.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_STATE	One or more of the following is true: Invalid Connection State Notifications and/or indications not enabled in the CCCD An ATT_MTU exchange is ongoing
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied.
BLE_ERROR_INVALID_ATTR_HANDLE	Invalid attribute handle(s) supplied. Only attributes added directly by the application are available to notify and indicate.
BLE_ERROR_GATTS_INVALID_ATTR_TYPE	Invalid attribute type(s) supplied, only characteristic values may be notified and indicated.
NRF_ERROR_NOT_FOUND	Attribute not found.
NRF_ERROR_FORBIDDEN	The connection's current security level is lower than the one required by the write permissions of the CCCD associated with this characteristic.
NRF_ERROR_DATA_SIZE	Invalid data size(s) supplied.
NRF_ERROR_BUSY	For BLE_GATT_HVX_INDICATION Procedure already in progress. Wait for a BLE_GATTS_EVT_HVC event and retry.
BLE_ERROR_GATTS_SYS_ATTR_MISSING	System attributes missing, use sd_ble_gatts_sys_attr_set to set them to a known value.
NRF_ERROR_RESOURCES	Too many notifications queued. Wait for a BLE_GATTS_EVT_HVN_TX_COMPLETE event and retry.
NRF_ERROR_TIMEOUT	There has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.

Add an include declaration to the Attribute Table.

Note

It is currently only possible to add an include declaration to the last added service (i.e. only sequential population is supported at this time).

The included service must already be present in the Attribute Table prior to this call.

Relevant Message Sequence Charts

BLE_GATTS_ATT_TABLE_POP_MSC

Parameters

[in]	service_handle	Handle of the service where the included service is to be placed, if BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
[in]	inc_srvc_handle	Handle of the included service.
[out]	p_include_handle	Pointer to a 16-bit word where the assigned handle will be stored.

Return values

NRF_SUCCESS	Successfully added an include declaration.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied, handle values need to match previously added services.
NRF_ERROR_INVALID_STATE	Invalid state to perform operation, a service context is required.
NRF_ERROR_NOT_SUPPORTED	Feature is not supported, service_handle must be that of the last added service.
NRF_ERROR_FORBIDDEN	Forbidden value supplied, self inclusions are not allowed.
NRF_ERROR_NO_MEM	Not enough memory to complete operation.
NRF_ERROR_NOT_FOUND	Attribute not found.

Retrieve the first valid user attribute handle.

Parameters

[out]

p_handle

Pointer to an integer where the handle will be stored.

Return values

NRF_SUCCESS	Successfully retrieved the handle.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.

Respond to a Read/Write authorization request.

Note

This call should only be used as a response to a BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST event issued to the application.

Relevant Message Sequence Charts

BLE_GATTS_QUEUED_WRITE_NOBUF_AUTH_MSC

BLE_GATTS_QUEUED_WRITE_BUF_AUTH_MSC

BLE_GATTS_QUEUED_WRITE_NOBUF_NOAUTH_MSC

BLE_GATTS_READ_REQ_AUTH_MSC

BLE_GATTS_WRITE_REQ_AUTH_MSC

BLE_GATTS_QUEUED_WRITE_QUEUE_FULL_MSC

BLE_GATTS_QUEUED_WRITE_PEER_CANCEL_MSC

Parameters

[in]	conn_handle	Connection handle.
[in]	p_rw_authorize_reply_params	Pointer to a structure with the attribute provided by the application.

Note

ble_gatts_authorize_params_t::p_data is ignored when this function is used to respond to a BLE_GATTS_AUTHORIZE_TYPE_READ event if ble_gatts_authorize_params_t::update is set to 0.

Return values

NRF_SUCCESS	Successfully queued a response to the peer, and in the case of a write operation, Attribute Table updated.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_BUSY	The stack is busy, process pending events and retry.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_STATE	Invalid Connection State or no authorization request pending.
NRF_ERROR_INVALID_PARAM	Authorization op invalid, handle supplied does not match requested handle, or invalid data to be written provided by the application.
NRF_ERROR_TIMEOUT	There has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.

Add a service declaration to the Attribute Table.

Note

Secondary Services are only relevant in the context of the entity that references them, it is therefore forbidden to add a secondary service declaration that is not referenced by another service later in the Attribute Table.

Relevant Message Sequence Charts

BLE_GATTS_ATT_TABLE_POP_MSC

Parameters

[in]	type	Toggles between primary and secondary services, see GATT Server Service Types .
[in]	p_uuid	Pointer to service UUID.
[out]	p_handle	Pointer to a 16-bit word where the assigned handle will be stored.

Return values

NRF_SUCCESS	Successfully added a service declaration.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied, Vendor Specific UUIDs need to be present in the table.
NRF_ERROR_FORBIDDEN	Forbidden value supplied, certain UUIDs are reserved for the stack.
NRF_ERROR_NO_MEM	Not enough memory to complete operation.

Indicate the Service Changed attribute value.

This call will send a Handle Value Indication to one or more peers connected to inform them that the Attribute Table layout has changed. As soon as the peer has confirmed the indication, a BLE_GATTS_EVT_SC_CONFIRM event will be issued.

Note

Some of the restrictions and limitations that apply to sd_ble_gatts_hvx also apply here.

Events generated

BLE_GATTS_EVT_SC_CONFIRM

Confirmation of attribute table change received from peer.

Relevant Message Sequence Charts

BLE_GATTS_SC_MSC

Parameters

[in]	conn_handle	Connection handle.
[in]	start_handle	Start of affected attribute handle range.
[in]	end_handle	End of affected attribute handle range.

Return values

NRF_SUCCESS	Successfully queued the Service Changed indication for transmission.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_NOT_SUPPORTED	Service Changed not enabled at initialization. See sd_ble_cfg_set and ble_gatts_cfg_service_changed_t .
NRF_ERROR_INVALID_STATE	One or more of the following is true: Invalid Connection State Notifications and/or indications not enabled in the CCCD An ATT_MTU exchange is ongoing
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied.
BLE_ERROR_INVALID_ATTR_HANDLE	Invalid attribute handle(s) supplied, handles must be in the range populated by the application.
NRF_ERROR_BUSY	Procedure already in progress.
BLE_ERROR_GATTS_SYS_ATTR_MISSING	System attributes missing, use sd_ble_gatts_sys_attr_set to set them to a known value.
NRF_ERROR_TIMEOUT	There has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.

Retrieve persistent system attribute information from the stack.

This call is used to retrieve information about values to be stored persistently by the application during the lifetime of a connection or after it has been terminated. When a new connection is established with the same bonded device, the system attribute information retrieved with this function should be restored using using sd_ble_gatts_sys_attr_set . If retrieved after disconnection, the data should be read before a new connection established. The connection handle for the previous, now disconnected, connection will remain valid until a new one is created to allow this API call to refer to it. Connection handles belonging to active connections can be used as well, but care should be taken since the system attributes may be written to at any time by the peer during a connection's lifetime.

Note

When the BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS is used with this function, only the system attributes included in system services will be returned.

When the BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS is used with this function, only the system attributes included in user services will be returned.

Relevant Message Sequence Charts

BLE_GATTS_SYS_ATTRS_BONDED_PEER_MSC

Parameters

[in]	conn_handle	Connection handle of the recently terminated connection.
[out]	p_sys_attr_data	Pointer to a buffer where updated information about system attributes will be filled in. The format of the data is described in BLE_GATTS_SYS_ATTRS_FORMAT. NULL can be provided to obtain the length of the data.
[in,out]	p_len	Size of application buffer if p_sys_attr_data is not NULL. Unconditionally updated to actual length of system attribute data.
[in]	flags	Optional additional flags, see System Attribute Flags

Return values

NRF_SUCCESS	Successfully retrieved the system attribute information.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid flags supplied.
NRF_ERROR_DATA_SIZE	The system attribute information did not fit into the provided buffer.
NRF_ERROR_NOT_FOUND	No system attributes found.

Update persistent system attribute information.

Supply information about persistent system attributes to the stack, previously obtained using sd_ble_gatts_sys_attr_get . This call is only allowed for active connections, and is usually made immediately after a connection is established with an known bonded device, often as a response to a BLE_GATTS_EVT_SYS_ATTR_MISSING .

p_sysattrs may point directly to the application's stored copy of the system attributes obtained using sd_ble_gatts_sys_attr_get . If the pointer is NULL, the system attribute info is initialized, assuming that the application does not have any previously saved system attribute data for this device.

Note

The state of persistent system attributes is reset upon connection establishment and then remembered for its duration.

If this call returns with an error code different from NRF_SUCCESS , the storage of persistent system attributes may have been completed only partially. This means that the state of the attribute table is undefined, and the application should either provide a new set of attributes using this same call or reset the SoftDevice to return to a known state.

When the BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS is used with this function, only the system attributes included in system services will be modified.

When the BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS is used with this function, only the system attributes included in user services will be modified.

Relevant Message Sequence Charts

BLE_GATTS_HVX_SYS_ATTRS_MISSING_MSC

BLE_GATTS_SYS_ATTRS_UNK_PEER_MSC

BLE_GATTS_SYS_ATTRS_BONDED_PEER_MSC

Parameters

[in]	conn_handle	Connection handle.
[in]	p_sys_attr_data	Pointer to a saved copy of system attributes supplied to the stack, or NULL.
[in]	len	Size of data pointed by p_sys_attr_data, in octets.
[in]	flags	Optional additional flags, see System Attribute Flags

Return values

NRF_SUCCESS	Successfully set the system attribute information.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_STATE	Invalid Connection State.
NRF_ERROR_INVALID_PARAM	Invalid flags supplied.
NRF_ERROR_INVALID_DATA	Invalid data supplied, the data should be exactly the same as retrieved with sd_ble_gatts_sys_attr_get .
NRF_ERROR_NO_MEM	Not enough memory to complete operation.

Get the value of a given attribute.

Note

If the attribute value is longer than the size of the supplied buffer, ble_gatts_value_t::len will return the total attribute value length (excluding offset), and not the number of bytes actually returned in ble_gatts_value_t::p_value . The application may use this information to allocate a suitable buffer size.

When retrieving system attribute values with this function, the connection handle may refer to an already disconnected connection. Refer to the documentation of sd_ble_gatts_sys_attr_get for further information.

Parameters

[in]	conn_handle	Connection handle. Ignored if the value does not belong to a system attribute.
[in]	handle	Attribute handle.
[in,out]	p_value	Attribute value information.

Return values

NRF_SUCCESS	Successfully retrieved the value of the attribute.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_NOT_FOUND	Attribute not found.
NRF_ERROR_INVALID_PARAM	Invalid attribute offset supplied.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid connection handle supplied on a system attribute.
BLE_ERROR_GATTS_SYS_ATTR_MISSING	System attributes missing, use sd_ble_gatts_sys_attr_set to set them to a known value.

Set the value of a given attribute.

Note

Values other than system attributes can be set at any time, regardless of whether any active connections exist.

Relevant Message Sequence Charts

BLE_GATTS_QUEUED_WRITE_QUEUE_FULL_MSC

BLE_GATTS_QUEUED_WRITE_NOBUF_NOAUTH_MSC

Parameters

[in]	conn_handle	Connection handle. Ignored if the value does not belong to a system attribute.
[in]	handle	Attribute handle.
[in,out]	p_value	Attribute value information.

Return values

NRF_SUCCESS	Successfully set the value of the attribute.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied.
NRF_ERROR_NOT_FOUND	Attribute not found.
NRF_ERROR_FORBIDDEN	Forbidden handle supplied, certain attributes are not modifiable by the application.
NRF_ERROR_DATA_SIZE	Invalid data size(s) supplied, attribute lengths are restricted by Maximum attribute lengths .
BLE_ERROR_INVALID_CONN_HANDLE	Invalid connection handle supplied on a system attribute.