Bluetooth GATT(Generic Attribute Profile) API provides functions for discovering, reading and modifying attributes.

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 the client and sends responses, indications and notifications to a client. The Client is the device that initiates commands and requests towards the server and can receive responses, indications and notifications sent by the server. This API supports the Client role in GATT.
Bluetooth stack architecture has been changed. Thus, GATT APIs defined in Tizen 2.3 are deprecated and new GATT client APIs are defined.

Related Features

This API is related with the following features:

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

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

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_get_value (bt_gatt_h gatt_handle, char *value, int value_length)
	Gets the value of a characteristic or descriptor's GATT handle.
int	bt_gatt_get_int_value (bt_gatt_h gatt_handle, bt_data_type_int_e type, int offset, int *value)
	Gets the value of a characteristic or descriptor's GATT handle as an integer type.
int	bt_gatt_get_float_value (bt_gatt_h gatt_handle, bt_data_type_float_e type, int offset, float *value)
	Gets the value of a characteristic or descriptor's GATT handle as a float type.
int	bt_gatt_set_value (bt_gatt_h gatt_handle, const char *value, int value_length)
	Updates the value of a characteristic or descriptor's GATT handle.
int	bt_gatt_set_int_value (bt_gatt_h gatt_handle, bt_data_type_int_e type, int value, int offset)
	Updates the value of a characteristic or descriptor's GATT handle using a integer type's value.
int	bt_gatt_set_float_value (bt_gatt_h gatt_handle, bt_data_type_float_e type, int mantissa, int exponent, int offset)
	Updates the value of a characteristic or descriptor's GATT handle using a float type's value.
int	bt_gatt_get_uuid (bt_gatt_h gatt_handle, char **uuid)
	Gets the UUID of a service, characteristic or descriptor's GATT handle.
int	bt_gatt_get_type (bt_gatt_h gatt_handle, bt_gatt_type_e *gatt_type)
	Gets the type of GATT handle.
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_service_get_characteristic (bt_gatt_h service, const char uuid, bt_gatt_h characteristic)
	Gets a characteristic's GATT handle which has specific UUID.
int	bt_gatt_service_foreach_characteristics (bt_gatt_h service, bt_gatt_foreach_cb callback, void *user_data)
	Invokes callback function on each characteristic that belongs to the specified service.
int	bt_gatt_service_get_included_service (bt_gatt_h service, const char uuid, bt_gatt_h included_service)
	Gets an included service's GATT handle which has specific UUID.
int	bt_gatt_service_foreach_included_services (bt_gatt_h service, bt_gatt_foreach_cb callback, void *user_data)
	Invokes callback function on each included service that belongs to the specified service.
int	bt_gatt_characteristic_get_service (bt_gatt_h characteristic, bt_gatt_h *service)
	Gets the service's GATT handle which the specified characteristic belongs to.
int	bt_gatt_characteristic_get_properties (bt_gatt_h characteristic, int *properties)
	Gets the properties which a characteristic's GATT handle has.
int	bt_gatt_characteristic_get_write_type (bt_gatt_h characteristic, bt_gatt_write_type_e *write_type)
	Gets the write type of the specified characteristic.
int	bt_gatt_characteristic_set_write_type (bt_gatt_h characteristic, bt_gatt_write_type_e write_type)
	Updates the write type of the specified characteristic.
int	bt_gatt_characteristic_get_descriptor (bt_gatt_h characteristic, const char uuid, bt_gatt_h descriptor)
	Gets a descriptor's GATT handle which has specific UUID.
int	bt_gatt_characteristic_foreach_descriptors (bt_gatt_h characteristic, bt_gatt_foreach_cb callback, void *user_data)
	Invokes callback function on each descriptor that belongs to the specified characteristic.
int	bt_gatt_descriptor_get_characteristic (bt_gatt_h descriptor, bt_gatt_h *characteristic)
	Gets the characteristic's GATT handle which the specified descriptor 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_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.
int	bt_gatt_set_connection_state_changed_cb (bt_gatt_connection_state_changed_cb callback, void *user_data)
	Registers a callback function that will be invoked when the connection state is changed.
int	bt_gatt_unset_connection_state_changed_cb (void)
	Unregisters a callback function that will be invoked when the connection state is changed.
Typedefs
typedef bool(*	bt_gatt_foreach_cb )(int total, int index, bt_gatt_h gatt_handle, void *user_data)
	Called when you get GATT handles repeatedly.
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 void(*	bt_gatt_connection_state_changed_cb )(int result, bool connected, const char remote_address, void user_data)
	Called when the connection state is changed.

