Bluetooth GATT (Generic Attribute Profile) Client API provides functions for discovering attributes and registering services, characteristics and descriptors of the remote device.

Required Header

#include <bluetooth.h>

Overview

Two roles are defined for devices that implement GATT. The Server is the device that accepts incoming commands and requests from a client and sends responses, indications and notifications to the client. The Client is the device that initiates commands and requests towards a server and can receive responses, indications and notifications sent by the server.

Related Features

This API supports both Client role in GATT.
This API is related with the following features:

http://tizen.org/feature/network.bluetooth.le.gatt.client

It is recommended to create your application with regard to features, to increase reliability.

You can check if a device supports the related features for this API by using System Information, and control your application's actions accordingly.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Functions
int	bt_gatt_service_get_client (bt_gatt_h service, bt_gatt_client_h *client)
	Gets the GATT client handle which the specified service belongs to.
int	bt_gatt_client_create (const char remote_address, bt_gatt_client_h client)
	Creates the GATT client handle.
int	bt_gatt_client_destroy (bt_gatt_client_h client)
	Destroys the GATT client's handle.
int	bt_gatt_client_get_remote_address (bt_gatt_client_h client, char **remote_address)
	Gets the address of remote device.
int	bt_gatt_client_read_value (bt_gatt_h gatt_handle, bt_gatt_client_request_completed_cb callback, void *user_data)
	Reads the value of a characteristic or descriptor from the remote device asynchronously.
int	bt_gatt_client_write_value (bt_gatt_h gatt_handle, bt_gatt_client_request_completed_cb callback, void *user_data)
	Writes the value of a characteristic or descriptor to the remote device asynchronously.
int	bt_gatt_client_request_att_mtu_change (bt_gatt_client_h client, unsigned int mtu)
	Requests a change of the ATT MTU value.
int	bt_gatt_client_get_att_mtu (bt_gatt_client_h client, unsigned int *mtu)
	Gets the ATT MTU value set for a connection.
int	bt_gatt_client_set_att_mtu_changed_cb (bt_gatt_client_h client, bt_gatt_client_att_mtu_changed_cb callback, void *user_data)
	Registers a callback function to be invoked when the ATT MTU is changed.
int	bt_gatt_client_unset_att_mtu_changed_cb (bt_gatt_client_h client)
	Unregisters the callback function to be invoked when the ATT MTU is changed.
int	bt_gatt_client_set_characteristic_value_changed_cb (bt_gatt_h characteristic, bt_gatt_client_characteristic_value_changed_cb callback, void *user_data)
	Registers a callback function to be invoked when the characteristic value is changed on the remote device.
int	bt_gatt_client_unset_characteristic_value_changed_cb (bt_gatt_h characteristic)
	Unregisters a callback function to be invoked when the characteristic value is changed on the remote device.
int	bt_gatt_client_get_service (bt_gatt_client_h client, const char uuid, bt_gatt_h service)
	Gets a service's GATT handle which has specific UUID.
int	bt_gatt_client_foreach_services (bt_gatt_client_h client, bt_gatt_foreach_cb callback, void *user_data)
	Invokes callback function on each service that belongs to the specified GATT client.
int	bt_gatt_client_set_service_changed_cb (bt_gatt_client_h client, bt_gatt_client_service_changed_cb callback, void *user_data)
	Registers a callback function to be invoked when service is changed from a remote device(GATT server).
int	bt_gatt_client_unset_service_changed_cb (bt_gatt_client_h client)
	Unregisters a callback function.
int	bt_gatt_connect (const char *address, bool auto_connect)
	Connects to a specific LE based service on a remote bluetooth device address, asynchronously.
int	bt_gatt_disconnect (const char *address)
	Disconnects to LE connection with the given remote Bluetooth device address, asynchronously or cancels a LE connection attempt currently in progress.
Typedefs
typedef void *	bt_gatt_client_h
	The handle of a GATT client which is associated with a remote device.
