Tizen Native API
Bluetooth GATT

Bluetooth GATT (Generic Attribute Profile) API provides common functions for GATT client and GATT server.

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 both Server role and 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_foreach_primary_services (const char *remote_address, bt_gatt_primary_service_cb callback, void *user_data)
 Gets the primary services of GATT(Generic Attribute Profile).
int bt_gatt_discover_characteristics (bt_gatt_attribute_h service, bt_gatt_characteristics_discovered_cb callback, void *user_data)
 Discovers the characteristics in service, asynchronously.
int bt_gatt_get_service_uuid (bt_gatt_attribute_h service, char **uuid)
 Gets the UUID of service.
int bt_gatt_foreach_included_services (bt_gatt_attribute_h service, bt_gatt_included_service_cb callback, void *user_data)
 Gets the included services in service.
int bt_gatt_set_characteristic_changed_cb (bt_gatt_characteristic_changed_cb callback, void *user_data)
 Registers a callback function that will be invoked when a characteristic value is changed.
int bt_gatt_unset_characteristic_changed_cb (void)
 Unregisters a callback function that will be invoked when a characteristic is changed.
int bt_gatt_watch_characteristic_changes (bt_gatt_attribute_h service)
 Watches all the characteristic value changes of the service.
int bt_gatt_unwatch_characteristic_changes (bt_gatt_attribute_h service)
 Remove watching of all the characteristic value changes of the service.
int bt_gatt_get_characteristic_declaration (bt_gatt_attribute_h characteristic, char **uuid, unsigned char **value, int *value_length)
 Gets the characteristic declaration.
int bt_gatt_set_characteristic_value (bt_gatt_attribute_h characteristic, const unsigned char *value, int value_length)
 Sets the value of characteristic.
int bt_gatt_set_characteristic_value_request (bt_gatt_attribute_h characteristic, const unsigned char *value, int value_length, bt_gatt_characteristic_write_cb callback)
 Sets the value of characteristic request.
int bt_gatt_clone_attribute_handle (bt_gatt_attribute_h *clone, bt_gatt_attribute_h origin)
 Clones the attribute handle.
int bt_gatt_destroy_attribute_handle (bt_gatt_attribute_h handle)
 Destroys the attribute handle.
int bt_gatt_read_characteristic_value (bt_gatt_attribute_h char_handle, bt_gatt_characteristic_read_cb callback)
 Reads the value of characteristic from remote device.
int bt_gatt_discover_characteristic_descriptor (bt_gatt_attribute_h characteristic_handle, bt_gatt_characteristic_descriptor_discovered_cb callback, void *user_data)
 Discovers the characteristic descriptors of a characteristic within its definition, asynchronously.
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_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_characteristic_get_permissions (bt_gatt_h gatt_handle, int *permissions)
 Gets the permissions which a characteristic's GATT handle has.
int bt_gatt_descriptor_get_permissions (bt_gatt_h gatt_handle, int *permissions)
 Gets the permissions which a descriptor's GATT handle has.
int bt_gatt_characteristic_create (const char *uuid, int permissions, int properties, const char *value, int value_length, bt_gatt_h *characteristic)
 Creates the GATT characteristic.
int bt_gatt_descriptor_create (const char *uuid, int permissions, const char *value, int value_length, bt_gatt_h *descriptor)
 Creates the GATT characteristic descriptor.

Typedefs

typedef void * bt_gatt_attribute_h
 The attribute handle of GATT(Generic Attribute Profile).
typedef bool(* bt_gatt_primary_service_cb )(bt_gatt_attribute_h service, void *user_data)
 Called when you get the primary services repeatedly.
typedef bool(* bt_gatt_characteristics_discovered_cb )(int result, int index, int total, bt_gatt_attribute_h characteristic, void *user_data)
 Called after the characteristics are discovered by bt_gatt_discover_characteristics().
typedef bool(* bt_gatt_included_service_cb )(bt_gatt_attribute_h service, void *user_data)
 Called when you get the included services repeatedly.
typedef void(* bt_gatt_characteristic_changed_cb )(bt_gatt_attribute_h characteristic, unsigned char *value, int value_length, void *user_data)
 Called when a characteristic in service is changed.
typedef void(* bt_gatt_characteristic_write_cb )(void *user_data)
 Called when a characteristic value is written.
typedef void(* bt_gatt_characteristic_read_cb )(unsigned char *value, int value_length, void *user_data)
 Called when a characteristic value is read.