Typedef Documentation

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_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()

typedef void(* bt_gatt_connection_state_changed_cb)(int result, bool connected, const char *remote_address, void *user_data)

Called when the connection state is changed.

Since :: 2.3.1

This callback is called when the connection state is changed. When you called bt_gatt_connect() or bt_gatt_disconnect(), this callback is also called with error result even though these functions fail.

Parameters:

[in]	result	The result of changing the connection state.
[in]	connected	The state to be changed, true means connected state, Otherwise, false.
[in]	remote_address	The remote_address
[in]	user_data	The user data passed from the callback registration function.

See also:: bt_gatt_connect(); bt_gatt_disconnect(); bt_gatt_set_connection_state_changed_cb(); bt_gatt_unset_connection_state_changed_cb()

typedef bool(* bt_gatt_foreach_cb)(int total, int index, bt_gatt_h gatt_handle, void *user_data)

Called when you get GATT handles repeatedly.

Since :: 2.3.1

Parameters:

[in]	total	The total number of GATT handles to be called
[in]	index	The index of current GATT handle. It starts from 0.
[in]	gatt_handle	The GATT handle
[in]	user_data	The user data passed from the foreach function

See also:: bt_gatt_service_foreach_characteristics(); bt_gatt_service_foreach_included_services(); bt_gatt_characteristic_foreach_descriptors(); bt_gatt_client_foreach_services()

Enumeration Type Documentation

enum bt_data_type_float_e

Enumerations of the float type for GATT handle's value.

Since :: 2.3.1

Enumerator:

BT_DATA_TYPE_FLOAT	32 bit float type
BT_DATA_TYPE_SFLOAT	16 bit float type

enum bt_data_type_int_e

Enumerations of the integer type for GATT handle's value.

Since :: 2.3.1

Enumerator:

BT_DATA_TYPE_SINT8	8 bit signed int type
BT_DATA_TYPE_SINT16	16 bit signed int type
BT_DATA_TYPE_SINT32	32 bit signed int type
BT_DATA_TYPE_UINT8	8 bit unsigned int type
BT_DATA_TYPE_UINT16	16 bit unsigned int type
BT_DATA_TYPE_UINT32	32 bit unsigned int type

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

enum bt_gatt_property_e

Enumerations of the characteristic's property.

Since :: 2.3.1

Enumerator:

BT_GATT_PROPERTY_BROADCAST	Broadcast property
BT_GATT_PROPERTY_READ	Read property
BT_GATT_PROPERTY_WRITE_WITHOUT_RESPONSE	Write without response property
BT_GATT_PROPERTY_WRITE	Write property
BT_GATT_PROPERTY_NOTIFY	Notify property
BT_GATT_PROPERTY_INDICATE	Indicate property
BT_GATT_PROPERTY_AUTHENTICATED_SIGNED_WRITES	Authenticated signed writes property
BT_GATT_PROPERTY_EXTENDED_PROPERTIES	Extended properties

enum bt_gatt_service_type_e

Enumerations of the service type.

Since :: 2.3.1

Enumerator:

BT_GATT_SERVICE_TYPE_PRIMARY	GATT primary service type
BT_GATT_SERVICE_TYPE_SECONDARY	GATT secondary service type

enum bt_gatt_type_e

Enumerations of the GATT handle's type.

Since :: 2.3.1

Enumerator:

BT_GATT_TYPE_SERVICE	GATT service type
BT_GATT_TYPE_DESCRIPTOR	GATT characteristic type

enum bt_gatt_write_type_e

Enumerations of the write type.

Since :: 2.3.1

Enumerator:

BT_GATT_WRITE_TYPE_WRITE_NO_RESPONSE	Write without response type
BT_GATT_WRITE_TYPE_WRITE	Write type

Function Documentation

int bt_gatt_characteristic_foreach_descriptors	(	bt_gatt_h	characteristic,
		bt_gatt_foreach_cb	callback,
		void *	user_data
	)

Invokes callback function on each descriptor that belongs to the specified characteristic.

Since :: 2.3.1

Parameters:

[in]	characteristic	The characteristic's GATT handle
[in]	callback	The function to be invoked on each descriptor
[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_characteristic_get_descriptor	(	bt_gatt_h	characteristic,
		const char *	uuid,
		bt_gatt_h *	descriptor
	)

Gets a descriptor'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 descriptors which have same UUID, only the first matched one will be returned.

Parameters:

[in]	characteristic	The characteristic's GATT handle
[in]	uuid	The descriptor's GATT handle which has this UUID will be returned if it exists
[out]	descriptor	The descriptor'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_characteristic_get_properties	(	bt_gatt_h	characteristic,
		int *	properties
	)

