Functions
Functions
BLE » Profile » Profile Server » Profile Client

Definitions and prototypes for Profile Client interface. More...

Collaboration diagram for Functions:

## Functions
uint16_t | ble_gattc_prf_enh_add (uint8_t *p_client_prf_id, ble_evt_handler_t evt_handler)
| Add a client profile by providing its detail information, including manager callback functions and GATT client callback functions. More...
uint16_t | ble_gattc_enh_prf_services_browse (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, const ble_uuid_t *p_srvc_uuid)
| Profile client Browse Specific Primary Service information on remote GATT server. More...
uint16_t | ble_gattc_enh_prf_primary_services_discover (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, const ble_uuid_t *p_srvc_uuid)
| Profile client Discover Primary Services on remote GATT server. More...
uint16_t | ble_gattc_enh_prf_included_services_discover (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, uint16_t start_hdl, uint16_t end_hdl)
| Profile client Discover Included Services on remote GATT server. More...
uint16_t | ble_gattc_enh_prf_char_discover (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, ble_gattc_disc_char_t *p_disc_char)
| Profile client Discover Characteristics on remote GATT server. More...
uint16_t | ble_gattc_enh_prf_char_desc_discover (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, uint16_t start_hdl, uint16_t end_hdl)
| Profile client Discover Characteristics Descriptors on remote GATT server. More...
uint16_t | ble_gattc_enh_prf_read (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, uint16_t handle, uint16_t offset)
| Profile client Read Attribute from remote GATT server. More...
uint16_t | ble_gattc_enh_prf_read_by_uuid (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, ble_gattc_read_by_uuid_t *p_read_by_uuid)
| Profile client Read Attribute by UUID. More...
uint16_t | ble_gattc_enh_prf_read_multiple (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, const ble_gattc_read_multiple_t *p_param)
| Profile client Initiate a Read Multiple Characteristic Values procedure. More...
uint16_t | ble_gattc_enh_prf_write (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, ble_gattc_write_attr_value_t *p_write_attr_value)
| Profile client Write (Long) Characteristic (Descriptor) Value. More...
uint16_t | ble_gattc_enh_prf_write_prepare (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, ble_gattc_write_attr_value_t *p_write_attr_value)
| Profile client Prepare Long/Reliable Write to remote GATT server. More...
uint16_t | ble_gattc_enh_prf_write_execute (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, bool execute)
| Profile client Execute Reliable/Long Write to remote GATT server. More...
uint16_t | ble_gattc_enh_prf_write_no_resp (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, ble_gattc_write_no_resp_t *p_write_no_resp)
| Profile client Write Attribute to remote GATT server (without response). More...
uint16_t | ble_gattc_enh_prf_indicate_cfm (uint8_t prf_id, uint8_t conn_idx, uint16_t cid, uint16_t handle)
| Profile client Confirm Reception of Indication. More...

## Detailed Description

Definitions and prototypes for Profile Client interface.

## Function Documentation

## ◆ ble_gattc_enh_prf_char_desc_discover()

uint16_t ble_gattc_enh_prf_char_desc_discover | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | uint16_t | start_hdl,
|  | uint16_t | end_hdl
| ) |  |

Profile client Discover Characteristics Descriptors on remote GATT server.

Note
  Event BLE_GATTC_EVT_CHAR_DESC_DISC will be called for Characteristic Descriptor(s) found. If the last Descriptor has not been reached, this function must be called again with an updated handle range to continue the discovery.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | start_hdl | Start handle.
  [in] | end_hdl | End handle.

Return values

  SDK_SUCCESS | Successfully start the Descriptor Discovery procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_char_discover()

uint16_t ble_gattc_enh_prf_char_discover | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | ble_gattc_disc_char_t * | p_disc_char
| ) |  |

Profile client Discover Characteristics on remote GATT server.

Note
  Event BLE_GATTC_EVT_CHAR_DISC will be called for Characteristic Declaration(s) found. If p_disc_char is NULL, the invalid pointer error code will be returned immediately.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | p_disc_char | Pointer to discover by characteristic UUID info. If it's p_uuid member is NULL, all characteristics are returned.

Return values

  SDK_SUCCESS | Successfully start the Characteristic Discovery procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_included_services_discover()

uint16_t ble_gattc_enh_prf_included_services_discover | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | uint16_t | start_hdl,
|  | uint16_t | end_hdl
| ) |  |

Profile client Discover Included Services on remote GATT server.

Note
  Event BLE_GATTC_EVT_INCLUDE_SRVC_DISC will be called for Included Service(s) found.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | start_hdl | Start handle.
  [in] | end_hdl | End handle.

Return values

  SDK_SUCCESS | Successfully start the Relationship Discovery procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_indicate_cfm()

uint16_t ble_gattc_enh_prf_indicate_cfm | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | uint16_t | handle
| ) |  |

Profile client Confirm Reception of Indication.

Note
  Confirm indication which has been correctly received from the peer.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | handle | Value handle.

Return values

  SDK_SUCCESS | Successfully send a Confirm Reception of Indication request.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_primary_services_discover()

uint16_t ble_gattc_enh_prf_primary_services_discover | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | const ble_uuid_t * | p_srvc_uuid
| ) |  |

Profile client Discover Primary Services on remote GATT server.

Note
  Event BLE_GATTC_EVT_PRIMARY_SRVC_DISC will be called for service(s) found.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | p_srvc_uuid | Pointer to Service UUID. If it is NULL, all Primary Services will be returned.

Return values

  SDK_SUCCESS | Successfully start the Primary Service Discovery procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_read()

uint16_t ble_gattc_enh_prf_read | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | uint16_t | handle,
|  | uint16_t | offset
| ) |  |

Profile client Read Attribute from remote GATT server.

Note
  This uses either the "Read Characteristic Value" procedure or the "Read Characteristic Descriptor" procedure, depending on the attribute pointed by handle. If offset is non-zero or the attribute length is larger than the MTU, the "Read Long Characteristic Value" procedure or the "Read Long Characteristic Descriptor" procedure will be used respectively.
  Event BLE_GATTC_EVT_READ_RSP will be called when Read is finished.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | handle | Attribute handle.
  [in] | offset | Value offset to start with.

Return values

  SDK_SUCCESS | Successfully start the Read (Long) procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.
  SDK_ERR_INVALID_OFFSET | Offset exceeds the current attribute value length.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_read_by_uuid()

uint16_t ble_gattc_enh_prf_read_by_uuid | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | ble_gattc_read_by_uuid_t * | p_read_by_uuid
| ) |  |

Profile client Read Attribute by UUID.

Note
  Event BLE_GATTC_EVT_READ_RSP will be called when Read is finished.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | p_read_by_uuid | Pointer to Read by Characteristic UUID info.

Return values

  SDK_SUCCESS | Successfully start the Read Using Characteristic UUID procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_read_multiple()

uint16_t ble_gattc_enh_prf_read_multiple | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | const ble_gattc_read_multiple_t * | p_param
| ) |  |

Profile client Initiate a Read Multiple Characteristic Values procedure.

Note
  Event BLE_GATTC_EVT_READ_RSP will be called for each handle value which is read. If set handle len 0, a Read Multiple Variable Length Characteristic Values procedure will be Initiated, this procesure is only support on version >= 5.2.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | p_param | Pointer to the parameters of the value.

Note
  Event BLE_GATTC_EVT_READ_RSP will be called when Read is finished. If set handle len 0, a Read Multiple Variable Length Characteristic Values procedure will be Initiated.

Return values

  SDK_SUCCESS | Successfully start the Read Multiple Characteristic Values procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_services_browse()

uint16_t ble_gattc_enh_prf_services_browse | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | const ble_uuid_t * | p_srvc_uuid
| ) |  |

Profile client Browse Specific Primary Service information on remote GATT server.

Note
  This discovery automatically searches for Primary Services, Included Services, Characteristics and Descriptors of each service. To discover one or more services only, use ble_gattc_primary_services_discover() instead. This discovery is able to search a specific Primary Service. If srvc_uuid is NULL, all services are returned.
  Event BLE_GATTC_EVT_SRVC_BROWSE will be called for all attributes of each service found. After completed service handle range registeration for receiving peer device indication/notification will be executed internally. Because secondary service can't be browsed, so handle range registeration for receiving peer device indication/notification to this client profile may be necessary. App can call function ble_gattc_prf_evt_handle_register for registeration, it depends on user app. If user don't call this function, user shall call ble_gattc_prf_evt_handle_register to register handle range for receiving peer device indication/notification in specific client profile callback.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | p_srvc_uuid | Pointer to Service UUID. If it is NULL, all services will be returned.

Return values

  SDK_SUCCESS | Successfully start the Browse Service(s) procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_write()

uint16_t ble_gattc_enh_prf_write | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | ble_gattc_write_attr_value_t * | p_write_attr_value
| ) |  |

Profile client Write (Long) Characteristic (Descriptor) Value.

Note
  This uses either the "Write Characteristic Value" procedure or the "Write Characteristic Descriptor" procedure, depending on the attribute pointed by handle. If offset is non-zero or the attribute length is larger than the MTU, the "Write Long Characteristic Value" procedure or the "Write Long Characteristic Descriptor" procedure will be used respectively.
  Once completed event BLE_GATTC_EVT_WRITE_RSP will be called.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | p_write_attr_value | Pointer to the write attribue value info.

Return values

  SDK_SUCCESS | Successfully start the Write procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.
  SDK_ERR_INVALID_OFFSET | Offset exceeds the current attribute value length.
  SDK_ERR_INVALID_DATA_LENGTH | Invalid data length supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_write_execute()

uint16_t ble_gattc_enh_prf_write_execute | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | bool | execute
| ) |  |

Profile client Execute Reliable/Long Write to remote GATT server.

Note
  Once completed event BLE_GATTC_EVT_WRITE_RSP will be called.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | execute | True if data shall be written; False if cancel all prepared writes.

Return values

  SDK_SUCCESS | Successfully send an Execute Write request.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_write_no_resp()

uint16_t ble_gattc_enh_prf_write_no_resp | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | ble_gattc_write_no_resp_t * | p_write_no_resp
| ) |  |

Profile client Write Attribute to remote GATT server (without response).

Note
  Whatever signed_write is set, Write Without Response sub-procedure is always used, because the Signed Write Without Response sub-procedure shall only be supported on the LE Fixed Channel Unenhanced ATT bearer.
  Once completed event BLE_GATTC_EVT_WRITE_RSP will be called.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | p_write_no_resp | Pointer to the write without response info.

Return values

  SDK_SUCCESS | Successfully: start the Write Without Response procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_enh_prf_write_prepare()

uint16_t ble_gattc_enh_prf_write_prepare | ( | uint8_t | prf_id,
|  | uint8_t | conn_idx,
|  | uint16_t | cid,
|  | ble_gattc_write_attr_value_t * | p_write_attr_value
| ) |  |

Profile client Prepare Long/Reliable Write to remote GATT server.

Note
  Once completed event BLE_GATTC_EVT_WRITE_RSP will be called.

Parameters

  [in] | prf_id | Profile id.
  [in] | conn_idx | Current connection index.
  [in] | cid | The local channel ID.
  [in] | p_write_attr_value | Pointer to the write attribue value info.

Return values

  SDK_SUCCESS | Successfully start the Write procedure.
  SDK_ERR_INVALID_PARAM | Invalid parameter(s) supplied.
  SDK_ERR_INVALID_CONN_IDX | Invalid connection index supplied.
  SDK_ERR_INVALID_CID | Invalid CID supplied.
  SDK_ERR_POINTER_NULL | Invalid pointer supplied.
  SDK_ERR_INVALID_HANDLE | Invalid handle supplied.
  SDK_ERR_INVALID_OFFSET | Offset exceeds the current attribute value length.
  SDK_ERR_INVALID_DATA_LENGTH | Invalid data length supplied.
  SDK_ERR_NO_RESOURCES | Not enough resources.

## ◆ ble_gattc_prf_enh_add()

uint16_t ble_gattc_prf_enh_add | ( | uint8_t * | p_client_prf_id,
|  | ble_evt_handler_t | evt_handler
| ) |  |

Add a client profile by providing its detail information, including manager callback functions and GATT client callback functions.

This API should be called in application initialization function.

Parameters

  [in] | evt_handler | Event handler, see ble_evt_handler_t.
  [out] | p_client_prf_id | Pointer to the client profile id.

Note
  If there are several profiles which need to be added, this function should be called corresponding times.

Return values

  SDK_SUCCESS | The profile info is recorded successfully, and the profile ENV will be initialized in profile initialization callback function.
  SDK_ERR_POINTER_NULL | The parameter p_client_prf_info or p_client_prf_id is NULL, or input parameters that prf_info points to are invalid.
  SDK_ERR_NO_RESOURCES | The profile number is up to the maximum number the system can support.