typedef void(* bt_gatt_characteristic_descriptor_discovered_cb )(int result, unsigned char characteristic_format, int total, bt_gatt_attribute_h characteristic_descriptor, void *user_data)
 Called after the characteristics descriptors are discovered by bt_gatt_discover_characteristic_descriptor().
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_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_attribute_h

The attribute handle of GATT(Generic Attribute Profile).

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_h instead.
Since :
2.3
typedef void(* bt_gatt_characteristic_changed_cb)(bt_gatt_attribute_h characteristic, unsigned char *value, int value_length, void *user_data)

Called when a characteristic in service is changed.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_client_characteristic_value_changed_cb instead.
Since :
2.3
Parameters:
[in]characteristicThe attribute handle of characteristic
[in]valueThe value of characteristic (byte array)
[in]value_lengthThe length of value
[in]user_dataThe user data passed from the callback registration function
See also:
bt_gatt_set_characteristic_changed_cb()
bt_gatt_unset_characteristic_changed_cb()
typedef void(* bt_gatt_characteristic_descriptor_discovered_cb)(int result, unsigned char characteristic_format, int total, bt_gatt_attribute_h characteristic_descriptor, void *user_data)

Called after the characteristics descriptors are discovered by bt_gatt_discover_characteristic_descriptor().

Deprecated:
Deprecated since 2.3.1. This is not required because descriptor discovery is happened automatically.
Since :
2.3
Parameters:
[in]resultThe result of discovering
[in]characteristic_formatThe format of the information data. characteristic_format = 0x01 indicates UUIDs are 16-bits characteristic_format = 0x02 indicates UUIDs are 128-bits
[in]totalThe total number of elements in characteristic_descriptor
[in]characteristicdescriptor The attribute handle and the UUID of characteristic descriptor
[in]user_dataThe user data passed from the request function
See also:
bt_gatt_discover_characteristic_descriptor()
typedef void(* bt_gatt_characteristic_read_cb)(unsigned char *value, int value_length, void *user_data)

Called when a characteristic value is read.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_client_request_completed_cb instead.
Since :
2.3
Parameters:
[in]valueThe value of characteristic (byte array)
[in]value_lengthThe length of value
[in]user_dataThe user data passed from the foreach function
See also:
bt_gatt_read_characteristic_value()
typedef void(* bt_gatt_characteristic_write_cb)(void *user_data)

Called when a characteristic value is written.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_client_request_completed_cb instead.
Since :
2.3
See also:
bt_gatt_set_characteristic_value()
typedef bool(* bt_gatt_characteristics_discovered_cb)(int result, int index, int total, bt_gatt_attribute_h characteristic, void *user_data)

Called after the characteristics are discovered by bt_gatt_discover_characteristics().

Deprecated:
Deprecated since 2.3.1. This is not required because characteristic discovery is happened automatically.
Since :
2.3
Remarks:
If bt_gatt_discover_characteristics() failed, then this callback function is called only once with 0 total and NULL characteristic_handle.
Parameters:
[in]resultThe result of discovering
[in]indexThe index of characteristics in a service, starts from 0
[in]totalThe total number of characteristics in a service
[in]characteristicThe attribute handle of characteristic
[in]user_dataThe user data passed from the request function
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop.
Precondition:
bt_gatt_discover_characteristics() will invoke this callback.
See also:
bt_gatt_discover_characteristics()
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

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()
typedef bool(* bt_gatt_included_service_cb)(bt_gatt_attribute_h service, void *user_data)

Called when you get the included services repeatedly.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_foreach_cb instead.
Since :
2.3
Parameters:
[in]serviceThe attribute handle of service
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop.
Precondition:
bt_gatt_foreach_included_services() will invoke this function.
See also:
bt_gatt_foreach_included_services()
typedef bool(* bt_gatt_primary_service_cb)(bt_gatt_attribute_h service, void *user_data)

Called when you get the primary services repeatedly.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_foreach_cb instead.
Since :
2.3
Parameters:
[in]serviceThe attribute handle of service
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop.
Precondition:
bt_gatt_foreach_primary_services() will invoke this function.
See also:
bt_gatt_foreach_primary_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 the attribute's permission.

Since :
3.0
Enumerator:
BT_GATT_PERMISSION_READ 

Readable permission

BT_GATT_PERMISSION_WRITE 

Writable permission

BT_GATT_PERMISSION_ENCRYPT_READ 

Readable permission required encryption

BT_GATT_PERMISSION_ENCRYPT_WRITE 

Writable permission required encryption