Gets the properties which a characteristic's GATT handle has.

Since :: 2.3.1

Parameters:

[in]	characteristic	The characteristic's GATT handle
[out]	properties	The properties which a characteristic's GATT handle has

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_property_e

int bt_gatt_characteristic_get_service	(	bt_gatt_h	characteristic,
		bt_gatt_h *	service
	)

Gets the service's GATT handle which the specified characteristic belongs to.

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().

Parameters:

[in]	characteristic	The characteristic's GATT handle
[out]	service	The service's GATT handle which characteristic 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

int bt_gatt_characteristic_get_write_type	(	bt_gatt_h	characteristic,
		bt_gatt_write_type_e *	write_type
	)

Gets the write type of the specified characteristic.

Since :: 2.3.1

Parameters:

[in]	characteristic	The characteristic's GATT handle
[out]	write_type	The write type of the specified characteristic

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_write_type_e

int bt_gatt_characteristic_set_write_type	(	bt_gatt_h	characteristic,
		bt_gatt_write_type_e	write_type
	)

Updates the write type of the specified characteristic.

Since :: 2.3.1

Parameters:

[in]	characteristic	The characteristic's GATT handle
[in]	write_type	The write type to be updated

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_write_value(); bt_gatt_write_type_e

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_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_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_change()

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_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

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_descriptor_get_characteristic	(	bt_gatt_h	descriptor,
		bt_gatt_h *	characteristic
	)

Gets the characteristic's GATT handle which the specified descriptor belongs to.

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().

Parameters:

[in]	descriptor	The descriptor's GATT handle
[out]	characteristic	The characteristic's GATT handle which descriptor 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

int bt_gatt_disconnect ( const char * address )

Disconnects to LE connection with the given remote Bluetooth device address, asynchronously.

Since :: 2.3

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

Precondition:: The connection must be established.

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_get_float_value	(	bt_gatt_h	gatt_handle,
		bt_data_type_float_e	type,
		int	offset,
		float *	value
	)

Gets the value of a characteristic or descriptor's GATT handle as a float type.

Since :: 2.3.1

Remarks:: This function returns a locally saved value in gatt_handle.
When gatt_handle is associated with bt_gatt_client_h, bt_gatt_client_read_value() must be used prior to this function
in order to get the remote device's current value.

Parameters:

[in]	gatt_handle	The handle of a characteristic or descriptor
[in]	type	The type of a saved value in gatt_handle
[in]	offset	The offset from where a value will be read from gatt_handle as an integer type
[out]	value	The float type's value of gatt_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

int bt_gatt_get_int_value	(	bt_gatt_h	gatt_handle,
		bt_data_type_int_e	type,
		int	offset,
		int *	value
	)

Gets the value of a characteristic or descriptor's GATT handle as an integer type.

Since :: 2.3.1

Remarks:: This function returns a locally saved value in gatt_handle.
When gatt_handle is associated with bt_gatt_client_h, bt_gatt_client_read_value() must be used prior to this function
in order to get the remote device's current value.

Parameters:

[in]	gatt_handle	The handle of a characteristic or descriptor
[in]	type	The type of a saved value in gatt_handle
[in]	offset	The offset from where a value will be read from gatt_handle as an integer type
[out]	value	The integer type's value of gatt_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

int bt_gatt_get_type	(	bt_gatt_h	gatt_handle,
		bt_gatt_type_e *	gatt_type
	)

Gets the type of GATT handle.

Since :: 2.3.1

Parameters:

[in]	gatt_handle	The GATT handle
[out]	gatt_type	The type of gatt_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

int bt_gatt_get_uuid	(	bt_gatt_h	gatt_handle,
		char **	uuid
	)

Gets the UUID of a service, characteristic or descriptor's GATT handle.

Since :: 2.3.1

Remarks:: uuid must be released using free().
16-bit UUID or 128-bit UUID is supported. (e.g. 2A19, 00002A19-0000-1000-8000-00805F9B34FB).

Parameters:

[in]	gatt_handle	The handle of a service, characteristic or descriptor
[out]	uuid	The string of the UUID of gatt_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

int bt_gatt_get_value	(	bt_gatt_h	gatt_handle,
		char **	value,
		int *	value_length
	)

Gets the value of a characteristic or descriptor's GATT handle.

Since :: 2.3.1

