S113 SoftDevice v7.2.0
Functions

Functions

uint32_t sd_ble_gattc_primary_services_discover (uint16_t conn_handle, uint16_t start_handle, ble_uuid_t const *p_srvc_uuid)
 Initiate or continue a GATT Primary Service Discovery procedure. More...
 
uint32_t sd_ble_gattc_relationships_discover (uint16_t conn_handle, ble_gattc_handle_range_t const *p_handle_range)
 Initiate or continue a GATT Relationship Discovery procedure. More...
 
uint32_t sd_ble_gattc_characteristics_discover (uint16_t conn_handle, ble_gattc_handle_range_t const *p_handle_range)
 Initiate or continue a GATT Characteristic Discovery procedure. More...
 
uint32_t sd_ble_gattc_descriptors_discover (uint16_t conn_handle, ble_gattc_handle_range_t const *p_handle_range)
 Initiate or continue a GATT Characteristic Descriptor Discovery procedure. More...
 
uint32_t sd_ble_gattc_char_value_by_uuid_read (uint16_t conn_handle, ble_uuid_t const *p_uuid, ble_gattc_handle_range_t const *p_handle_range)
 Initiate or continue a GATT Read using Characteristic UUID procedure. More...
 
uint32_t sd_ble_gattc_read (uint16_t conn_handle, uint16_t handle, uint16_t offset)
 Initiate or continue a GATT Read (Long) Characteristic or Descriptor procedure. More...
 
uint32_t sd_ble_gattc_char_values_read (uint16_t conn_handle, uint16_t const *p_handles, uint16_t handle_count)
 Initiate a GATT Read Multiple Characteristic Values procedure. More...
 
uint32_t sd_ble_gattc_write (uint16_t conn_handle, ble_gattc_write_params_t const *p_write_params)
 Perform a Write (Characteristic Value or Descriptor, with or without response, signed or not, long or reliable) procedure. More...
 
uint32_t sd_ble_gattc_hv_confirm (uint16_t conn_handle, uint16_t handle)
 Send a Handle Value Confirmation to the GATT Server. More...
 
uint32_t sd_ble_gattc_attr_info_discover (uint16_t conn_handle, ble_gattc_handle_range_t const *p_handle_range)
 Discovers information about a range of attributes on a GATT server. More...
 
uint32_t sd_ble_gattc_exchange_mtu_request (uint16_t conn_handle, uint16_t client_rx_mtu)
 Start an ATT_MTU exchange by sending an Exchange MTU Request to the server. More...
 
__STATIC_INLINE uint32_t sd_ble_gattc_evt_char_val_by_uuid_read_rsp_iter (ble_gattc_evt_t *p_gattc_evt, ble_gattc_handle_value_t *p_iter)
 Iterate through Handle-Value(s) list in BLE_GATTC_EVT_CHAR_VAL_BY_UUID_READ_RSP event. More...
 

Detailed Description

Function Documentation

uint32_t sd_ble_gattc_attr_info_discover ( uint16_t  conn_handle,
ble_gattc_handle_range_t const *  p_handle_range 
)

Discovers information about a range of attributes on a GATT server.

Events generated
BLE_GATTC_EVT_ATTR_INFO_DISC_RSPGenerated when information about a range of attributes has been received.
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]p_handle_rangeThe range of handles to request information about.
Return values
NRF_SUCCESSSuccessfully started an attribute information discovery procedure.
BLE_ERROR_INVALID_CONN_HANDLEInvalid connection handle.
NRF_ERROR_INVALID_STATEInvalid connection state
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_BUSYClient procedure already in progress.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
uint32_t sd_ble_gattc_char_value_by_uuid_read ( uint16_t  conn_handle,
ble_uuid_t const *  p_uuid,
ble_gattc_handle_range_t const *  p_handle_range 
)

Initiate or continue a GATT Read using Characteristic UUID procedure.

This function initiates or resumes a Read using Characteristic UUID procedure. If the last Characteristic has not been reached, this must be called again with an updated handle range to continue the discovery.

Events generated
BLE_GATTC_EVT_CHAR_VAL_BY_UUID_READ_RSP
Relevant Message Sequence Charts
GATTC Read Characteristic Value by UUID
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]p_uuidPointer to a Characteristic value UUID to read.
[in]p_handle_rangeA pointer to the range of handles to perform this procedure on.
Return values
NRF_SUCCESSSuccessfully started or resumed the Read using Characteristic UUID procedure.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_BUSYClient procedure already in progress.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
uint32_t sd_ble_gattc_char_values_read ( uint16_t  conn_handle,
uint16_t const *  p_handles,
uint16_t  handle_count 
)

Initiate a GATT Read Multiple Characteristic Values procedure.

This function initiates a GATT Read Multiple Characteristic Values procedure.

Events generated
BLE_GATTC_EVT_CHAR_VALS_READ_RSP
Relevant Message Sequence Charts
GATTC Read Multiple Characteristic Values
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]p_handlesA pointer to the handle(s) of the attribute(s) to be read.
[in]handle_countThe number of handles in p_handles.
Return values
NRF_SUCCESSSuccessfully started the Read Multiple Characteristic Values procedure.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_BUSYClient procedure already in progress.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
uint32_t sd_ble_gattc_characteristics_discover ( uint16_t  conn_handle,
ble_gattc_handle_range_t const *  p_handle_range 
)

Initiate or continue a GATT Characteristic Discovery procedure.

This function initiates or resumes a Characteristic discovery procedure. If the last Characteristic has not been reached, this must be called again with an updated handle range to continue the discovery. See also ble_gattc_opt_uuid_disc_t.

Events generated
BLE_GATTC_EVT_CHAR_DISC_RSP
Relevant Message Sequence Charts
GATTC Characteristic Discovery
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]p_handle_rangeA pointer to the range of handles of the Service to perform this procedure on.
Return values
NRF_SUCCESSSuccessfully started or resumed the Characteristic Discovery procedure.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_BUSYClient procedure already in progress.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
uint32_t sd_ble_gattc_descriptors_discover ( uint16_t  conn_handle,
ble_gattc_handle_range_t const *  p_handle_range 
)

Initiate or continue a GATT Characteristic Descriptor Discovery procedure.

This function initiates or resumes a Characteristic Descriptor discovery procedure. If the last Descriptor has not been reached, this must be called again with an updated handle range to continue the discovery. See also ble_gattc_opt_uuid_disc_t.

Events generated
BLE_GATTC_EVT_DESC_DISC_RSP
Relevant Message Sequence Charts
GATTC Descriptor Discovery
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]p_handle_rangeA pointer to the range of handles of the Characteristic to perform this procedure on.
Return values
NRF_SUCCESSSuccessfully started or resumed the Descriptor Discovery procedure.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_BUSYClient procedure already in progress.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
__STATIC_INLINE uint32_t sd_ble_gattc_evt_char_val_by_uuid_read_rsp_iter ( ble_gattc_evt_t p_gattc_evt,
ble_gattc_handle_value_t p_iter 
)

Iterate through Handle-Value(s) list in BLE_GATTC_EVT_CHAR_VAL_BY_UUID_READ_RSP event.

Parameters
[in]p_gattc_evtPointer to event buffer containing BLE_GATTC_EVT_CHAR_VAL_BY_UUID_READ_RSP event.
Note
If the buffer contains different event, behavior is undefined.
Parameters
[in,out]p_iterIterator, points to ble_gattc_handle_value_t structure that will be filled in with the next Handle-Value pair in each iteration. If the function returns other than NRF_SUCCESS, it will not be changed.
  • To start iteration, initialize the structure to zero.
  • To continue, pass the value from previous iteration.
memset(&iter, 0, sizeof(ble_gattc_handle_value_t));
while (sd_ble_gattc_evt_char_val_by_uuid_read_rsp_iter(&ble_evt.evt.gattc_evt, &iter) == NRF_SUCCESS)
{
app_handle = iter.handle;
memcpy(app_value, iter.p_value, ble_evt.evt.gattc_evt.params.char_val_by_uuid_read_rsp.value_len);
}
Return values
NRF_SUCCESSSuccessfully retrieved the next Handle-Value pair.
NRF_ERROR_NOT_FOUNDNo more Handle-Value pairs available in the list.
uint32_t sd_ble_gattc_exchange_mtu_request ( uint16_t  conn_handle,
uint16_t  client_rx_mtu 
)

Start an ATT_MTU exchange by sending an Exchange MTU Request to the server.

The SoftDevice sets ATT_MTU to the minimum of:

However, the SoftDevice never sets ATT_MTU lower than BLE_GATT_ATT_MTU_DEFAULT.

Events generated
BLE_GATTC_EVT_EXCHANGE_MTU_RSP
Relevant Message Sequence Charts
GATTC ATT_MTU Exchange
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]client_rx_mtuClient RX MTU size.
Return values
NRF_SUCCESSSuccessfully sent request to the server.
BLE_ERROR_INVALID_CONN_HANDLEInvalid connection handle.
NRF_ERROR_INVALID_STATEInvalid connection state or an ATT_MTU exchange was already requested once.
NRF_ERROR_INVALID_PARAMInvalid Client RX MTU size supplied.
NRF_ERROR_BUSYClient procedure already in progress.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
uint32_t sd_ble_gattc_hv_confirm ( uint16_t  conn_handle,
uint16_t  handle 
)

Send a Handle Value Confirmation to the GATT Server.

Relevant Message Sequence Charts
GATTC Handle Value Indication
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]handleThe handle of the attribute in the indication.
Return values
NRF_SUCCESSSuccessfully queued the Handle Value Confirmation for transmission.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State or no Indication pending to be confirmed.
BLE_ERROR_INVALID_ATTR_HANDLEInvalid attribute handle.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
uint32_t sd_ble_gattc_primary_services_discover ( uint16_t  conn_handle,
uint16_t  start_handle,
ble_uuid_t const *  p_srvc_uuid 
)

Initiate or continue a GATT Primary Service Discovery procedure.

This function initiates or resumes a Primary Service discovery procedure, starting from the supplied handle. If the last service has not been reached, this function must be called again with an updated start handle value to continue the search. See also ble_gattc_opt_uuid_disc_t.

Events generated
BLE_GATTC_EVT_PRIM_SRVC_DISC_RSP
Relevant Message Sequence Charts
GATTC Primary Service Discovery
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]start_handleHandle to start searching from.
[in]p_srvc_uuidPointer to the service UUID to be found. If it is NULL, all primary services will be returned.
Return values
NRF_SUCCESSSuccessfully started or resumed the Primary Service Discovery procedure.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied.
NRF_ERROR_BUSYClient procedure already in progress.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
uint32_t sd_ble_gattc_read ( uint16_t  conn_handle,
uint16_t  handle,
uint16_t  offset 
)

Initiate or continue a GATT Read (Long) Characteristic or Descriptor procedure.

This function initiates or resumes a GATT Read (Long) Characteristic or Descriptor procedure. If the Characteristic or Descriptor to be read is longer than ATT_MTU - 1, this function must be called multiple times with appropriate offset to read the complete value.

Events generated
BLE_GATTC_EVT_READ_RSP
Relevant Message Sequence Charts
GATTC Characteristic or Descriptor Value Read
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]handleThe handle of the attribute to be read.
[in]offsetOffset into the attribute value to be read.
Return values
NRF_SUCCESSSuccessfully started or resumed the Read (Long) procedure.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State.
NRF_ERROR_BUSYClient procedure already in progress.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
uint32_t sd_ble_gattc_relationships_discover ( uint16_t  conn_handle,
ble_gattc_handle_range_t const *  p_handle_range 
)

Initiate or continue a GATT Relationship Discovery procedure.

This function initiates or resumes the Find Included Services sub-procedure. If the last included service has not been reached, this must be called again with an updated handle range to continue the search. See also ble_gattc_opt_uuid_disc_t.

Events generated
BLE_GATTC_EVT_REL_DISC_RSP
Relevant Message Sequence Charts
GATTC Relationship Discovery
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]p_handle_rangeA pointer to the range of handles of the Service to perform this procedure on.
Return values
NRF_SUCCESSSuccessfully started or resumed the Relationship Discovery procedure.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied.
NRF_ERROR_BUSYClient procedure already in progress.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
uint32_t sd_ble_gattc_write ( uint16_t  conn_handle,
ble_gattc_write_params_t const *  p_write_params 
)

Perform a Write (Characteristic Value or Descriptor, with or without response, signed or not, 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 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_COMPLETEWrite without response transmission complete.
BLE_GATTC_EVT_WRITE_RSPWrite 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_handleThe connection handle identifying the connection to perform this procedure on.
[in]p_write_paramsA pointer to a write parameters structure.
Return values
NRF_SUCCESSSuccessfully started the Write procedure.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied.
NRF_ERROR_DATA_SIZEInvalid data size(s) supplied.
NRF_ERROR_BUSYFor write with response, procedure already in progress. Wait for a BLE_GATTC_EVT_WRITE_RSP event and retry.
NRF_ERROR_RESOURCESToo many writes without responses queued. Wait for a BLE_GATTC_EVT_WRITE_CMD_TX_COMPLETE event and retry.
NRF_ERROR_TIMEOUTThere has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.

Documentation feedback | Developer Zone | Subscribe | Updated