BT_GATT_PERMISSION_ENCRYPT_AUTHENTICATED_READ 

Readable permission required encryption and authentication

BT_GATT_PERMISSION_ENCRYPT_AUTHENTICATED_WRITE 

Writable permission required encryption and authentication

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_create ( const char *  uuid,
int  permissions,
int  properties,
const char *  value,
int  value_length,
bt_gatt_h characteristic 
)

Creates the GATT characteristic.

Since :
3.0
Remarks:
The permissions can be one or more values of bt_gatt_permission_e, combined with bitwise 'or'.
The properties can be one or more values of bt_gatt_property_e, combined with bitwise 'or'.
The characteristic should be destroyed by using bt_gatt_characteristic_destroy().
Parameters:
[in]uuidThe UUID of the characteristic
[in]permissionsthe permissions of the characteristic
[in]propertiesThe properties of the characteristic
[in]valueThe value(byte stream) of the characteristic
[in]value_lengthThe length of value
[out]characteristicThe GATT handle of the created characteristic
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_NOT_SUPPORTEDNot supported
See also:
bt_gatt_characteristic_destroy()
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_permissions ( bt_gatt_h  gatt_handle,
int *  permissions 
)

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

Since :
3.0
Remarks:
The permissions can be one or more values of bt_gatt_permission_e, combined with bitwise 'or'.
Parameters:
[in]gatt_handleThe handle of a characteristic
[out]permissionsThe permissions 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_characteristic_create()
bt_gatt_permission_e
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

Clones the attribute handle.

Deprecated:
Deprecated since 2.3.1. GATT handle clone is not allowed. Instead, all handles for client role must be got from GATT client handle.
Since :
2.3
Remarks:
clone must be released with bt_gatt_destroy_attribute_handle().
Parameters:
[out]cloneThe cloned attribute handle
[in]originThe origin attribute handle
Returns:
0 on success, otherwise negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OUT_OF_MEMORYOut of memory
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_gatt_destroy_attribute_handle()
int bt_gatt_descriptor_create ( const char *  uuid,
int  permissions,
const char *  value,
int  value_length,
bt_gatt_h descriptor 
)

Creates the GATT characteristic descriptor.

Since :
3.0
Remarks:
The permissions can be one or more values of bt_gatt_permission_e, combined with bitwise 'or'.
The descriptor should be destroyed by using bt_gatt_descriptor_destroy().
Parameters:
[in]uuidThe UUID of the descriptor
[in]permissionsThe permissions of the descriptor
[in]valueThe value(byte stream) associated with the descriptor
[in]value_lengthThe length of value
[out]descriptorThe GATT handle of the created characteristic descriptor
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_NOT_SUPPORTEDNot supported
See also:
bt_gatt_descriptor_destroy()
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_descriptor_get_permissions ( bt_gatt_h  gatt_handle,
int *  permissions 
)

Gets the permissions which a descriptor's GATT handle has.

Since :
3.0
Remarks:
The permissions can be one or more values of bt_gatt_permission_e, combined with bitwise 'or'.
Parameters:
[in]gatt_handleThe handle of a descriptor
[out]permissionsThe permissions which a descriptor'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_descriptor_create()
bt_gatt_permission_e

Destroys the attribute handle.

Deprecated:
Deprecated since 2.3.1. GATT handle clone and destroy are not allowed.
Since :
2.3
Parameters:
[in]handleThe attribute handle
Returns:
0 on success, otherwise negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_gatt_clone_attribute_handle()

Discovers the characteristic descriptors of a characteristic within its definition, asynchronously.