typedef void(*	bt_gatt_client_att_mtu_changed_cb )(bt_gatt_client_h client, const bt_gatt_client_att_mtu_info_s mtu_info, void user_data)
	Called when the ATT MTU value is changed.
typedef void(*	bt_gatt_client_request_completed_cb )(int result, bt_gatt_h request_handle, void *user_data)
	Called when the client request(e.g. read / write) has been completed.
typedef void(*	bt_gatt_client_characteristic_value_changed_cb )(bt_gatt_h characteristic, char value, int len, void user_data)
	Called when a value of a watched characteristic's GATT handle has been changed.
typedef void(*	bt_gatt_client_service_changed_cb )(bt_gatt_client_h client, bt_gatt_client_service_change_type_e change_type, const char service_uuid, void user_data)
	Called when a service of a remote GATT server has been changed.

Typedef Documentation

typedef void(* bt_gatt_client_att_mtu_changed_cb)(bt_gatt_client_h client, const bt_gatt_client_att_mtu_info_s *mtu_info, void *user_data)

Called when the ATT MTU value is changed.

Since :: 4.0

Remarks:: The mtu_info must not be freed by application.
mtu_info can be used only inside the callback.
If it's needed outside, make a copy.

Parameters:

[in]	client	The handle of a GATT client which is associated with a remote device
[in]	mtu_info	The MTU information
[in]	user_data	The user data passed from the callback registration function

See also:: bt_gatt_client_set_att_mtu_changed_cb()

typedef void(* bt_gatt_client_characteristic_value_changed_cb)(bt_gatt_h characteristic, char *value, int len, void *user_data)

Called when a value of a watched characteristic's GATT handle has been changed.

Since :: 2.3.1

Remarks:: After this function is returned, a changed value is automatically
applied to characteristic. Before that, characteristic has an old value.

Parameters:

[in]	characteristic	The characteristic's GATT handle of which value change is informed. It has an old value.
[in]	value	The new value
[in]	len	The length of value
[in]	user_data	The user data passed from the registering function

See also:: bt_gatt_client_set_characteristic_value_changed_cb()

typedef void* bt_gatt_client_h

The handle of a GATT client which is associated with a remote device.

Since :: 2.3.1

typedef void(* bt_gatt_client_request_completed_cb)(int result, bt_gatt_h request_handle, void *user_data)

Called when the client request(e.g. read / write) has been completed.

Since :: 2.3.1

Parameters:

[in]	result	The result of a request
[in]	request_handle	The requesting GATT handle
[in]	user_data	The user data passed from the requesting function

See also:: bt_gatt_client_read_value(); bt_gatt_client_write_value()

typedef void(* bt_gatt_client_service_changed_cb)(bt_gatt_client_h client, bt_gatt_client_service_change_type_e change_type, const char *service_uuid, void *user_data)

Called when a service of a remote GATT server has been changed.

Since :: 3.0

Parameters:

[in]	client	The handle of a GATT client which is associated with a remote device.
[in]	change_type	The changed type
[in]	service_uuid	The changed service uuid
[in]	user_data	The user data passed from the registering function

See also:: bt_gatt_client_set_characteristic_value_changed_cb()

Enumeration Type Documentation

enum bt_gatt_client_service_change_type_e

Enumerations of gatt server's service changing mode.

Since :: 3.0

Enumerator:

BT_GATT_CLIENT_SERVICE_ADDED	Service added
BT_GATT_CLIENT_SERVICE_REMOVED	Service removed

Function Documentation

int bt_gatt_client_create	(	const char *	remote_address,
		bt_gatt_client_h *	client
	)

Creates the GATT client handle.

Since :: 2.3.1

Remarks:: The GATT client handle must be freed by bt_gatt_client_destroy() after use.

Parameters:

[in]	remote_address	The address of the remote device
[out]	client	The created GATT client's handle

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OUT_OF_MEMORY	Out of memory
BT_ERROR_ALREADY_DONE	Operation is already done
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_destroy()

int bt_gatt_client_destroy ( bt_gatt_client_h client )

