sd_ble_gattc_write()

uint32_t sd_ble_gattc_write	(	uint16_t	conn_handle,
		ble_gattc_write_params_t const *	p_write_params )

#include <ble_gattc.h>

Perform a Write (Characteristic Value or Descriptor, with or without response, long or reliable) procedure.

This function can perform all write procedures described in GATT.

Note

Only one write with response procedure can be ongoing per connection at a time. If the application tries to write with response while another write with response procedure is ongoing, the function call will return NRF_ERROR_BUSY. A BLE_GATTC_EVT_WRITE_RSP event will be issued as soon as the write response arrives from the peer.

The minimum guaranteed number of Write without Response that can be queued is configured by ble_gattc_conn_cfg_t::write_cmd_tx_queue_size When the queue is full, the function call will return NRF_ERROR_RESOURCES. A BLE_GATTC_EVT_WRITE_CMD_TX_COMPLETE event will be issued as soon as the transmission of the write without response is complete.

The application can keep track of the available queue element count for writes without responses 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_GATTC_EVT_WRITE_CMD_TX_COMPLETE event.

Events generated

BLE_GATTC_EVT_WRITE_CMD_TX_COMPLETE	Write without response transmission complete.
BLE_GATTC_EVT_WRITE_RSP	Write response received from the peer.

Relevant Message Sequence Charts

GATTC Characteristic Value Write Without Response

GATTC Characteristic or Descriptor Value Write

GATTC Characteristic or Descriptor Value Long Write

GATTC Characteristic or Descriptor Value Reliable Write

Parameters

[in]	conn_handle	The connection handle identifying the connection to perform this procedure on.
[in]	p_write_params	A pointer to a write parameters structure.

Return values

NRF_SUCCESS	Successfully started the Write procedure.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_STATE	Invalid Connection State.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied.
NRF_ERROR_DATA_SIZE	Invalid data size(s) supplied.
NRF_ERROR_BUSY	For write with response, procedure already in progress. Wait for a BLE_GATTC_EVT_WRITE_RSP event and retry.
NRF_ERROR_RESOURCES	Too many writes without responses queued. Wait for a BLE_GATTC_EVT_WRITE_CMD_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.