GATT client API

Functions
at_ble_status_t	at_ble_characteristic_discover_all (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle)
	Discover all Characteristics declared in a connected device. More...
at_ble_status_t	at_ble_characteristic_discover_by_uuid (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle, at_ble_uuid_t *uuid)
	Discover all Characteristics of a given UUID declared in a connected device. More...
at_ble_status_t	at_ble_characteristic_read (at_ble_handle_t conn_handle, at_ble_handle_t char_handle, uint16_t offset, uint16_t length)
	Read a characteristic given its handle. More...
at_ble_status_t	at_ble_characteristic_read_by_uuid (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle, at_ble_uuid_t *uuid)
	Read a characteristic given its UUID. More...
at_ble_status_t	at_ble_characteristic_read_multible (at_ble_handle_t conn_handle, at_ble_handle_t *char_handle_list, uint16_t *char_val_length, uint8_t char_handle_count)
	Read a list of characteristics given their handles. More...
at_ble_status_t	at_ble_characteristic_reliable_write_cancel (at_ble_handle_t conn_handle)
	Cancels a pending prepared write operation. More...
at_ble_status_t	at_ble_characteristic_reliable_write_execute (at_ble_handle_t conn_handle)
	Executes a pending prepared write operation. More...
at_ble_status_t	at_ble_characteristic_reliable_write_prepare (at_ble_handle_t conn_handle, at_ble_handle_t char_handle, uint16_t offset, uint16_t length, uint8_t *data)
	Add a new prepared write request. More...
at_ble_status_t	at_ble_characteristic_write (at_ble_handle_t conn_handle, at_ble_handle_t char_handle, uint16_t offset, uint16_t length, uint8_t *data, bool signed_write, bool with_response)
	Write a characteristic. More...
at_ble_status_t	at_ble_descriptor_discover_all (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle)
	Discover all Descriptors declared in a connected device. More...
at_ble_status_t	at_ble_exchange_mtu (at_ble_handle_t conn_handle)
	This message is used by the application to initiate the MTU exchange. More...
at_ble_status_t	at_ble_included_service_discover_all (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle)
	Discover all included services declared in a connected device. More...
at_ble_status_t	at_ble_primary_service_discover_all (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle)
	Discover all Primary services declared in a connected device. More...
at_ble_status_t	at_ble_primary_service_discover_by_uuid (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle, at_ble_uuid_t *uuid)
	Discover all Primary services of a given UUID declared in a connected device. More...

at_ble_status_t at_ble_characteristic_discover_all	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	start_handle,
		at_ble_handle_t	end_handle
	)

Discover all Characteristics declared in a connected device.

Search will go from start_handle to end_handle, whenever a characteristic is found AT_BLE_CHARACTERISTIC_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	Handle of the connection
[in]	start_handle	Start of the searched range
[in]	end_handle	End of the searched range

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_INVALID_PARAM Invalid arguments

AT_BLE_FAILURE Generic error

Search will go from start_handle to end_handle, whenever a characteristic is found AT_BLE_CHARACTERISTIC_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	handle of the connection
[in]	start_handle	start of the searched range
[in]	end_handle	end of the searched range

Returns

Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

References AT_BLE_INVALID_PARAM, GATTC_DISC_ALL_CHAR, gattc_disc_cmd_handler(), and NULL.

Referenced by anp_client_discovery_complete_handler(), csc_prf_discovery_complete_handler(), fmp_locator_discovery_complete_handler(), pas_client_discovery_complete_handler(), pxp_monitor_discovery_complete_handler(), and time_info_discovery_complete_handler().

at_ble_status_t at_ble_characteristic_discover_by_uuid	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	start_handle,
		at_ble_handle_t	end_handle,
		at_ble_uuid_t *	uuid
	)

Discover all Characteristics of a given UUID declared in a connected device.

Search will go from start_handle to end_handle, whenever a characteristic of matching UUID is found AT_BLE_CHARACTERISTIC_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	Handle of the connection
[in]	start_handle	Start of the searched range
[in]	end_handle	End of the searched range
[in]	uuid	UUID of the characteristic to be found, with LSB byte First in UUID value member

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_INVALID_PARAM Invalid arguments

AT_BLE_FAILURE Generic error