Remarks:: value must be released using free().
When gatt_handle is associated with bt_gatt_client_h, bt_gatt_client_read_value() must be used prior to this function
in order to get the remote device's current value.

Parameters:

[in]	gatt_handle	The handle of a characteristic or descriptor
[out]	value	The value of gatt_handle. It is a byte stream type
[out]	value_length	The length of 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_SUPPORTED	Not supported

int bt_gatt_service_foreach_characteristics	(	bt_gatt_h	service,
		bt_gatt_foreach_cb	callback,
		void *	user_data
	)

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

Since :: 2.3.1

Parameters:

[in]	service	The service's GATT handle
[in]	callback	The function to be invoked on each characteristic
[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_service_foreach_included_services	(	bt_gatt_h	service,
		bt_gatt_foreach_cb	callback,
		void *	user_data
	)

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

Since :: 2.3.1

Parameters:

[in]	service	The service's GATT handle
[in]	callback	The function to be invoked on each included service
[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_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_foreach_cb()

int bt_gatt_service_get_characteristic	(	bt_gatt_h	service,
		const char *	uuid,
		bt_gatt_h *	characteristic
	)

Gets a characteristic'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 characteristics which have same UUID, only the first matched one will be returned.

Parameters:

[in]	service	The service's GATT handle
[in]	uuid	The characteristic's GATT handle which has this UUID will be returned if it exists
[out]	characteristic	The characteristic'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_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()

int bt_gatt_service_get_included_service	(	bt_gatt_h	service,
		const char *	uuid,
		bt_gatt_h *	included_service
	)

Gets an included 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 included services which have same UUID, only the first matched one will be returned.

Parameters:

[in]	service	The service's GATT handle
[in]	uuid	The included service's GATT handle which has this UUID will be returned if it exists
[out]	included_service	The included 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_set_connection_state_changed_cb	(	bt_gatt_connection_state_changed_cb	callback,
		void *	user_data
	)

Registers a callback function that will be invoked when the connection state is changed.

Since :: 2.3

Parameters:

[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

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_connect(); bt_gatt_disconnect(); bt_gatt_unset_connection_state_changed_cb()

int bt_gatt_set_float_value	(	bt_gatt_h	gatt_handle,
		bt_data_type_float_e	type,
		int	mantissa,
		int	exponent,
		int	offset
	)

Updates the value of a characteristic or descriptor's GATT handle using a float type's value.

Since :: 2.3.1

Remarks:: This function updates a value of gatt_handle locally.
When gatt_handle is associated with bt_gatt_client_h, bt_gatt_client_write_value() can be used after this function
in order to update the remote device's value.

Parameters:

[in]	gatt_handle	The handle of a characteristic or descriptor
[in]	type	mantissa and exponent will be saved in gatt_handle as this type
[in]	mantissa	The mantissa of float type's value to be updated
[in]	exponent	The exponent of float type's value to be updated
[in]	offset	The offset from where mantissa and exponent will be saved in gatt_handle

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

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOT_SUPPORTED	Not supported

int bt_gatt_set_int_value	(	bt_gatt_h	gatt_handle,
		bt_data_type_int_e	type,
		int	value,
		int	offset
	)

Updates the value of a characteristic or descriptor's GATT handle using a integer type's value.

Since :: 2.3.1

Remarks:: This function updates a value of gatt_handle locally.
When gatt_handle is associated with bt_gatt_client_h, bt_gatt_client_write_value() can be used after this function
in order to update the remote device's value.

Parameters:

[in]	gatt_handle	The handle of a characteristic or descriptor
[in]	type	value will be saved in gatt_handle as this type
[in]	value	The integer type's value to be updated
[in]	offset	The offset from where value will be saved in gatt_handle

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

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOT_SUPPORTED	Not supported

int bt_gatt_set_value	(	bt_gatt_h	gatt_handle,
		const char *	value,
		int	value_length
	)

Updates the value of a characteristic or descriptor's GATT handle.

Since :: 2.3.1

Remarks:: This function updates a value of gatt_handle locally.
When gatt_handle is associated with bt_gatt_client_h, bt_gatt_client_write_value() can be used after this function
in order to update the remote device's value.

Parameters:

[in]	gatt_handle	The handle of a characteristic or descriptor
[in]	value	The value to be updated
[in]	value_length	The length of value

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

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOT_SUPPORTED	Not supported

int bt_gatt_unset_connection_state_changed_cb ( void )

Unregisters a callback function that will be invoked when the connection state is changed.

Since :: 2.3

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_gatt_connect(); bt_gatt_disconnect(); bt_gatt_connection_state_changed_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation