Tizen Native API  5.5
Bluetooth GATT Client

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]clientThe handle of a GATT client which is associated with a remote device
[in]mtu_infoThe MTU information
[in]user_dataThe 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]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_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]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()

Enumeration Type Documentation

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


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_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_att_mtu ( bt_gatt_client_h  client,
unsigned int *  mtu 
)

Gets the ATT MTU value set for a connection.

Since :
4.0
Parameters:
[in]clientThe created GATT client's handle
[out]mtuThe MTU value set for a connection
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_NOT_SUPPORTEDNot supported
BT_ERROR_REMOTE_DEVICE_NOT_CONNECTEDRemote 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]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()
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]clientThe created GATT client's handle
[in]mtuThe new MTU value
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
See also:
bt_gatt_client_set_att_mtu_changed_cb()

Registers a callback function to be invoked when the ATT MTU is changed.

Since :
4.0
Parameters:
[in]clientThe created GATT client's handle
[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().
Postcondition:
bt_device_connection_state_changed_cb() will be invoked.
See also:
bt_initialize()
bt_gatt_client_request_att_mtu_change()
bt_gatt_client_unset_att_mtu_changed_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_changed_cb()

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 the callback function to be invoked when the ATT MTU is changed.

Since :
4.0
Parameters:
[in]clientThe created GATT client's handle
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_initialize()
bt_gatt_client_request_att_mtu_change()
bt_gatt_client_set_att_mtu_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_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]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
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_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()

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

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