search will go from start_handle to end_handle, whenever a characteristic of matching UUID is found AT_BLE_CHARACTERISTIC_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	handle of the connection
[in]	start_handle	start of the searched range
[in]	end_handle	end of the searched range
[in]	uuid	UUID of the characteristic to be found, with LSB byte First in UUID value member

Returns

Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

References AT_BLE_INVALID_PARAM, at_ble_uuid_type2len(), GATTC_DISC_BY_UUID_CHAR, gattc_disc_cmd_handler(), at_ble_uuid_t::type, and at_ble_uuid_t::uuid.

at_ble_status_t at_ble_characteristic_read	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	char_handle,
		uint16_t	offset,
		uint16_t	length
	)

Read a characteristic given its handle.

Read value will be reported via AT_BLE_CHARACTERISTIC_READ_RESPONSE event.

Parameters

[in]	conn_handle	Handle of the connection
[in]	char_handle	Handle of the characteristic
[in]	offset	Offset at where to start reading
[in]	length	Maximum length of data to read

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_INVALID_PARAM Invalid arguments

AT_BLE_FAILURE Generic error

Read value will be reported via AT_BLE_CHARACTERISTIC_READ_RESPONSE event

Parameters

[in]	conn_handle	handle of the connection
[in]	char_handle	handle of the characteristic
[in]	offset	offset at where to start reading
[in]	length	= 0 then the response will retrieve the full length of the characteristic (read all) > 0 && < full length then the passed length will be red by == full length || > full length full length will be retrieved

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

References gattc_read_cmd_handler_simple_read().

Referenced by anp_alert_read(), lls_alert_level_read(), pas_read_alert_status_char(), pas_read_ringer_setting_char(), tis_current_time_read(), tis_dst_change_read(), tis_rtu_update_read(), and txps_power_read().

at_ble_status_t at_ble_characteristic_read_by_uuid	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	start_handle,
		at_ble_handle_t	end_handle,
		at_ble_uuid_t *	uuid
	)

Read a characteristic given its UUID.

Search will go from start_handle to end_handle, whenever a descriptor with given UUID is found its value will be read and reported via AT_BLE_CHARACTERISTIC_READ_RESPONSE event.

Parameters

[in]	conn_handle	Handle of the connection
[in]	start_handle	Start of the searched range
[in]	end_handle	End of the searched range
[in]	uuid	UUID of the read characteristic, with LSB byte First in UUID value member

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

search will go from start_handle to end_handle, whenever a descriptor with given UUID is found its value will be read and reported via AT_BLE_CHARACTERISTIC_READ_BY_UUID_RESPONSE event

Parameters

[in]	conn_handle	handle of the connection
[in]	start_handle	start of the searched range
[in]	end_handle	end of the searched range
[in]	uuid	UUID of the read characteristic, with LSB byte First in UUID value member

Returns

Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

References AT_BLE_INVALID_PARAM, at_ble_uuid_type2len(), gattc_read_cmd_handler_by_uuid(), at_ble_uuid_t::type, and at_ble_uuid_t::uuid.

at_ble_status_t at_ble_characteristic_read_multible	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t *	char_handle_list,
		uint16_t *	char_val_length,
		uint8_t	char_handle_count
	)

Read a list of characteristics given their handles.

Read values will be reported via AT_BLE_CHARACTERISTIC_READ_MULTIBLE_RESPONSE event.

Parameters

[in]	conn_handle	Handle of the connection
[in]	char_handle_list	List of characteristic handles
[in]	char_val_length	Length of characteristic handle
[in]	char_handle_count	Number of characteristic handles

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

References gattc_read_cmd_handler_multible().

at_ble_status_t at_ble_characteristic_reliable_write_cancel

(

at_ble_handle_t

conn_handle

)

Cancels a pending prepared write operation.

Cancels a pending prepared write operation.

Parameters

[in]

conn_handle

Handle of the connection

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

Cancels a pending prepared write operation.

Cancels a pending prepared reliable write operation

Parameters

[in]

conn_handle

handle of the connection

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

References gattc_execute_write_cmd_handler().

at_ble_status_t at_ble_characteristic_reliable_write_execute

(

at_ble_handle_t

conn_handle

)

Executes a pending prepared write operation.

Executes a pending prepared write operation. Write completion will be reported via AT_BLE_CHARACTERISTIC_WRITE_RESPONSE event.

Parameters

[in]

conn_handle

Handle of the connection

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

send write Execute to peer device to Execute pending prepared write operation, write completion will be reported via AT_BLE_CHARACTERISTIC_WRITE_CMD_CMP event.

Parameters

[in]

conn_handle

handle of the connection

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

References gattc_execute_write_cmd_handler().

at_ble_status_t at_ble_characteristic_reliable_write_prepare	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	char_handle,
		uint16_t	offset,
		uint16_t	length,
		uint8_t *	data
	)

Add a new prepared write request.

Adds a new request to a pending prepared write operation, or starts a new prepared write operation if none was started before.

Parameters

[in]	conn_handle	Handle of the connection
[in]	char_handle	Handle of the characteristic
[in]	offset	Offset at where to start write
[in]	length	Length of data to write
[in]	data	A buffer where write data is stored

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

Add a new prepared write request.

Adds a new request to a pending prepared write operation, or starts a new prepared write operation if none was started before

Parameters

[in]	conn_handle	handle of the connection
[in]	char_handle	handle of the characteristic
[in]	offset	offset at where to start write
[in]	length	length of data to write
[in]	data	a buffer where write data is stored

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

References GATTC_WRITE, and gattc_write_cmd_handler().

at_ble_status_t at_ble_characteristic_write	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	char_handle,
		uint16_t	offset,
		uint16_t	length,
		uint8_t *	data,
		bool	signed_write,
		bool	with_response
	)

Write a characteristic.

If with_response is True, write completion will be reported via AT_BLE_CHARACTERISTIC_WRITE_RESPONSE event.

Parameters

[in]	conn_handle	Handle of the connection
[in]	char_handle	Handle of the characteristic
[in]	offset	Offset at where to start write
[in]	length	Length of data to write
[in]	data	A buffer where write data is stored
[in]	signed_write	If true, perform a signed write
[in]	with_response	If true, perform a write with response procedure, otherwise perform write with no response procedure

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

Write a characteristic.

In case of signed write and write without response AT_BLE_CHARACTERISTIC_WRITE_CMD_CMP is triggered as soon as packet has been sent over the air. In case of write with response AT_BLE_CHARACTERISTIC_WRITE_CMD_CMP is triggered if error happened or when response is received from peer device.

Parameters

[in]	conn_handle	handle of the connection
[in]	char_handle	handle of the characteristic
[in]	offset	offset at where to start write
[in]	length	length of data to write
[in]	data	a buffer where write data is stored
[in]	signed_write	if true, perform a signed write
[in]	with_response	if true, perform a write with response procedure, otherwise perform write with no response procedure

Note

• If data length > MTU-3 then the write operation will be converted to long write instead of normal write operation, this scenario will be taken over by BLE stack firmware.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

References GATTC_WRITE, gattc_write_cmd_handler(), GATTC_WRITE_NO_RESPONSE, and GATTC_WRITE_SIGNED.

Referenced by anp_alert_noti(), anp_client_write_notification_handler(), anp_write_to_ncp(), csc_prf_write_notification_handler(), ias_alert_level_write(), lls_alert_level_write(), pas_char_set_ringer_control_point(), pas_char_write_notification(), tis_current_time_noti(), and tis_rtu_update_write().

at_ble_status_t at_ble_descriptor_discover_all	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	start_handle,
		at_ble_handle_t	end_handle
	)

Discover all Descriptors declared in a connected device.

Search will go from start_handle to end_handle, whenever a descriptor is found AT_BLE_DESCRIPTOR_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	Handle of the connection
[in]	start_handle	Start of the searched range
[in]	end_handle	End of the searched range

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_INVALID_PARAM Invalid arguments

AT_BLE_FAILURE Generic error

Search will go from start_handle to end_handle, whenever a descriptor is found AT_BLE_DESCRIPTOR_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	handle of the connection
[in]	start_handle	start of the searched range
[in]	end_handle	end of the searched range

Returns

Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

References AT_BLE_INVALID_PARAM, gattc_disc_cmd_handler(), GATTC_DISC_DESC_CHAR, and NULL.

Referenced by anp_client_discovery_complete_handler(), csc_prf_discovery_complete_handler(), pas_client_discovery_complete_handler(), and time_info_discovery_complete_handler().

