Functions

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

Functions
uint16_t	ble_client_prf_add (const prf_client_info_t *p_client_prf_info, uint8_t *p_client_prf_id)
	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_prf_services_browse (uint8_t prf_id, uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid)
	Profile client Browse Specific Primary Service information on remote GATT server. More...
uint16_t	ble_gattc_prf_primary_services_discover (uint8_t prf_id, uint8_t conn_idx, const ble_uuid_t *p_srvc_uuid)
	Profile client Discover Primary Services on remote GATT server. More...
uint16_t	ble_gattc_prf_included_services_discover (uint8_t prf_id, uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl)
	Profile client Discover Included Services on remote GATT server. More...
uint16_t	ble_gattc_prf_char_discover (uint8_t prf_id, uint8_t conn_idx, gattc_disc_char_t *p_disc_char)
	Profile client Discover Characteristics on remote GATT server. More...
uint16_t	ble_gattc_prf_char_desc_discover (uint8_t prf_id, uint8_t conn_idx, uint16_t start_hdl, uint16_t end_hdl)
	Profile client Discover Characteristics Descriptors on remote GATT server. More...
uint16_t	ble_gattc_prf_read (uint8_t prf_id, uint8_t conn_idx, uint16_t handle, uint16_t offset)
	Profile client Read Attribute from remote GATT server. More...
uint16_t	ble_gattc_prf_read_by_uuid (uint8_t prf_id, uint8_t conn_idx, gattc_read_by_uuid_t *p_read_by_uuid)
	Profile client Read Attribute by UUID. More...
uint16_t	ble_gattc_prf_read_multiple (uint8_t prf_id, uint8_t conn_idx, const gattc_read_multiple_t *p_param)
	Profile client Initiate a Read Multiple Characteristic Values procedure. More...
uint16_t	ble_gattc_prf_write (uint8_t prf_id, uint8_t conn_idx, gattc_write_attr_value_t *p_write_attr_value)
	Profile client Write (Long) Characteristic (Descriptor) Value. More...
uint16_t	ble_gattc_prf_write_prepare (uint8_t prf_id, uint8_t conn_idx, gattc_write_attr_value_t *p_write_attr_value)
	Profile client Prepare Long/Reliable Write to remote GATT server. More...
uint16_t	ble_gattc_prf_write_execute (uint8_t prf_id, uint8_t conn_idx, bool execute)
	Profile client Execute Reliable/Long Write to remote GATT server. More...
uint16_t	ble_gattc_prf_write_no_resp (uint8_t prf_id, uint8_t conn_idx, gattc_write_no_resp_t *p_write_no_resp)
	Profile client Write Attribute to remote GATT server (without response). More...
uint16_t	ble_gattc_prf_indicate_cfm (uint8_t prf_id, uint8_t conn_idx, uint16_t handle)
	Profile client Confirm Reception of Indication. More...
uint16_t	ble_gattc_prf_evt_handle_register (uint8_t prf_id, uint8_t conn_idx, gattc_prf_reg_peer_evt_t *env)
	Profile client Register Indication/Notification event. More...
uint16_t	ble_gattc_prf_evt_handle_unregister (uint8_t prf_id, uint8_t conn_idx, gattc_prf_reg_peer_evt_t *env)
	Profile client Unregister Indication/Notification event. More...

Detailed Description

Definitions and prototypes for Profile Client interface.

Function Documentation

ble_client_prf_add()

uint16_t ble_client_prf_add	(	const prf_client_info_t *	p_client_prf_info,
		uint8_t *	p_client_prf_id
	)

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]	p_client_prf_info	Pointer to the p_client_prf_info. See prf_client_info_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.

ble_gattc_prf_char_desc_discover()

uint16_t ble_gattc_prf_char_desc_discover	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		uint16_t	start_hdl,
		uint16_t	end_hdl
	)

Profile client Discover Characteristics Descriptors on remote GATT server.

Note

Function callback gattc_prf_cbs_t::app_gattc_char_desc_disc_cb 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]	start_hdl	Start handle.
[in]	end_hdl	End handle.

Return values

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

ble_gattc_prf_char_discover()

uint16_t ble_gattc_prf_char_discover	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		gattc_disc_char_t *	p_disc_char
	)

Profile client Discover Characteristics on remote GATT server.

Note

Function callback gattc_prf_cbs_t::app_gattc_char_disc_cb 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]	p_disc_char	Pointer to discover by characteristic UUID info.

Return values

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

ble_gattc_prf_evt_handle_register()

uint16_t ble_gattc_prf_evt_handle_register	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		gattc_prf_reg_peer_evt_t *	env
	)

Profile client Register Indication/Notification event.

Note

Registration to peer device events (Indication/Notification) for specific client profile. Once completed gattc_prf_cbs_t::app_gattc_prf_reg_cb with type: GATTC_EVT_UNREGISTER will be called. If user don't call ble_gattc_prf_services_browse, user shall call this function 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]	env	Pointer to the profile registeration event info.

Return values

SDK_SUCCESS	Successfully register Indication/Notification event.
SDK_ERR_INVALID_CONN_IDX	Invalid connection index supplied.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter(s) supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

ble_gattc_prf_evt_handle_unregister()

uint16_t ble_gattc_prf_evt_handle_unregister	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		gattc_prf_reg_peer_evt_t *	env
	)

