Tizen Native API
|
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_connect (const char *address, bool auto_connect) |
Connect to a specific LE based service on a remote bluetooth dievice address, asynchronously. | |
int | bt_gatt_disconnect (const char *address) |
Disconnect to LE connection with the given remote Bluetooth dievice 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 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 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. |
Bluetooth GATT(Generic Attribute Profile) API provides functions for discovering, reading and modifying attributes.
#include <bluetooth.h>
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.
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.
typedef void* bt_gatt_attribute_h |
The attribute handle of GATT(Generic Attribute Profile)
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.
[in] | characteristic | The attribute handle of characteristic |
[in] | value | The value of characteristic (byte array) |
[in] | value_length | The length of value |
[in] | user_data | The user data passed from the callback registration function |
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().
[in] | result | The result of discovering |
[in] | characteristic_format | The format of the information data. characteristic_format = 0x01 indicates UUIDs are 16-bits characteristic_format = 0x02 indicates UUIDs are 128-bits |
[in] | total | The total number of elements in characteristic_descriptor |
[in] | characteristic | descriptor The attribute handle and the UUID of characteristic descriptor |
[in] | user_data | The user data passed from the request function |
typedef void(* bt_gatt_characteristic_read_cb)(unsigned char *value, int value_length, void *user_data) |
Called when a characteristic value is read.
[in] | value | The value of characteristic (byte array) |
[in] | value_length | The length of value |
[in] | user_data | The user data passed from the foreach function |
typedef void(* bt_gatt_characteristic_write_cb)(void *user_data) |
Called when a characteristic value is written.
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().
[in] | result | The result of discovering |
[in] | index | The index of characteristics in a service, starts from 0 |
[in] | total | The total number of characteristics in a service |
[in] | characteristic | The attribute handle of characteristic |
[in] | user_data | The user data passed from the request function |
true
to continue with the next iteration of the loop, false
to break out of the loop. 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.
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.
[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. |
typedef bool(* bt_gatt_included_service_cb)(bt_gatt_attribute_h service, void *user_data) |
Called when you get the included services repeatedly.
[in] | service | The attribute handle of service |
[in] | user_data | The user data passed from the foreach function |
true
to continue with the next iteration of the loop, false
to break out of the loop. typedef bool(* bt_gatt_primary_service_cb)(bt_gatt_attribute_h service, void *user_data) |
Called when you get the primary services repeatedly.
[in] | service | The attribute handle of service |
[in] | user_data | The user data passed from the foreach function |
true
to continue with the next iteration of the loop, false
to break out of the loop. int bt_gatt_clone_attribute_handle | ( | bt_gatt_attribute_h * | clone, |
bt_gatt_attribute_h | origin | ||
) |
Clones the attribute handle.
[out] | clone | The cloned attribute handle |
[in] | origin | The origin attribute handle |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OUT_OF_MEMORY | Out of memory |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_connect | ( | const char * | address, |
bool | auto_connect | ||
) |
Connect to a specific LE based service on a remote bluetooth dievice address, asynchronously.
[in] | address | The address of the remote Bluetooth device. |
[in] | auto_connect | The flag of the auto connection. |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_INVALID_PARAMETER | Invalid paramater |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_destroy_attribute_handle | ( | bt_gatt_attribute_h | handle | ) |
Destroys the attribute handle.
[in] | handle | The attribute handle |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_disconnect | ( | const char * | address | ) |
Disconnect to LE connection with the given remote Bluetooth dievice address, asynchronously.
[in] | address | The address of the remote Bluetooth device |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_INVALID_PARAMETER | Invalid paramater |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
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.
[in] | characteristic_handle | The attribute handle of characteristic |
[in] | callback | The result callback |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
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.
[in] | service | The attribute handle of service |
[in] | callback | The result callback |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
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.
[in] | service | The attribute handle of service |
[in] | callback | The callback function to invoke |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
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).
[in] | remote_address | The address of the remote device |
[in] | callback | The callback function to invoke |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_get_characteristic_declaration | ( | bt_gatt_attribute_h | characteristic, |
char ** | uuid, | ||
unsigned char ** | value, | ||
int * | value_length | ||
) |
Gets the characteristic declaration.
[in] | characteristic | The attribute handle of characteristic |
[out] | uuid | The UUID of service |
[out] | value | The value of characteristic (byte array) |
[out] | value_length | The length of value |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_OUT_OF_MEMORY | Out of memory |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_get_service_uuid | ( | bt_gatt_attribute_h | service, |
char ** | uuid | ||
) |
Gets the UUID of service.
[in] | service | The attribute handle of service |
[out] | uuid | The UUID of service |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_OUT_OF_MEMORY | Out of memory |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
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.
[in] | char_handle | The attribute handle of characteristic |
[in] | callback | The result callback |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
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.
[in] | callback | The callback function to register |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_set_characteristic_value | ( | bt_gatt_attribute_h | characteristic, |
const unsigned char * | value, | ||
int | value_length | ||
) |
Sets the value of characteristic.
[in] | characteristic | The attribute handle of characteristic |
[in] | value | The value of characteristic (byte array) |
[in] | value_length | The length of value |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
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.
[in] | characteristic | The attribute handle of characteristic |
[in] | value | The value of characteristic (byte array) |
[in] | value_length | The length of value |
[in] | callback | The result callback |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
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.
[in] | callback | The callback function to register. |
[in] | user_data | The user data to be passed to the callback function. |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid paramater |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_unset_characteristic_changed_cb | ( | void | ) |
Unregisters a callback function that will be invoked when a characteristic is changed.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
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.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_unwatch_characteristic_changes | ( | bt_gatt_attribute_h | service | ) |
Remove watching of all the characteristic value changes of the service.
[in] | service | The attribute handle of service |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_watch_characteristic_changes | ( | bt_gatt_attribute_h | service | ) |
Watches all the characteristic value changes of the service.
[in] | service | The attribute handle of service |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |