Tizen Native API
5.5
|
Bluetooth GATT (Generic Attribute Profile) Client API provides functions for discovering attributes and registering services, characteristics and descriptors of the remote device.
Required Header
#include <bluetooth.h>
Overview
Two roles are defined for devices that implement GATT. The Server is the device that accepts incoming commands and requests from a client and sends responses, indications and notifications to the client. The Client is the device that initiates commands and requests towards a server and can receive responses, indications and notifications sent by the server.
Related Features
This API supports both Client role in GATT.
This API is related with the following features:
- http://tizen.org/feature/network.bluetooth.le.gatt.client
It is recommended to create your application with regard to features, to increase reliability.
You can check if a device supports the related features for this API by using System Information, and control your application's actions accordingly.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
Functions | |
int | bt_gatt_service_get_client (bt_gatt_h service, bt_gatt_client_h *client) |
Gets the GATT client handle which the specified service belongs to. | |
int | bt_gatt_client_create (const char *remote_address, bt_gatt_client_h *client) |
Creates the GATT client handle. | |
int | bt_gatt_client_destroy (bt_gatt_client_h client) |
Destroys the GATT client's handle. | |
int | bt_gatt_client_get_remote_address (bt_gatt_client_h client, char **remote_address) |
Gets the address of remote device. | |
int | bt_gatt_client_read_value (bt_gatt_h gatt_handle, bt_gatt_client_request_completed_cb callback, void *user_data) |
Reads the value of a characteristic or descriptor from the remote device asynchronously. | |
int | bt_gatt_client_write_value (bt_gatt_h gatt_handle, bt_gatt_client_request_completed_cb callback, void *user_data) |
Writes the value of a characteristic or descriptor to the remote device asynchronously. | |
int | bt_gatt_client_request_att_mtu_change (bt_gatt_client_h client, unsigned int mtu) |
Requests a change of the ATT MTU value. | |
int | bt_gatt_client_get_att_mtu (bt_gatt_client_h client, unsigned int *mtu) |
Gets the ATT MTU value set for a connection. | |
int | bt_gatt_client_set_att_mtu_changed_cb (bt_gatt_client_h client, bt_gatt_client_att_mtu_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when the ATT MTU is changed. | |
int | bt_gatt_client_unset_att_mtu_changed_cb (bt_gatt_client_h client) |
Unregisters the callback function to be invoked when the ATT MTU is changed. | |
int | bt_gatt_client_set_characteristic_value_changed_cb (bt_gatt_h characteristic, bt_gatt_client_characteristic_value_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when the characteristic value is changed on the remote device. | |
int | bt_gatt_client_unset_characteristic_value_changed_cb (bt_gatt_h characteristic) |
Unregisters a callback function to be invoked when the characteristic value is changed on the remote device. | |
int | bt_gatt_client_get_service (bt_gatt_client_h client, const char *uuid, bt_gatt_h *service) |
Gets a service's GATT handle which has specific UUID. | |
int | bt_gatt_client_foreach_services (bt_gatt_client_h client, bt_gatt_foreach_cb callback, void *user_data) |
Invokes callback function on each service that belongs to the specified GATT client. | |
int | bt_gatt_client_set_service_changed_cb (bt_gatt_client_h client, bt_gatt_client_service_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when service is changed from a remote device(GATT server). | |
int | bt_gatt_client_unset_service_changed_cb (bt_gatt_client_h client) |
Unregisters a callback function. | |
int | bt_gatt_connect (const char *address, bool auto_connect) |
Connects to a specific LE based service on a remote bluetooth device address, asynchronously. | |
int | bt_gatt_disconnect (const char *address) |
Disconnects to LE connection with the given remote Bluetooth device address, asynchronously or cancels a LE connection attempt currently in progress. | |
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_client_h |
The handle of a GATT client which is associated with a remote device. | |
typedef void(* | bt_gatt_client_att_mtu_changed_cb )(bt_gatt_client_h client, const bt_gatt_client_att_mtu_info_s *mtu_info, void *user_data) |
Called when the ATT MTU value is changed. | |
typedef void(* | bt_gatt_client_request_completed_cb )(int result, bt_gatt_h request_handle, void *user_data) |
Called when the client request(e.g. read / write) has been completed. | |
typedef void(* | bt_gatt_client_characteristic_value_changed_cb )(bt_gatt_h characteristic, char *value, int len, void *user_data) |
Called when a value of a watched characteristic's GATT handle has been changed. | |
typedef void(* | bt_gatt_client_service_changed_cb )(bt_gatt_client_h client, bt_gatt_client_service_change_type_e change_type, const char *service_uuid, void *user_data) |
Called when a service of a remote GATT server has been changed. |
Typedef Documentation
typedef void(* bt_gatt_client_att_mtu_changed_cb)(bt_gatt_client_h client, const bt_gatt_client_att_mtu_info_s *mtu_info, void *user_data) |
Called when the ATT MTU value is changed.
- Since :
- 4.0
- Remarks:
- The mtu_info must not be freed by application.
mtu_info can be used only inside the callback.
If it's needed outside, make a copy.
- Parameters:
-
[in] client The handle of a GATT client which is associated with a remote device [in] mtu_info The MTU information [in] user_data The user data passed from the callback registration function
- See also:
- bt_gatt_client_set_connection_state_changed_cb()
- bt_gatt_client_unset_connection_state_changed_cb()
typedef void(* bt_gatt_client_characteristic_value_changed_cb)(bt_gatt_h characteristic, char *value, int len, void *user_data) |
Called when a value of a watched characteristic's GATT handle has been changed.
- Since :
- 2.3.1
- Remarks:
- After this function is returned, a changed value is automatically
applied to characteristic. Before that, characteristic has an old value.
- Parameters:
-
[in] characteristic The characteristic's GATT handle of which value change is informed. It has an old value. [in] value The new value [in] len The length of value [in] user_data The user data passed from the registering function
typedef void* bt_gatt_client_h |
The handle of a GATT client which is associated with a remote device.
- Since :
- 2.3.1
typedef void(* bt_gatt_client_request_completed_cb)(int result, bt_gatt_h request_handle, void *user_data) |
Called when the client request(e.g. read / write) has been completed.
- Since :
- 2.3.1
- Parameters:
-
[in] result The result of a request [in] request_handle The requesting GATT handle [in] user_data The user data passed from the requesting function
typedef void(* bt_gatt_client_service_changed_cb)(bt_gatt_client_h client, bt_gatt_client_service_change_type_e change_type, const char *service_uuid, void *user_data) |
Called when a service of a remote GATT server has been changed.
- Since :
- 3.0
- Parameters:
-
[in] client The handle of a GATT client which is associated with a remote device. [in] change_type The changed type [in] service_uuid The changed service uuid [in] user_data The user data passed from the registering function
Enumeration Type Documentation
Function Documentation
int bt_gatt_client_create | ( | const char * | remote_address, |
bt_gatt_client_h * | client | ||
) |
Creates the GATT client handle.
- Since :
- 2.3.1
- Remarks:
- The GATT client handle must be freed by bt_gatt_client_destroy() after use.
- Parameters:
-
[in] remote_address The address of the remote device [out] client The created GATT client's handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_OUT_OF_MEMORY Out of memory BT_ERROR_ALREADY_DONE Operation is already done BT_ERROR_NOT_SUPPORTED Not supported
- See also:
- bt_gatt_client_destroy()
int bt_gatt_client_destroy | ( | bt_gatt_client_h | client | ) |
Destroys the GATT client's handle.
- Since :
- 2.3.1
- Remarks:
- All related service, characteristic and descriptor's GATT handles are freed also.
- Parameters:
-
[in] client The GATT client's handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
- See also:
- bt_gatt_client_create()
int bt_gatt_client_foreach_services | ( | bt_gatt_client_h | client, |
bt_gatt_foreach_cb | callback, | ||
void * | user_data | ||
) |
Invokes callback function on each service that belongs to the specified GATT client.
- Since :
- 2.3.1
- Parameters:
-
[in] client The GATT client's handle [in] callback The function to be invoked on each service [in] user_data The user data to be passed to callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
- See also:
- bt_gatt_foreach_cb()
int bt_gatt_client_get_att_mtu | ( | bt_gatt_client_h | client, |
unsigned int * | mtu | ||
) |
Gets the ATT MTU value set for a connection.
- Since :
- 4.0
- Parameters:
-
[in] client The created GATT client's handle [out] mtu The MTU value set for a connection
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_NOT_ENABLED Not enabled BT_ERROR_OPERATION_FAILED Operation failed BT_ERROR_NOT_SUPPORTED Not supported BT_ERROR_REMOTE_DEVICE_NOT_CONNECTED Remote device is not connected
int bt_gatt_client_get_remote_address | ( | bt_gatt_client_h | client, |
char ** | remote_address | ||
) |
Gets the address of remote device.
- Since :
- 2.3.1
- Parameters:
-
[in] client The created GATT client's handle [out] remote_address The address of the remote device which is associated with client
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
- See also:
- bt_gatt_client_create()
int bt_gatt_client_get_service | ( | bt_gatt_client_h | client, |
const char * | uuid, | ||
bt_gatt_h * | service | ||
) |
Gets a service's GATT handle which has specific UUID.
- Since :
- 2.3.1
- Remarks:
- The returned GATT handle must not be freed by application.
It will be freed when an associated client is destroyed by bt_gatt_client_destroy().
If there are multiple services which have same UUID, only the first matched one will be returned.
- Parameters:
-
[in] client The GATT client's handle [in] uuid The service's GATT handle which has this UUID will be returned if it exists [out] service The service's GATT handle which has uuid if it exists
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NO_DATA No data available BT_ERROR_NOT_SUPPORTED Not supported
int bt_gatt_client_read_value | ( | bt_gatt_h | gatt_handle, |
bt_gatt_client_request_completed_cb | callback, | ||
void * | user_data | ||
) |
Reads the value of a characteristic or descriptor from the remote device asynchronously.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Parameters:
-
[in] gatt_handle The GATT handle of a characteristic or descriptor [in] callback When a read request is completed, this callback function will be called [in] user_data The user data to be passed to callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_ENABLED Not enabled BT_ERROR_OPERATION_FAILED Operation failed BT_ERROR_NOW_IN_PROGRESS Operation now in progress BT_ERROR_PERMISSION_DENIED Permission denied BT_ERROR_NOT_SUPPORTED Not supported
int bt_gatt_client_request_att_mtu_change | ( | bt_gatt_client_h | client, |
unsigned int | mtu | ||
) |
Requests a change of the ATT MTU value.
- Since :
- 4.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Parameters:
-
[in] client The created GATT client's handle [in] mtu The new MTU value
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_NOT_ENABLED Not enabled BT_ERROR_OPERATION_FAILED Operation failed BT_ERROR_PERMISSION_DENIED Permission denied BT_ERROR_NOT_SUPPORTED Not supported
int bt_gatt_client_set_att_mtu_changed_cb | ( | bt_gatt_client_h | client, |
bt_gatt_client_att_mtu_changed_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when the ATT MTU is changed.
- Since :
- 4.0
- Parameters:
-
[in] client The created GATT client's handle [in] callback The callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The Bluetooth service must be initialized with bt_initialize().
- Postcondition:
- bt_device_connection_state_changed_cb() will be invoked.
int bt_gatt_client_set_characteristic_value_changed_cb | ( | bt_gatt_h | characteristic, |
bt_gatt_client_characteristic_value_changed_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when the characteristic value is changed on the remote device.
- Since :
- 2.3.1
- Parameters:
-
[in] characteristic The characteristic's GATT handle [in] callback The callback to be invoked when the value is changed and it is informed [in] user_data The user data to be passed to callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
int bt_gatt_client_set_service_changed_cb | ( | bt_gatt_client_h | client, |
bt_gatt_client_service_changed_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when service is changed from a remote device(GATT server).
- Since :
- 3.0
- Parameters:
-
[in] client The GATT client's handle [in] callback The callback to be invoked [in] user_data The user data to be passed to callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
int bt_gatt_client_unset_att_mtu_changed_cb | ( | bt_gatt_client_h | client | ) |
Unregisters the callback function to be invoked when the ATT MTU is changed.
- Since :
- 4.0
- Parameters:
-
[in] client The created GATT client's handle
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The Bluetooth service must be initialized with bt_initialize().
int bt_gatt_client_unset_characteristic_value_changed_cb | ( | bt_gatt_h | characteristic | ) |
Unregisters a callback function to be invoked when the characteristic value is changed on the remote device.
- Since :
- 2.3.1
- Parameters:
-
[in] characteristic The characteristic's GATT handle, whose value change will not be informed
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
int bt_gatt_client_unset_service_changed_cb | ( | bt_gatt_client_h | client | ) |
Unregisters a callback function.
- Since :
- 3.0
- Parameters:
-
[in] client The GATT client's handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
int bt_gatt_client_write_value | ( | bt_gatt_h | gatt_handle, |
bt_gatt_client_request_completed_cb | callback, | ||
void * | user_data | ||
) |
Writes the value of a characteristic or descriptor to the remote device asynchronously.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Parameters:
-
[in] gatt_handle The GATT handle of a characteristic or descriptor [in] callback When a write request is completed, this callback function will be called [in] user_data The user data to be passed to callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_ENABLED Not enabled BT_ERROR_OPERATION_FAILED Operation failed BT_ERROR_NOW_IN_PROGRESS Operation now in progress BT_ERROR_PERMISSION_DENIED Permission denied BT_ERROR_NOT_SUPPORTED Not supported
int bt_gatt_connect | ( | const char * | address, |
bool | auto_connect | ||
) |
Connects to a specific LE based service on a remote bluetooth device address, asynchronously.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Remarks:
- A connection can be disconnected by bt_gatt_disconnect().
- Parameters:
-
[in] address The address of the remote Bluetooth device. [in] auto_connect The flag of the auto connection.
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_NOT_ENABLED Not enabled BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_OPERATION_FAILED Operation failed BT_ERROR_PERMISSION_DENIED Permission denied BT_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The Bluetooth service must be initialized with bt_initialize().
- The remote device must support le connection.
- Postcondition:
- This function invokes bt_gatt_connection_state_changed_cb().
int bt_gatt_disconnect | ( | const char * | address | ) |
Disconnects to LE connection with the given remote Bluetooth device address, asynchronously or cancels a LE connection attempt currently in progress.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Parameters:
-
[in] address The address of the remote Bluetooth device
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_NOT_ENABLED Not enabled BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_OPERATION_FAILED Operation failed BT_ERROR_PERMISSION_DENIED Permission denied BT_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- This function invokes bt_gatt_connection_state_changed_cb().
int bt_gatt_service_get_client | ( | bt_gatt_h | service, |
bt_gatt_client_h * | client | ||
) |
Gets the GATT client handle which the specified service belongs to.
- Since :
- 2.3.1
- Remarks:
- This function doesn't allocate new memory for GATT client handle.
The returned GATT client handle is the same one which was got from bt_gatt_client_create().
So if it is destroyed by bt_gatt_client_destroy(), all related GATT handles are freed also.
- Parameters:
-
[in] service The service's GATT handle [out] client The GATT client handle which service belongs to
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
- See also:
- bt_gatt_client_create()
int bt_gatt_set_connection_state_changed_cb | ( | bt_gatt_connection_state_changed_cb | callback, |
void * | user_data | ||
) |
Registers a callback function that will be invoked when the connection state is changed.
- Since :
- 2.3
- Parameters:
-
[in] callback The callback function to register. [in] user_data The user data to be passed to the callback function.
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_SUPPORTED Not supported
int bt_gatt_unset_connection_state_changed_cb | ( | void | ) |
Unregisters a callback function that will be invoked when the connection state is changed.
- Since :
- 2.3
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
BT_ERROR_NONE Successful BT_ERROR_NOT_INITIALIZED Not initialized BT_ERROR_NOT_SUPPORTED Not supported