Profile client Unregister Indication/Notification event.

Note

Unregistration to peer device events (Indication/Notification) for specific client profile. Once completed gattc_prf_cbs_t::app_gattc_prf_reg_cb with type: GATTC_EVT_UNREGISTER will be called.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[in]	env	Pointer to the profile registeration event info.

Return values

SDK_SUCCESS	Successfully unregister Indication/Notification event.
SDK_ERR_INVALID_CONN_IDX	Invalid connection index supplied.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter(s) supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

ble_gattc_prf_included_services_discover()

uint16_t ble_gattc_prf_included_services_discover	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		uint16_t	start_hdl,
		uint16_t	end_hdl
	)

Profile client Discover Included Services on remote GATT server.

Note

Function callback gattc_prf_cbs_t::app_gattc_inc_srvc_disc_cb will be called for Included Service(s) found.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[in]	start_hdl	Start handle.
[in]	end_hdl	End handle.

Return values

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

ble_gattc_prf_indicate_cfm()

uint16_t ble_gattc_prf_indicate_cfm	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		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]	handle	Value handle.

Return values

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

ble_gattc_prf_primary_services_discover()

uint16_t ble_gattc_prf_primary_services_discover	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		const ble_uuid_t *	p_srvc_uuid
	)

Profile client Discover Primary Services on remote GATT server.

Note

Function callback gattc_prf_cbs_t::app_gattc_srvc_disc_cb will be called for service(s) found. If p_srvc_uuid is NULL, the invalid pointer error code will be returned immediately.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[in]	p_srvc_uuid	Pointer to Service UUID.

Return values

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

ble_gattc_prf_read()

uint16_t ble_gattc_prf_read	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		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.

Function callback gattc_prf_cbs_t::app_gattc_read_cb will be called when Read is finished.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[in]	handle	Attribute handle.
[in]	offset	Value offset to start with.

Return values

SDK_SUCCESS	Successfully start the Read (Long) procedure.
SDK_ERR_INVALID_CONN_IDX	Invalid connection index supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter(s) supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

ble_gattc_prf_read_by_uuid()

uint16_t ble_gattc_prf_read_by_uuid	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		gattc_read_by_uuid_t *	p_read_by_uuid
	)

Profile client Read Attribute by UUID.

Note

Function callback gattc_prf_cbs_t::app_gattc_read_cb will be called when Read is finished.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[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_CONN_IDX	Invalid connection index supplied.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter(s) supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

ble_gattc_prf_read_multiple()

uint16_t ble_gattc_prf_read_multiple	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		const gattc_read_multiple_t *	p_param
	)

Profile client Initiate a Read Multiple Characteristic Values procedure.

Note

Function callback gattc_prf_cbs_t::app_gattc_read_cb will be called for each handle value which is read.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[in]	p_param	Pointer to the parameters of the value.

Return values

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

ble_gattc_prf_services_browse()

uint16_t ble_gattc_prf_services_browse	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		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 p_srvc_uuid is NULL, the invalid pointer error code will be returned immediately.

Function callback gattc_prf_cbs_t::app_gattc_srvc_browse_cb 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]	p_srvc_uuid	Pointer to Service UUID.

Return values

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

ble_gattc_prf_write()

uint16_t ble_gattc_prf_write	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		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 gattc_prf_cbs_t::app_gattc_write_cb will be called.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[in]	p_write_attr_value	Pointer to the write attribue value info.

Return values

SDK_SUCCESS	Successfully start the Write procedure.
SDK_ERR_INVALID_CONN_IDX	Invalid connection index supplied.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter(s) supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

ble_gattc_prf_write_execute()

uint16_t ble_gattc_prf_write_execute	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		bool	execute
	)

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

Note

Once completed gattc_prf_cbs_t::app_gattc_write_cb will be called.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[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_CONN_IDX	Invalid connection index supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter(s) supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.

ble_gattc_prf_write_no_resp()

uint16_t ble_gattc_prf_write_no_resp	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		gattc_write_no_resp_t *	p_write_no_resp
	)

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

Note

If signed_write is set to false, the "Write Without Response" procedure will be used. If signed_write is set to true, the "Signed Write Without Response" procedure will be used on a link which is not encrypted. If a link is already encrypted, "Write Without Response" procedure shall be used instead of "Signed Write Without Response".

Once completed gattc_prf_cbs_t::app_gattc_write_cb will be called.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[in]	p_write_no_resp	Pointer to the write without response info.

Return values

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

ble_gattc_prf_write_prepare()

uint16_t ble_gattc_prf_write_prepare	(	uint8_t	prf_id,
		uint8_t	conn_idx,
		gattc_write_attr_value_t *	p_write_attr_value
	)

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

Note

Once completed gattc_prf_cbs_t::app_gattc_write_cb will be called.

Parameters

[in]	prf_id	Profile id.
[in]	conn_idx	Current connection index.
[in]	p_write_attr_value	Pointer to the write attribue value info.

Return values

SDK_SUCCESS	Successfully send prepare write request.
SDK_ERR_INVALID_CONN_IDX	Invalid connection index supplied.
SDK_ERR_POINTER_NULL	Invalid pointer supplied.
SDK_ERR_INVALID_PARAM	Invalid parameter(s) supplied.
SDK_ERR_NO_RESOURCES	Not enough resources.