Destroys the GATT client's handle.

Since :: 2.3.1

Remarks:: All related service, characteristic and descriptor's GATT handles are freed also.

Parameters:

[in] client The GATT client's handle

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_create()

int bt_gatt_client_foreach_services	(	bt_gatt_client_h	client,
		bt_gatt_foreach_cb	callback,
		void *	user_data
	)

Invokes callback function on each service that belongs to the specified GATT client.

Since :: 2.3.1

Parameters:

[in]	client	The GATT client's handle
[in]	callback	The function to be invoked on each service
[in]	user_data	The user data to be passed to callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_foreach_cb()

int bt_gatt_client_get_att_mtu	(	bt_gatt_client_h	client,
		unsigned int *	mtu
	)

Gets the ATT MTU value set for a connection.

Since :: 4.0

Parameters:

[in]	client	The created GATT client's handle
[out]	mtu	The MTU value set for a connection

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOT_SUPPORTED	Not supported
BT_ERROR_REMOTE_DEVICE_NOT_CONNECTED	Remote device is not connected

int bt_gatt_client_get_remote_address	(	bt_gatt_client_h	client,
		char **	remote_address
	)

Gets the address of remote device.

Since :: 2.3.1

Parameters:

[in]	client	The created GATT client's handle
[out]	remote_address	The address of the remote device which is associated with client

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_create()

int bt_gatt_client_get_service	(	bt_gatt_client_h	client,
		const char *	uuid,
		bt_gatt_h *	service
	)

Gets a service's GATT handle which has specific UUID.

Since :: 2.3.1

Remarks:: The returned GATT handle must not be freed by application.
It will be freed when an associated client is destroyed by bt_gatt_client_destroy().
If there are multiple services which have same UUID, only the first matched one will be returned.

Parameters:

[in]	client	The GATT client's handle
[in]	uuid	The service's GATT handle which has this UUID will be returned if it exists
[out]	service	The service's GATT handle which has uuid if it exists

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NO_DATA	No data available
BT_ERROR_NOT_SUPPORTED	Not supported

int bt_gatt_client_read_value	(	bt_gatt_h	gatt_handle,
		bt_gatt_client_request_completed_cb	callback,
		void *	user_data
	)

Reads the value of a characteristic or descriptor from the remote device asynchronously.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in]	gatt_handle	The GATT handle of a characteristic or descriptor
[in]	callback	When a read request is completed, this callback function will be called
[in]	user_data	The user data to be passed to callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOW_IN_PROGRESS	Operation now in progress
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_create(); bt_gatt_client_request_completed_cb()

int bt_gatt_client_request_att_mtu_change	(	bt_gatt_client_h	client,
		unsigned int	mtu
	)

Requests a change of the ATT MTU value.

Since :: 4.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in]	client	The created GATT client's handle
[in]	mtu	The new MTU value

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_set_att_mtu_changed_cb()

int bt_gatt_client_set_att_mtu_changed_cb	(	bt_gatt_client_h	client,
		bt_gatt_client_att_mtu_changed_cb	callback,
		void *	user_data
	)

Registers a callback function to be invoked when the ATT MTU is changed.

Since :: 4.0

Parameters:

