Tizen Native API  3.0
Bluetooth GATT

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:

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]characteristicThe characteristic's GATT handle of which value change is informed. It has an old value.
[in]valueThe new value
[in]lenThe length of value
[in]user_dataThe 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]resultThe result of a request
[in]request_handleThe requesting GATT handle
[in]user_dataThe 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]clientThe handle of a GATT client which is associated with a remote device.
[in]change_typeThe changed type
[in]service_uuidThe changed service uuid
[in]user_dataThe 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]resultThe result of changing the connection state.
[in]connectedThe state to be changed, true means connected state, Otherwise, false.
[in]remote_addressThe remote_address
[in]user_dataThe 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]totalThe total number of GATT handles to be called
[in]indexThe index of current GATT handle. It starts from 0.
[in]gatt_handleThe GATT handle
[in]user_dataThe 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

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

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

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

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

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

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

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]characteristicThe characteristic's GATT handle
[in]callbackThe function to be invoked on each descriptor
[in]user_dataThe user data to be passed to callback function
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]characteristicThe characteristic's GATT handle
[in]uuidThe descriptor's GATT handle which has this UUID will be returned if it exists
[out]descriptorThe descriptor's GATT handle which has uuid if it exists
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NO_DATANo data available
BT_ERROR_NOT_SUPPORTEDNot 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]characteristicThe characteristic's GATT handle
[out]propertiesThe properties which a characteristic's GATT handle has
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]characteristicThe characteristic's GATT handle
[out]serviceThe service's GATT handle which characteristic belongs to
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]characteristicThe characteristic's GATT handle
[out]write_typeThe write type of the specified characteristic
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]characteristicThe characteristic's GATT handle
[in]write_typeThe write type to be updated
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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_addressThe address of the remote device
[out]clientThe created GATT client's handle
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OUT_OF_MEMORYOut of memory
BT_ERROR_ALREADY_DONEOperation is already done
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_gatt_client_destroy()

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]clientThe GATT client's handle
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]clientThe GATT client's handle
[in]callbackThe function to be invoked on each service
[in]user_dataThe user data to be passed to callback function
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]clientThe created GATT client's handle
[out]remote_addressThe address of the remote device which is associated with client
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]clientThe GATT client's handle
[in]uuidThe service's GATT handle which has this UUID will be returned if it exists
[out]serviceThe service's GATT handle which has uuid if it exists
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NO_DATANo data available
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe GATT handle of a characteristic or descriptor
[in]callbackWhen a read request is completed, this callback function will be called
[in]user_dataThe user data to be passed to callback function
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOW_IN_PROGRESSOperation now in progress
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_gatt_client_create()
bt_gatt_client_request_completed_cb()

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

Since :
2.3.1
Parameters:
[in]characteristicThe characteristic's GATT handle
[in]callbackThe callback to be invoked when the value is changed and it is informed
[in]user_dataThe user data to be passed to callback function
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_gatt_client_characteristic_value_changed_cb()
bt_gatt_client_unset_characteristic_value_change()

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

Since :
3.0
Parameters:
[in]clientThe GATT client's handle
[in]callbackThe callback to be invoked
[in]user_dataThe user data to be passed to callback function
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_gatt_client_unset_service_changed_cb()

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

Since :
2.3.1
Parameters:
[in]characteristicThe characteristic's GATT handle, whose value change will not be informed
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_gatt_client_set_characteristic_value_changed_cb()

Unregisters a callback function.

Since :
3.0
Parameters:
[in]clientThe GATT client's handle
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe GATT handle of a characteristic or descriptor
[in]callbackWhen a write request is completed, this callback function will be called
[in]user_dataThe user data to be passed to callback function
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOW_IN_PROGRESSOperation now in progress
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot 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]addressThe address of the remote Bluetooth device
[in]auto_connectThe flag of the auto connection
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot 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]descriptorThe descriptor's GATT handle
[out]characteristicThe characteristic's GATT handle which descriptor belongs to
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]addressThe address of the remote Bluetooth device
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe handle of a characteristic or descriptor
[in]typeThe type of a saved value in gatt_handle
[in]offsetThe offset from where a value will be read from gatt_handle as an integer type
[out]valueThe float type's value of gatt_handle
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe handle of a characteristic or descriptor
[in]typeThe type of a saved value in gatt_handle
[in]offsetThe offset from where a value will be read from gatt_handle as an integer type
[out]valueThe integer type's value of gatt_handle
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe GATT handle
[out]gatt_typeThe type of gatt_handle
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe handle of a service, characteristic or descriptor
[out]uuidThe string of the UUID of gatt_handle
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe handle of a characteristic or descriptor
[out]valueThe value of gatt_handle. It is a byte stream type
[out]value_lengthThe length of value
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]serviceThe service's GATT handle
[in]callbackThe function to be invoked on each characteristic
[in]user_dataThe user data to be passed to callback function
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]serviceThe service's GATT handle
[in]callbackThe function to be invoked on each included service
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]serviceThe service's GATT handle
[in]uuidThe characteristic's GATT handle which has this UUID will be returned if it exists
[out]characteristicThe characteristic's GATT handle which has uuid if it exists
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NO_DATANo data available
BT_ERROR_NOT_SUPPORTEDNot 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]serviceThe service's GATT handle
[out]clientThe GATT client handle which service belongs to
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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]serviceThe service's GATT handle
[in]uuidThe included service's GATT handle which has this UUID will be returned if it exists
[out]included_serviceThe included service's GATT handle which has uuid if it exists
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NO_DATANo data available
BT_ERROR_NOT_SUPPORTEDNot supported

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

Since :
2.3
Parameters:
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe handle of a characteristic or descriptor
[in]typemantissa and exponent will be saved in gatt_handle as this type
[in]mantissaThe mantissa of float type's value to be updated
[in]exponentThe exponent of float type's value to be updated
[in]offsetThe 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_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe handle of a characteristic or descriptor
[in]typevalue will be saved in gatt_handle as this type
[in]valueThe integer type's value to be updated
[in]offsetThe offset from where value will be saved in gatt_handle
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot 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_handleThe handle of a characteristic or descriptor
[in]valueThe value to be updated
[in]value_lengthThe length of value
Returns:
0 on success, otherwise a negative error value
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot supported

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

Since :
2.3
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_gatt_connect()
bt_gatt_disconnect()
bt_gatt_connection_state_changed_cb()