sd_ble_gatts_hvx()

uint32_t sd_ble_gatts_hvx	(	uint16_t	conn_handle,
		ble_gatts_hvx_params_t const *	p_hvx_params )

#include <ble_gatts.h>

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 minimum guaranteed 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

GATTS Handle Value Indication or Notification with System Attributes Missing

GATTS Handle Value Notification

GATTS Handle Value Indication

GATTS Handle Value Indication or Notification disabled

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.