Deprecated:
Deprecated since 2.3.1. This function call is not required because descriptor discovery is happened automatically.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]characteristic_handleThe attribute handle of characteristic
[in]callbackThe result callback
[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_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of local Bluetooth must be BT_ADAPTER_ENABLED.
Postcondition:
callback will be called.
See also:
bt_gatt_characteristic_descriptor_discovered_cb()

Discovers the characteristics in service, asynchronously.

Deprecated:
Deprecated since 2.3.1. This function call is not required because characteristic discovery is happened automatically.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]serviceThe attribute handle of service
[in]callbackThe result callback
[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_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of local Bluetooth must be BT_ADAPTER_ENABLED.
Postcondition:
callback will be called.
See also:
bt_gatt_characteristics_discovered_cb()
int bt_gatt_foreach_included_services ( bt_gatt_attribute_h  service,
bt_gatt_included_service_cb  callback,
void *  user_data 
)

Gets the included services in service.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_service_foreach_included_services or bt_gatt_service_get_included_service instead.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]serviceThe attribute handle of service
[in]callbackThe callback function to invoke
[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_INITIALIZEDNot initialized
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of local Bluetooth must be BT_ADAPTER_ENABLED.
Postcondition:
callback will be called if there are included services.
See also:
bt_gatt_included_service_cb()
int bt_gatt_foreach_primary_services ( const char *  remote_address,
bt_gatt_primary_service_cb  callback,
void *  user_data 
)

Gets the primary services of GATT(Generic Attribute Profile).

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_client_foreach_services or bt_gatt_client_get_service instead.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]remote_addressThe address of the remote device
[in]callbackThe callback function to invoke
[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_INITIALIZEDNot initialized
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of local Bluetooth must be BT_ADAPTER_ENABLED.
Postcondition:
callback will be called if there are primary services.
See also:
bt_gatt_primary_service_cb()
int bt_gatt_get_characteristic_declaration ( bt_gatt_attribute_h  characteristic,
char **  uuid,
unsigned char **  value,
int *  value_length 
)

Gets the characteristic declaration.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_get_value or bt_gatt_get_uuid after bt_gatt_client_read_value instead.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Remarks:
uuid and value must be released with free() by you.
Parameters:
[in]characteristicThe attribute handle of characteristic
[out]uuidThe UUID of service
[out]valueThe value of characteristic (byte array)
[out]value_lengthThe length of value
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_OPERATION_FAILEDOperation failed
BT_ERROR_OUT_OF_MEMORYOut of memory
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of local Bluetooth must be BT_ADAPTER_ENABLED.
See also:
bt_gatt_set_characteristic_value()
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_service_uuid ( bt_gatt_attribute_h  service,
char **  uuid 
)

Gets the UUID of service.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_get_uuid instead.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Remarks:
uuid must be released with free() by you.
Parameters:
[in]serviceThe attribute handle of service
[out]uuidThe UUID of service
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_OPERATION_FAILEDOperation failed
BT_ERROR_OUT_OF_MEMORYOut of memory
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of local Bluetooth must be BT_ADAPTER_ENABLED.
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

Reads the value of characteristic from remote device.

Deprecated:
Deprecated since 2.3.1. Use gatt_client_read_value instead.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]char_handleThe attribute handle of characteristic
[in]callbackThe result callback
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_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of local Bluetooth must be BT_ADAPTER_ENABLED.
See also:
bt_gatt_get_characteristic_declaration()
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_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 a characteristic value is changed.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_client_set_characteristic_value_changed_cb instead.
Since :
2.3
Parameters:
[in]callbackThe callback function to register
[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_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
See also:
bt_gatt_unset_characteristic_changed_cb()
int bt_gatt_set_characteristic_value ( bt_gatt_attribute_h  characteristic,
const unsigned char *  value,
int  value_length 
)

Sets the value of characteristic.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_set_value and bt_gatt_client_write_value instead.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]characteristicThe attribute handle of characteristic
[in]valueThe value of characteristic (byte array)
[in]value_lengthThe length of value
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_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of local Bluetooth must be BT_ADAPTER_ENABLED.
See also:
bt_gatt_get_characteristic_declaration()
int bt_gatt_set_characteristic_value_request ( bt_gatt_attribute_h  characteristic,
const unsigned char *  value,
int  value_length,
bt_gatt_characteristic_write_cb  callback 
)

Sets the value of characteristic request.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_set_value and bt_gatt_client_write_value instead.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]characteristicThe attribute handle of characteristic
[in]valueThe value of characteristic (byte array)
[in]value_lengthThe length of value
[in]callbackThe result callback
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_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of local Bluetooth must be BT_ADAPTER_ENABLED.
See also:
bt_gatt_get_characteristic_declaration()
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 a characteristic is changed.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_client_unset_characteristic_value_changed_cb instead.
Since :
2.3
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
See also:
bt_gatt_set_characteristic_changed_cb()

Remove watching of all the characteristic value changes of the service.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_client_unset_characteristic_value_changed_cb instead.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]serviceThe attribute handle of service
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_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
See also:
bt_gatt_set_characteristic_changed_cb()

Watches all the characteristic value changes of the service.

Deprecated:
Deprecated since 2.3.1. Use bt_gatt_client_set_characteristic_value_changed_cb instead.
Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]serviceThe attribute handle of service
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_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
See also:
bt_gatt_unset_characteristic_changed_cb()