Tizen Native API
5.0
|
Bluetooth GATT (Generic Attribute Profile) Server API provides functions for modifying attributes and registering services, characteristics and descriptors.
#include <bluetooth.h>
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.
This API supports both Server role in GATT.
This API is related with the following features:
It is recommended to create an 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, 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_service_destroy (bt_gatt_h gatt_handle) |
Destroys the GATT handle of service. | |
int | bt_gatt_characteristic_destroy (bt_gatt_h gatt_handle) |
Destroys the GATT handle of characteristic. | |
int | bt_gatt_descriptor_destroy (bt_gatt_h gatt_handle) |
Destroys the GATT handle of descriptor. | |
int | bt_gatt_service_create (const char *uuid, bt_gatt_service_type_e type, bt_gatt_h *service) |
Creates the GATT service. | |
int | bt_gatt_service_add_characteristic (bt_gatt_h service, bt_gatt_h characteristic) |
Adds a characteristic to a specified service. | |
int | bt_gatt_service_add_included_service (bt_gatt_h service, bt_gatt_h included_service) |
Adds a service to a specified service as included service. | |
int | bt_gatt_service_get_server (bt_gatt_h service, bt_gatt_server_h *server) |
Gets the GATT server handle to which the specified service belongs. | |
int | bt_gatt_characteristic_add_descriptor (bt_gatt_h characteristic, bt_gatt_h descriptor) |
Adds a descriptor to a specified characteristic. | |
int | bt_gatt_server_initialize (void) |
Initializes the GATT Server. | |
int | bt_gatt_server_deinitialize (void) |
DeInitializes the GATT server. | |
int | bt_gatt_server_create (bt_gatt_server_h *server) |
Creates the GATT server's handle. | |
int | bt_gatt_server_destroy (bt_gatt_server_h server) |
Destroys the GATT server's handle. | |
int | bt_gatt_server_set_read_value_requested_cb (bt_gatt_h gatt_handle, bt_gatt_server_read_value_requested_cb callback, void *user_data) |
Registers a callback function to be invoked when a read request for a specified characteristic or descriptor is issued from a remote device(GATT client). | |
int | bt_gatt_server_set_characteristic_notification_state_change_cb (bt_gatt_h gatt_handle, bt_gatt_server_characteristic_notification_state_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when the remote device enables or disables the Notification/Indication for particular characteristics. | |
int | bt_gatt_server_set_write_value_requested_cb (bt_gatt_h gatt_handle, bt_gatt_server_write_value_requested_cb callback, void *user_data) |
Registers a callback function to be invoked when a value of a characteristic or descriptor has been changed by a remote device(GATT client)'s request. | |
int | bt_gatt_server_register_service (bt_gatt_server_h server, bt_gatt_h service) |
Registers a specified service to the specified GATT server that the local device is hosting. | |
int | bt_gatt_server_unregister_service (bt_gatt_server_h server, bt_gatt_h service) |
Unregisters a specified service from the specified GATT server that the local device is hosting. | |
int | bt_gatt_server_unregister_all_services (bt_gatt_server_h server) |
Unregisters all services from the specified GATT server that the local device is hosting. | |
int | bt_gatt_server_start (void) |
Registers the application along with the GATT services of the application it is hosting. | |
int | bt_gatt_server_send_response (int request_id, bt_gatt_att_request_type_e request_type, int offset, int resp_status, char *value, int value_length) |
Sends a response to the remote device as a result of a read/write request. | |
int | bt_gatt_server_notify_characteristic_changed_value (bt_gatt_h characteristic, bt_gatt_server_notification_sent_cb callback, const char *device_address, void *user_data) |
Notifies value change of the characteristic to the remote devices which enable a Client Characteristic Configuration Descriptor. | |
int | bt_gatt_server_get_service (bt_gatt_server_h server, const char *uuid, bt_gatt_h *service) |
Gets a service's GATT handle which has specific UUID. | |
int | bt_gatt_server_foreach_services (bt_gatt_server_h server, bt_gatt_foreach_cb callback, void *user_data) |
Invokes callback function on each service that belongs to the specified GATT server. | |
Typedefs | |
typedef void * | bt_gatt_server_h |
The handle of a GATT server. | |
typedef void(* | bt_gatt_server_write_value_requested_cb )(const char *remote_address, int request_id, bt_gatt_server_h server, bt_gatt_h gatt_handle, bool response_needed, int offset, const char *value, int len, void *user_data) |
Called when a value of a characteristic or descriptor's GATT handle has been changed. | |
typedef void(* | bt_gatt_server_read_value_requested_cb )(const char *remote_address, int request_id, bt_gatt_server_h server, bt_gatt_h gatt_handle, int offset, void *user_data) |
Called when the remote device requests to read a value on a GATT server. | |
typedef void(* | bt_gatt_server_characteristic_notification_state_changed_cb )(bool notify, bt_gatt_server_h server, bt_gatt_h gatt_handle, void *user_data) |
Called when the remote device enables or disables the Notification/Indication for particular characteristics. | |
typedef void(* | bt_hrp_sensor_characteristic_notification_state_changed_cb )(bool notify, bt_gatt_server_h server, bt_gatt_h gatt_handle, void *user_data) |
Called when the remote device enables or disables the Notification/Indication for particular characteristics for HRP. | |
typedef void(* | bt_gatt_server_notification_sent_cb )(int result, const char *remote_address, bt_gatt_server_h server, bt_gatt_h characteristic, bool completed, void *user_data) |
Called when the sending notification / indication is done. |
typedef void(* bt_gatt_server_characteristic_notification_state_changed_cb)(bool notify, bt_gatt_server_h server, bt_gatt_h gatt_handle, void *user_data) |
Called when the remote device enables or disables the Notification/Indication for particular characteristics.
By using this callback function, server can know notification state.
[in] | notify | Indicates whether the Notification/Indication is enabled or not |
[in] | server | The GATT server handle |
[in] | gatt_handle | The characteristic's GATT handle to be read |
[in] | user_data | The user data passed from the registration function |
typedef void* bt_gatt_server_h |
The handle of a GATT server.
typedef void(* bt_gatt_server_notification_sent_cb)(int result, const char *remote_address, bt_gatt_server_h server, bt_gatt_h characteristic, bool completed, void *user_data) |
Called when the sending notification / indication is done.
[in] | result | The result of a sending operation |
[in] | remote_address | The address of the remote device |
[in] | server | The GATT server handle |
[in] | characteristic | The characteristic's GATT handle |
[in] | completed | If this callback is for the last remote device which enables a CCCD, it will be true. Or it will be false. |
[in] | user_data | The user data passed from the requesting function |
typedef void(* bt_gatt_server_read_value_requested_cb)(const char *remote_address, int request_id, bt_gatt_server_h server, bt_gatt_h gatt_handle, int offset, void *user_data) |
Called when the remote device requests to read a value on a GATT server.
For finishing the request, call the function bt_gatt_server_send_response in callback.
[in] | remote_address | The address of the requesting remote device |
[in] | request_id | The identification of this request. It will be used to send a response. |
[in] | server | The GATT server handle |
[in] | gatt_handle | The characteristic or descriptor's GATT handle to be read |
[in] | offset | The requested offset from where the GATT handle's value is read |
[in] | user_data | The user data passed from the registration function |
typedef void(* bt_gatt_server_write_value_requested_cb)(const char *remote_address, int request_id, bt_gatt_server_h server, bt_gatt_h gatt_handle, bool response_needed, int offset, const char *value, int len, void *user_data) |
Called when a value of a characteristic or descriptor's GATT handle has been changed.
For finishing the request, call the function bt_gatt_server_send_response in callback.
[in] | remote_address | The address of the remote device which requests a change |
[in] | request_id | The identification of this request. It will be used to send a response. |
[in] | server | The GATT server handle |
[in] | gatt_handle | The characteristic or descriptor's GATT handle which has an old value |
[in] | response_needed | Indicates whether a response is required by the remote device - true if required, false if not |
[in] | offset | The requested offset from where the gatt_handle value will be updated |
[in] | value | The new value |
[in] | len | The length of value |
[in] | user_data | The user data passed from the registration function |
typedef void(* bt_hrp_sensor_characteristic_notification_state_changed_cb)(bool notify, bt_gatt_server_h server, bt_gatt_h gatt_handle, void *user_data) |
Called when the remote device enables or disables the Notification/Indication for particular characteristics for HRP.
By using this callback function, server can know notification state.
[in] | notify | Indicates whether the Notification/Indication is enabled or not |
[in] | server | The GATT server handle |
[in] | gatt_handle | The characteristic's GATT handle to be read |
[in] | user_data | The user data passed from the registration function |
int bt_gatt_characteristic_add_descriptor | ( | bt_gatt_h | characteristic, |
bt_gatt_h | descriptor | ||
) |
Adds a descriptor to a specified characteristic.
[in] | characteristic | The GATT handle of the characteristic |
[in] | descriptor | The descriptor's GATT handle to be added |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_characteristic_destroy | ( | bt_gatt_h | gatt_handle | ) |
Destroys the GATT handle of characteristic.
[in] | gatt_handle | The handle of characteristic |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_descriptor_destroy | ( | bt_gatt_h | gatt_handle | ) |
Destroys the GATT handle of descriptor.
[in] | gatt_handle | The handle of descriptor |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_create | ( | bt_gatt_server_h * | server | ) |
Creates the GATT server's handle.
[out] | server | The GATT server's 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_server_deinitialize | ( | void | ) |
DeInitializes the GATT server.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_destroy | ( | bt_gatt_server_h | server | ) |
Destroys the GATT server's handle.
[in] | server | The GATT server's handle |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_foreach_services | ( | bt_gatt_server_h | server, |
bt_gatt_foreach_cb | callback, | ||
void * | user_data | ||
) |
Invokes callback function on each service that belongs to the specified GATT server.
[in] | server | The GATT server's handle |
[in] | callback | The function to be invoked on each service |
[in] | user_data | The user data to be passed to callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_get_service | ( | bt_gatt_server_h | server, |
const char * | uuid, | ||
bt_gatt_h * | service | ||
) |
Gets a service's GATT handle which has specific UUID.
[in] | server | The GATT server'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 |
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_server_initialize | ( | void | ) |
Initializes the GATT Server.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_notify_characteristic_changed_value | ( | bt_gatt_h | characteristic, |
bt_gatt_server_notification_sent_cb | callback, | ||
const char * | device_address, | ||
void * | user_data | ||
) |
Notifies value change of the characteristic to the remote devices which enable a Client Characteristic Configuration Descriptor.
[in] | characteristic | The characteristic which has a changed value |
[in] | callback | The function to be invoked on each remote device when a sending operation is done |
[in] | device_address | Remote device address to send notify or indicate and if set to NULL then notify/indicate all is enabled. |
[in] | user_data | The user data to be passed to callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_register_service | ( | bt_gatt_server_h | server, |
bt_gatt_h | service | ||
) |
Registers a specified service to the specified GATT server that the local device is hosting.
[in] | server | The GATT server that local device is hosting |
[in] | service | The service, which needs to be registered in server |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_ALREADY_DONE | Operation is already done |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_send_response | ( | int | request_id, |
bt_gatt_att_request_type_e | request_type, | ||
int | offset, | ||
int | resp_status, | ||
char * | value, | ||
int | value_length | ||
) |
Sends a response to the remote device as a result of a read/write request.
[in] | request_id | The identification of a read/write request |
[in] | request_type | The request type for read/write |
[in] | offset | The offset from where a value is read |
[in] | resp_status | The application error if any occurred or BT_ERROR_NONE for successful. |
[in] | value | The value to be sent. It will be sent from offset. If it is NULL, a requested GATT handle's value will be sent from offset. |
[in] | value_length | Value Length |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_set_characteristic_notification_state_change_cb | ( | bt_gatt_h | gatt_handle, |
bt_gatt_server_characteristic_notification_state_changed_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when the remote device enables or disables the Notification/Indication for particular characteristics.
[in] | gatt_handle | The GATT handle of a characteristic |
[in] | callback | The callback to be invoked |
[in] | user_data | The user data to be passed to callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_set_read_value_requested_cb | ( | bt_gatt_h | gatt_handle, |
bt_gatt_server_read_value_requested_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when a read request for a specified characteristic or descriptor is issued from a remote device(GATT client).
[in] | gatt_handle | The GATT handle of a characteristic or descriptor |
[in] | callback | The callback to be invoked |
[in] | user_data | The user data to be passed to callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_set_write_value_requested_cb | ( | bt_gatt_h | gatt_handle, |
bt_gatt_server_write_value_requested_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when a value of a characteristic or descriptor has been changed by a remote device(GATT client)'s request.
[in] | gatt_handle | The GATT handle of a characteristic or descriptor |
[in] | callback | The callback to be invoked |
[in] | user_data | The user data to be passed to callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_start | ( | void | ) |
Registers the application along with the GATT services of the application it is hosting.
BT_ERROR_NONE | Successful |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_ALREADY_DONE | Operation is already done |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_unregister_all_services | ( | bt_gatt_server_h | server | ) |
Unregisters all services from the specified GATT server that the local device is hosting.
[in] | server | The GATT server that local device is hosting |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_server_unregister_service | ( | bt_gatt_server_h | server, |
bt_gatt_h | service | ||
) |
Unregisters a specified service from the specified GATT server that the local device is hosting.
[in] | server | The GATT server that local device is hosting |
[in] | service | The service, which needs to be unregistered from server |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_SERVICE_NOT_FOUND | Service not found |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_service_add_characteristic | ( | bt_gatt_h | service, |
bt_gatt_h | characteristic | ||
) |
Adds a characteristic to a specified service.
[in] | service | The service's GATT handle |
[in] | characteristic | The characteristic's GATT handle to be added |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_service_add_included_service | ( | bt_gatt_h | service, |
bt_gatt_h | included_service | ||
) |
Adds a service to a specified service as included service.
[in] | service | The service's GATT handle |
[in] | included_service | The service's GATT handle to be added as included service |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_service_create | ( | const char * | uuid, |
bt_gatt_service_type_e | type, | ||
bt_gatt_h * | service | ||
) |
Creates the GATT service.
[in] | uuid | The UUID of the service |
[in] | type | The type of the service |
[out] | service | The GATT handle of the created service |
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_service_destroy | ( | bt_gatt_h | gatt_handle | ) |
Destroys the GATT handle of service.
[in] | gatt_handle | The handle of service |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_gatt_service_get_server | ( | bt_gatt_h | service, |
bt_gatt_server_h * | server | ||
) |
Gets the GATT server handle to which the specified service belongs.
[in] | service | The service's GATT handle |
[out] | server | The GATT server handle to which service belongs |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |