| S132 SoftDevice v3.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Functions
Generic Attribute Profile (GATT) Client

## 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 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_RSP | Generated when information about a range of attributes has been received.

Parameters

  [in] | conn_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | p_handle_range | The range of handles to request information about.

Return values

  NRF_SUCCESS | Successfully started an attribute information discovery 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_BUSY | Client procedure already in progress.

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_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | p_uuid | Pointer to a Characteristic value UUID to read.
  [in] | p_handle_range | A pointer to the range of handles to perform this procedure on.

Return values

  NRF_SUCCESS | Successfully started or resumed the Read using Characteristic UUID 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_BUSY | Client procedure already in progress.

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_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | p_handles | A pointer to the handle(s) of the attribute(s) to be read.
  [in] | handle_count | The number of handles in p_handles.

Return values

  NRF_SUCCESS | Successfully started the Read Multiple Characteristic Values 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_BUSY | Client procedure already in progress.

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.

Note
  If any of the discovered characteristics have 128-bit UUIDs which are not present in the table provided to ble_vs_uuids_assign, a UUID structure with type BLE_UUID_TYPE_UNKNOWN will be received in the corresponding event.

Events generated

  BLE_GATTC_EVT_CHAR_DISC_RSP

Relevant Message Sequence Charts

  GATTC Characteristic Discovery

Parameters

  [in] | conn_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | p_handle_range | A pointer to the range of handles of the Service to perform this procedure on.

Return values

  NRF_SUCCESS | Successfully started or resumed the Characteristic Discovery 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_BUSY | Client procedure already in progress.

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.

Events generated

  BLE_GATTC_EVT_DESC_DISC_RSP

Relevant Message Sequence Charts

  GATTC Descriptor Discovery

Parameters

  [in] | conn_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | p_handle_range | A pointer to the range of handles of the Characteristic to perform this procedure on.

Return values

  NRF_SUCCESS | Successfully started or resumed the Descriptor Discovery 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_BUSY | Client procedure already in progress.

static 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
| ) |  |
| inline static

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

Parameters

  [in] | p_gattc_evt | Pointer 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_iter | Iterator, 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.

ble_gattc_handle_value_t iter;
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_SUCCESS | Successfully retrieved the next Handle-Value pair.
  NRF_ERROR_NOT_FOUND | No 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:

- The Client RX MTU value, and
- The Server RX MTU value from BLE_GATTC_EVT_EXCHANGE_MTU_RSP.

However, the SoftDevice never sets ATT_MTU lower than GATT_MTU_SIZE_DEFAULT.

Events generated

  BLE_GATTC_EVT_EXCHANGE_MTU_RSP
  BLE_EVT_DATA_LENGTH_CHANGED | Generated if a data length update procedure is performed after the ATT_MTU exchange.

Relevant Message Sequence Charts

  GATTC ATT_MTU Exchange

Parameters

  [in] | conn_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | client_rx_mtu | Client RX MTU size. The minimum value is GATT_MTU_SIZE_DEFAULT. The maximum value is ble_gatt_enable_params_t::att_mtu. The value must be equal to Server RX MTU size given in sd_ble_gatts_exchange_mtu_reply if an ATT_MTU exchange has already been performed in the other direction.

Return values

  NRF_SUCCESS | Successfully sent request to the server.
  BLE_ERROR_INVALID_CONN_HANDLE | Invalid connection handle.
  NRF_ERROR_INVALID_STATE | Invalid connection state or an ATT_MTU exchange was already requested once.
  NRF_ERROR_INVALID_PARAM | Invalid Client RX MTU size supplied.
  NRF_ERROR_BUSY | Client procedure already in progress.

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_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | handle | The handle of the attribute in the indication.

Return values

  NRF_SUCCESS | Successfully queued the Handle Value Confirmation for transmission.
  BLE_ERROR_INVALID_CONN_HANDLE | Invalid Connection Handle.
  NRF_ERROR_INVALID_STATE | Invalid Connection State or no Indication pending to be confirmed.
  BLE_ERROR_INVALID_ATTR_HANDLE | Invalid attribute handle.

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.

Note
  If any of the discovered services have 128-bit UUIDs which are not present in the table provided to ble_vs_uuids_assign, a UUID structure with type BLE_UUID_TYPE_UNKNOWN will be received in the corresponding event.

Events generated

  BLE_GATTC_EVT_PRIM_SRVC_DISC_RSP

Relevant Message Sequence Charts

  GATTC Primary Service Discovery

Parameters

  [in] | conn_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | start_handle | Handle to start searching from.
  [in] | p_srvc_uuid | Pointer to the service UUID to be found. If it is NULL, all primary services will be returned.

Return values

  NRF_SUCCESS | Successfully started or resumed the Primary Service Discovery procedure.
  BLE_ERROR_INVALID_CONN_HANDLE | Invalid Connection Handle.
  NRF_ERROR_INVALID_STATE | Invalid Connection State.
  NRF_ERROR_INVALID_PARAM | Invalid parameter(s) supplied.
  NRF_ERROR_BUSY | Client procedure already in progress.

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_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | handle | The handle of the attribute to be read.
  [in] | offset | Offset into the attribute value to be read.

Return values

  NRF_SUCCESS | Successfully started or resumed the Read (Long) procedure.
  BLE_ERROR_INVALID_CONN_HANDLE | Invalid Connection Handle.
  NRF_ERROR_INVALID_STATE | Invalid Connection State.
  NRF_ERROR_BUSY | Client procedure already in progress.

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.

Events generated

  BLE_GATTC_EVT_REL_DISC_RSP

Relevant Message Sequence Charts

  GATTC Relationship Discovery

Parameters

  [in] | conn_handle | The connection handle identifying the connection to perform this procedure on.
  [in] | p_handle_range | A pointer to the range of handles of the Service to perform this procedure on.

Return values

  NRF_SUCCESS | Successfully started or resumed the Relationship Discovery 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_BUSY | Client procedure already in progress.

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
  It is important to note that a write without response will consume an application buffer, and will therefore generate a BLE_EVT_TX_COMPLETE event when the packet has been transmitted. A write (with response) on the other hand will use the standard client internal buffer and thus will only generate a BLE_GATTC_EVT_WRITE_RSP event as soon as the write response has been received from the peer. Please see the documentation of sd_ble_tx_packet_count_get for more details.

Events generated

  BLE_GATTC_EVT_WRITE_RSP | Generated when using write request or queued writes.

Relevant Message Sequence Charts

  GATTC Characteristic or Descriptor Value Write
  GATTC Characteristic or Descriptor Value Long Write
  GATTC Characteristic or Descriptor Value Reliable Write
  App TX Packet Management

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 | Procedure already in progress.
  BLE_ERROR_NO_TX_PACKETS | No available application packets for this connection.