at_ble_status_t at_ble_exchange_mtu

(

at_ble_handle_t

conn_handle

)

This message is used by the application to initiate the MTU exchange.

Parameters

[in]

conn_handle

Handle of the connection

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

This message is used by the application to initiate the MTU exchange.

Sends the MTU Exchange command to peer device to start exchanging the MTu maximum allowed length (Octet). if the peer device changes his MTU value according to the sender's MTU. the sender will receive the indication AT_BLE_MTU_CHANGED_INDICATION with the exchanged MTU value then receive AT_BLE_MTU_CHANGED_CMD_COMPLETE . if the peer device didn't accept the MTU value AT_BLE_MTU_CHANGED_CMD_COMPLETE will be sent.

Parameters

[in]

conn_handle

handle of the connection

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

References gattc_mtu_cmd_handler().

at_ble_status_t at_ble_included_service_discover_all	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	start_handle,
		at_ble_handle_t	end_handle
	)

Discover all included services declared in a connected device.

Search will go from start_handle to end_handle, whenever a service is found AT_BLE_INCLUDED_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	Handle of the connection
[in]	start_handle	Start of the searched range
[in]	end_handle	End of the searched range

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_INVALID_PARAM Invalid arguments

AT_BLE_FAILURE Generic error

Search will go from start_handle to end_handle, whenever a service is found AT_BLE_INCLUDED_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	handle of the connection
[in]	start_handle	start of the searched range
[in]	end_handle	end of the searched range

Returns

Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

References AT_BLE_INVALID_PARAM, gattc_disc_cmd_handler(), GATTC_DISC_INCLUDED_SVC, and NULL.

at_ble_status_t at_ble_primary_service_discover_all	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	start_handle,
		at_ble_handle_t	end_handle
	)

Discover all Primary services declared in a connected device.

Search will go from start_handle to end_handle, whenever a service is found AT_BLE_PRIMARY_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	Handle of the connection
[in]	start_handle	Start of the searched range
[in]	end_handle	End of the searched range

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_INVALID_PARAM Invalid arguments

AT_BLE_FAILURE Generic error

Discover all Primary services declared in a connected device.

Discover all Primary services in a peer device from a specified start_handle to a specified end_handle, whenever a service is found AT_BLE_PRIMARY_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at the end of discover operation.

Parameters

[in]	conn_handle	handle of the connected peer
[in]	start_handle	start of the searched range
[in]	end_handle	end of the searched range

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

References AT_BLE_INVALID_PARAM, GATTC_DISC_ALL_SVC, gattc_disc_cmd_handler(), and NULL.

Referenced by alert_service_discovery(), fmp_locator_service_discover(), pxp_monitor_service_discover(), and time_info_service_discovery().

at_ble_status_t at_ble_primary_service_discover_by_uuid	(	at_ble_handle_t	conn_handle,
		at_ble_handle_t	start_handle,
		at_ble_handle_t	end_handle,
		at_ble_uuid_t *	uuid
	)

Discover all Primary services of a given UUID declared in a connected device.

Search will go from start_handle to end_handle, whenever a service of matching UUID is found AT_BLE_PRIMARY_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	Handle of the connection
[in]	start_handle	Start of the searched range
[in]	end_handle	End of the searched range
[in]	uuid	UUID of the service to be found, with LSB byte First in UUID value member

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_INVALID_PARAM Invalid arguments

AT_BLE_FAILURE Generic error

Discover all Primary services of a given UUID declared in a connected device.

Search will go from start_handle to end_handle, whenever a service of matching UUID is found AT_BLE_PRIMARY_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters

[in]	conn_handle	handle of the connected peer
[in]	start_handle	start of the searched range
[in]	end_handle	end of the searched range
[in]	uuid	UUID of the service to be found, with LSB byte First in UUID value member

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

References AT_BLE_INVALID_PARAM, at_ble_uuid_type2len(), GATTC_DISC_BY_UUID_SVC, gattc_disc_cmd_handler(), at_ble_uuid_t::type, and at_ble_uuid_t::uuid.

Referenced by anp_client_connected_state_handler(), csc_prf_connected_state_handler(), and pas_client_start_service_discovery().