[in]	client	The created GATT client's handle
[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The Bluetooth service must be initialized with bt_initialize().

Postcondition:: bt_device_connection_state_changed_cb() will be invoked.

See also:: bt_initialize(); bt_gatt_client_request_att_mtu_change(); bt_gatt_client_unset_att_mtu_changed_cb()

int bt_gatt_client_set_characteristic_value_changed_cb	(	bt_gatt_h	characteristic,
		bt_gatt_client_characteristic_value_changed_cb	callback,
		void *	user_data
	)

Registers a callback function to be invoked when the characteristic value is changed on the remote device.

Since :: 2.3.1

Parameters:

[in]	characteristic	The characteristic's GATT handle
[in]	callback	The callback to be invoked when the value is changed and it is informed
[in]	user_data	The user data to be passed to callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_characteristic_value_changed_cb(); bt_gatt_client_unset_characteristic_value_changed_cb()

int bt_gatt_client_set_service_changed_cb	(	bt_gatt_client_h	client,
		bt_gatt_client_service_changed_cb	callback,
		void *	user_data
	)

Registers a callback function to be invoked when service is changed from a remote device(GATT server).

Since :: 3.0

Parameters:

[in]	client	The GATT client's handle
[in]	callback	The callback to be invoked
[in]	user_data	The user data to be passed to callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_unset_service_changed_cb()

int bt_gatt_client_unset_att_mtu_changed_cb ( bt_gatt_client_h client )

Unregisters the callback function to be invoked when the ATT MTU is changed.

Since :: 4.0

Parameters:

[in] client The created GATT client's handle

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The Bluetooth service must be initialized with bt_initialize().

See also:: bt_initialize(); bt_gatt_client_request_att_mtu_change(); bt_gatt_client_set_att_mtu_changed_cb()

int bt_gatt_client_unset_characteristic_value_changed_cb ( bt_gatt_h characteristic )

Unregisters a callback function to be invoked when the characteristic value is changed on the remote device.

Since :: 2.3.1

Parameters:

[in] characteristic The characteristic's GATT handle, whose value change will not be informed

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_set_characteristic_value_changed_cb()

int bt_gatt_client_unset_service_changed_cb ( bt_gatt_client_h client )

Unregisters a callback function.

Since :: 3.0

Parameters:

[in] client The GATT client's handle

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_set_service_changed_cb()

int bt_gatt_client_write_value	(	bt_gatt_h	gatt_handle,
		bt_gatt_client_request_completed_cb	callback,
		void *	user_data
	)

Writes the value of a characteristic or descriptor to the remote device asynchronously.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in]	gatt_handle	The GATT handle of a characteristic or descriptor
[in]	callback	When a write request is completed, this callback function will be called
[in]	user_data	The user data to be passed to callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOW_IN_PROGRESS	Operation now in progress
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_create(); bt_gatt_characteristic_set_write_type(); bt_gatt_set_value(); bt_gatt_set_int_value(); bt_gatt_set_float_value(); bt_gatt_client_request_completed_cb()

int bt_gatt_connect	(	const char *	address,
		bool	auto_connect
	)

Connects to a specific LE based service on a remote bluetooth device address, asynchronously.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Remarks:: A connection can be disconnected by bt_gatt_disconnect().

Parameters:

[in]	address	The address of the remote Bluetooth device.
[in]	auto_connect	The flag of the auto connection.

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The Bluetooth service must be initialized with bt_initialize().; The remote device must support le connection.

Postcondition:: This function invokes bt_gatt_connection_state_changed_cb().

See also:: bt_initialize(); bt_gatt_disconnect(); bt_gatt_set_connection_state_changed_cb(); bt_gatt_unset_connection_state_changed_cb(); bt_gatt_connection_state_changed_cb()

int bt_gatt_disconnect ( const char * address )

Disconnects to LE connection with the given remote Bluetooth device address, asynchronously or cancels a LE connection attempt currently in progress.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in] address The address of the remote Bluetooth device

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

Postcondition:: This function invokes bt_gatt_connection_state_changed_cb().

See also:: bt_initialize(); bt_gatt_connect(); bt_gatt_set_connection_state_changed_cb(); bt_gatt_unset_connection_state_changed_cb(); bt_gatt_connection_state_changed_cb()

int bt_gatt_service_get_client	(	bt_gatt_h	service,
		bt_gatt_client_h *	client
	)

Gets the GATT client handle which the specified service belongs to.

Since :: 2.3.1

Remarks:: This function doesn't allocate new memory for GATT client handle.
The returned GATT client handle is the same one which was got from bt_gatt_client_create().
So if it is destroyed by bt_gatt_client_destroy(), all related GATT handles are freed also.

Parameters:

[in]	service	The service's GATT handle
[out]	client	The GATT client handle which service belongs to

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_client_create()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation