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

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. This API should be called in application initialization function. 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]start_hdlStart handle.
[in]end_hdlEnd handle.
Return values
SDK_SUCCESSSuccessfully start the Descriptor Discovery procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_INVALID_HANDLEInvalid handle supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]p_disc_charPointer to discover by characteristic UUID info. If it's p_uuid member is NULL, all characteristics are returned.
Return values
SDK_SUCCESSSuccessfully start the Characteristic Discovery procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_POINTER_NULLInvalid pointer supplied.
SDK_ERR_INVALID_HANDLEInvalid handle supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]start_hdlStart handle.
[in]end_hdlEnd handle.
Return values
SDK_SUCCESSSuccessfully start the Relationship Discovery procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_INVALID_HANDLEInvalid handle supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]handleValue handle.
Return values
SDK_SUCCESSSuccessfully send a Confirm Reception of Indication request.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_INVALID_HANDLEInvalid handle supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]p_srvc_uuidPointer to Service UUID. If it is NULL, all Primary Services will be returned.
Return values
SDK_SUCCESSSuccessfully start the Primary Service Discovery procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_POINTER_NULLInvalid pointer supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]handleAttribute handle.
[in]offsetValue offset to start with.
Return values
SDK_SUCCESSSuccessfully start the Read (Long) procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_INVALID_HANDLEInvalid handle supplied.
SDK_ERR_INVALID_OFFSETOffset exceeds the current attribute value length.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]p_read_by_uuidPointer to Read by Characteristic UUID info.
Return values
SDK_SUCCESSSuccessfully start the Read Using Characteristic UUID procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_POINTER_NULLInvalid pointer supplied.
SDK_ERR_INVALID_HANDLEInvalid handle supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]p_paramPointer 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_SUCCESSSuccessfully start the Read Multiple Characteristic Values procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_POINTER_NULLInvalid pointer supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]p_srvc_uuidPointer to Service UUID. If it is NULL, all services will be returned.
Return values
SDK_SUCCESSSuccessfully start the Browse Service(s) procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_POINTER_NULLInvalid pointer supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]p_write_attr_valuePointer to the write attribue value info.
Return values
SDK_SUCCESSSuccessfully start the Write procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_POINTER_NULLInvalid pointer supplied.
SDK_ERR_INVALID_HANDLEInvalid handle supplied.
SDK_ERR_INVALID_OFFSETOffset exceeds the current attribute value length.
SDK_ERR_INVALID_DATA_LENGTHInvalid data length supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]executeTrue if data shall be written; False if cancel all prepared writes.
Return values
SDK_SUCCESSSuccessfully send an Execute Write request.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]p_write_no_respPointer to the write without response info.
Return values
SDK_SUCCESSSuccessfully: start the Write Without Response procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_POINTER_NULLInvalid pointer supplied.
SDK_ERR_INVALID_HANDLEInvalid handle supplied.
SDK_ERR_NO_RESOURCESNot 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_idProfile id.
[in]conn_idxCurrent connection index.
[in]cidThe local channel ID.
[in]p_write_attr_valuePointer to the write attribue value info.
Return values
SDK_SUCCESSSuccessfully start the Write procedure.
SDK_ERR_INVALID_PARAMInvalid parameter(s) supplied.
SDK_ERR_INVALID_CONN_IDXInvalid connection index supplied.
SDK_ERR_INVALID_CIDInvalid CID supplied.
SDK_ERR_POINTER_NULLInvalid pointer supplied.
SDK_ERR_INVALID_HANDLEInvalid handle supplied.
SDK_ERR_INVALID_OFFSETOffset exceeds the current attribute value length.
SDK_ERR_INVALID_DATA_LENGTHInvalid data length supplied.
SDK_ERR_NO_RESOURCESNot 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_handlerEvent handler, see ble_evt_handler_t.
[out]p_client_prf_idPointer 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_SUCCESSThe profile info is recorded successfully, and the profile ENV will be initialized in profile initialization callback function.
SDK_ERR_POINTER_NULLThe 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_RESOURCESThe profile number is up to the maximum number the system can support.