Data Structures
struct	bt_gatt_exchange_params
	GATT Exchange MTU parameters. More...

struct	bt_gatt_discover_params
	GATT Discover Attributes parameters. More...

struct	bt_gatt_read_params
	GATT Read parameters. More...

struct	bt_gatt_write_params
	GATT Write parameters. More...

struct	bt_gatt_subscribe_params
	GATT Subscribe parameters. More...

Typedefs
typedef uint8_t(*	bt_gatt_discover_func_t) (struct bt_conn conn, const struct bt_gatt_attr attr, struct bt_gatt_discover_params *params)
	Discover attribute callback function. More...

typedef uint8_t(*	bt_gatt_read_func_t) (struct bt_conn conn, uint8_t err, struct bt_gatt_read_params params, const void *data, uint16_t length)
	Read callback function. More...

typedef void(*	bt_gatt_write_func_t) (struct bt_conn conn, uint8_t err, struct bt_gatt_write_params params)
	Write callback function. More...

typedef uint8_t(*	bt_gatt_notify_func_t) (struct bt_conn conn, struct bt_gatt_subscribe_params params, const void *data, uint16_t length)
	Notification callback function. More...

Enumerations
enum	{ BT_GATT_DISCOVER_PRIMARY , BT_GATT_DISCOVER_SECONDARY , BT_GATT_DISCOVER_INCLUDE , BT_GATT_DISCOVER_CHARACTERISTIC , BT_GATT_DISCOVER_DESCRIPTOR , BT_GATT_DISCOVER_ATTRIBUTE , BT_GATT_DISCOVER_STD_CHAR_DESC }

enum	{ BT_GATT_SUBSCRIBE_FLAG_VOLATILE , BT_GATT_SUBSCRIBE_FLAG_NO_RESUB , BT_GATT_SUBSCRIBE_FLAG_WRITE_PENDING , BT_GATT_SUBSCRIBE_NUM_FLAGS }

Functions
int	bt_gatt_exchange_mtu (struct bt_conn conn, struct bt_gatt_exchange_params params)
	Exchange MTU. More...

int	bt_gatt_discover (struct bt_conn conn, struct bt_gatt_discover_params params)
	GATT Discover function. More...

int	bt_gatt_read (struct bt_conn conn, struct bt_gatt_read_params params)
	Read Attribute Value by handle. More...

int	bt_gatt_write (struct bt_conn conn, struct bt_gatt_write_params params)
	Write Attribute Value by handle. More...

int	bt_gatt_write_without_response_cb (struct bt_conn conn, uint16_t handle, const void data, uint16_t length, bool sign, bt_gatt_complete_func_t func, void *user_data)
	Write Attribute Value by handle without response with callback. More...

static int	bt_gatt_write_without_response (struct bt_conn conn, uint16_t handle, const void data, uint16_t length, bool sign)
	Write Attribute Value by handle without response. More...

int	bt_gatt_subscribe (struct bt_conn conn, struct bt_gatt_subscribe_params params)
	Subscribe Attribute Value Notification. More...

int	bt_gatt_resubscribe (uint8_t id, const bt_addr_le_t peer, struct bt_gatt_subscribe_params params)
	Resubscribe Attribute Value Notification subscription. More...

int	bt_gatt_unsubscribe (struct bt_conn conn, struct bt_gatt_subscribe_params params)
	Unsubscribe Attribute Value Notification. More...

void	bt_gatt_cancel (struct bt_conn conn, void params)
	Cancel GATT pending request. More...

Detailed Description

Typedef Documentation

◆ bt_gatt_discover_func_t

bt_gatt_discover_func_t

#include <include/bluetooth/gatt.h>

Discover attribute callback function.

Parameters

conn	Connection object.
attr	Attribute found, or NULL if not found.
params	Discovery parameters given.

If discovery procedure has completed this callback will be called with attr set to NULL. This will not happen if procedure was stopped by returning BT_GATT_ITER_STOP.

The attribute object as well as its UUID and value objects are temporary and must be copied to in order to cache its information. Only the following fields of the attribute contains valid information:

uuid UUID representing the type of attribute.
handle Handle in the remote database.
user_data The value of the attribute. Will be NULL when discovering descriptors

To be able to read the value of the discovered attribute the user_data must be cast to an appropriate type.

bt_gatt_service_val when UUID is BT_UUID_GATT_PRIMARY or BT_UUID_GATT_SECONDARY.
bt_gatt_include when UUID is BT_UUID_GATT_INCLUDE.
bt_gatt_chrc when UUID is BT_UUID_GATT_CHRC.

Returns: BT_GATT_ITER_CONTINUE to continue discovery procedure.; BT_GATT_ITER_STOP to stop discovery procedure.

◆ bt_gatt_notify_func_t

bt_gatt_notify_func_t

#include <include/bluetooth/gatt.h>

Notification callback function.

In the case of an empty notification, the data pointer will be non-NULL while the length will be 0, which is due to the special case where a data NULL pointer means unsubscribed.

Parameters

conn	Connection object. May be NULL, indicating that the peer is being unpaired
params	Subscription parameters.
data	Attribute value data. If NULL then subscription was removed.
length	Attribute value length.

Returns: BT_GATT_ITER_CONTINUE to continue receiving value notifications. BT_GATT_ITER_STOP to unsubscribe from value notifications.

◆ bt_gatt_read_func_t

bt_gatt_read_func_t

#include <include/bluetooth/gatt.h>

Read callback function.

Parameters

conn	Connection object.
err	ATT error code.
params	Read parameters used.
data	Attribute value data. NULL means read has completed.
length	Attribute value length.

Returns: BT_GATT_ITER_CONTINUE if should continue to the next attribute.; BT_GATT_ITER_STOP to stop.

◆ bt_gatt_write_func_t

bt_gatt_write_func_t

#include <include/bluetooth/gatt.h>

Write callback function.

Parameters

conn	Connection object.
err	ATT error code.
params	Write parameters used.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

#include <include/bluetooth/gatt.h>

GATT Discover types

Enumerator
BT_GATT_DISCOVER_PRIMARY	Discover Primary Services.
BT_GATT_DISCOVER_SECONDARY	Discover Secondary Services.
BT_GATT_DISCOVER_INCLUDE	Discover Included Services.
BT_GATT_DISCOVER_CHARACTERISTIC	Discover Characteristic Values. Discover Characteristic Value and its properties.
BT_GATT_DISCOVER_DESCRIPTOR	Discover Descriptors. Discover Attributes which are not services or characteristics. @note The use of this type of discover is not recommended for discovering in ranges across multiple services/characteristics as it may incur in extra round trips.
BT_GATT_DISCOVER_ATTRIBUTE	Discover Attributes. Discover Attributes of any type. @note The use of this type of discover is not recommended for discovering in ranges across multiple services/characteristics as it may incur in more round trips.
BT_GATT_DISCOVER_STD_CHAR_DESC	Discover standard characteristic descriptor values. Discover standard characterestic descriptor values and their properties. Supported descriptors: - Characteristic Extended Properties - Client Characteristic Configuration - Server Characteristic Configuration - Characteristic Presentation Format

◆ anonymous enum

anonymous enum

#include <include/bluetooth/gatt.h>

Subscription flags

Enumerator
BT_GATT_SUBSCRIBE_FLAG_VOLATILE	Persistence flag. If set, indicates that the subscription is not saved on the GATT server side. Therefore, upon disconnection, the subscription will be automatically removed from the client's subscriptions list and when the client reconnects, it will have to issue a new subscription.
BT_GATT_SUBSCRIBE_FLAG_NO_RESUB	No resubscribe flag. By default when BT_GATT_SUBSCRIBE_FLAG_VOLATILE is unset, the subscription will be automatically renewed when the client reconnects, as a workaround for GATT servers that do not persist subscriptions. This flag will disable the automatic resubscription. It is useful if the application layer knows that the GATT server remembers subscriptions from previous connections and wants to avoid renewing the subscriptions.
BT_GATT_SUBSCRIBE_FLAG_WRITE_PENDING	Write pending flag. If set, indicates write operation is pending waiting remote end to respond.
BT_GATT_SUBSCRIBE_NUM_FLAGS

Function Documentation

◆ bt_gatt_cancel()

void bt_gatt_cancel	(	struct bt_conn *	conn,
		void *	params
	)

#include <include/bluetooth/gatt.h>

Cancel GATT pending request.

Parameters

conn	Connection object.
params	Requested params address.

◆ bt_gatt_discover()

int bt_gatt_discover	(	struct bt_conn *	conn,
		struct bt_gatt_discover_params *	params
	)

#include <include/bluetooth/gatt.h>

GATT Discover function.

This procedure is used by a client to discover attributes on a server.

Primary Service Discovery: Procedure allows to discover specific Primary Service based on UUID. Include Service Discovery: Procedure allows to discover all Include Services within specified range. Characteristic Discovery: Procedure allows to discover all characteristics within specified handle range as well as discover characteristics with specified UUID. Descriptors Discovery: Procedure allows to discover all characteristic descriptors within specified range.

For each attribute found the callback is called which can then decide whether to continue discovering or stop.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

Parameters

conn	Connection object.
params	Discover parameters.

Returns: 0 in case of success or negative value in case of error.

◆ bt_gatt_exchange_mtu()

int bt_gatt_exchange_mtu	(	struct bt_conn *	conn,
		struct bt_gatt_exchange_params *	params
	)

#include <include/bluetooth/gatt.h>

Exchange MTU.

This client procedure can be used to set the MTU to the maximum possible size the buffers can hold.

Note: Shall only be used once per connection.

Parameters

conn	Connection object.
params	Exchange MTU parameters.

Returns: 0 in case of success or negative value in case of error.

◆ bt_gatt_read()

int bt_gatt_read	(	struct bt_conn *	conn,
		struct bt_gatt_read_params *	params
	)

#include <include/bluetooth/gatt.h>

Read Attribute Value by handle.

This procedure read the attribute value and return it to the callback.

When reading attributes by UUID the callback can be called multiple times depending on how many instances of given the UUID exists with the start_handle being updated for each instance.

If an instance does contain a long value which cannot be read entirely the caller will need to read the remaining data separately using the handle and offset.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

Parameters

conn	Connection object.
params	Read parameters.

Returns: 0 in case of success or negative value in case of error.

◆ bt_gatt_resubscribe()

int bt_gatt_resubscribe	(	uint8_t	id,
		const bt_addr_le_t *	peer,
		struct bt_gatt_subscribe_params *	params
	)

#include <include/bluetooth/gatt.h>

Resubscribe Attribute Value Notification subscription.

Resubscribe to Attribute Value Notification when already subscribed from a previous connection. The GATT server will remember subscription from previous connections when bonded, so resubscribing can be done without performing a new subscribe procedure after a power cycle.

Note: Notifications are asynchronous therefore the parameters need to remain valid while subscribed.

Parameters

id	Local identity (in most cases BT_ID_DEFAULT).
peer	Remote address.
params	Subscribe parameters.

Returns: 0 in case of success or negative value in case of error.

◆ bt_gatt_subscribe()

int bt_gatt_subscribe	(	struct bt_conn *	conn,
		struct bt_gatt_subscribe_params *	params
	)

#include <include/bluetooth/gatt.h>

Subscribe Attribute Value Notification.

This procedure subscribe to value notification using the Client Characteristic Configuration handle. If notification received subscribe value callback is called to return notified value. One may then decide whether to unsubscribe directly from this callback. Notification callback with NULL data will not be called if subscription was removed by this method.

Note: Notifications are asynchronous therefore the parameters need to remain valid while subscribed.

Parameters

conn	Connection object.
params	Subscribe parameters.

Returns: 0 in case of success or negative value in case of error.

◆ bt_gatt_unsubscribe()

int bt_gatt_unsubscribe	(	struct bt_conn *	conn,
		struct bt_gatt_subscribe_params *	params
	)

#include <include/bluetooth/gatt.h>

Unsubscribe Attribute Value Notification.

This procedure unsubscribe to value notification using the Client Characteristic Configuration handle. Notification callback with NULL data will be called if subscription was removed by this call, until then the parameters cannot be reused.

Parameters

conn	Connection object.
params	Subscribe parameters.

Returns: 0 in case of success or negative value in case of error.

◆ bt_gatt_write()

int bt_gatt_write	(	struct bt_conn *	conn,
		struct bt_gatt_write_params *	params
	)

#include <include/bluetooth/gatt.h>

Write Attribute Value by handle.

This procedure write the attribute value and return the result in the callback.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

Parameters

conn	Connection object.
params	Write parameters.

Returns: 0 in case of success or negative value in case of error.

◆ bt_gatt_write_without_response()

static int bt_gatt_write_without_response	(	struct bt_conn *	conn,
		uint16_t	handle,
		const void *	data,
		uint16_t	length,
		bool	sign
	)

inlinestatic

#include <include/bluetooth/gatt.h>

Write Attribute Value by handle without response.

This procedure write the attribute value without requiring an acknowledgment that the write was successfully performed

Parameters

conn	Connection object.
handle	Attribute handle.
data	Data to be written.
length	Data length.
sign	Whether to sign data

Returns: 0 in case of success or negative value in case of error.

◆ bt_gatt_write_without_response_cb()

int bt_gatt_write_without_response_cb	(	struct bt_conn *	conn,
		uint16_t	handle,
		const void *	data,
		uint16_t	length,
		bool	sign,
		bt_gatt_complete_func_t	func,
		void *	user_data
	)

#include <include/bluetooth/gatt.h>

Write Attribute Value by handle without response with callback.

This function works in the same way as bt_gatt_write_without_response. With the addition that after sending the write the callback function will be called.

The callback is run from System Workqueue context. When called from the System Workqueue context this API will not wait for resources for the callback but instead return an error. The number of pending callbacks can be increased with the

embed:rst:inline :kconfig:`CONFIG_BT_CONN_TX_MAX`

option.

Note: By using a callback it also disable the internal flow control which would prevent sending multiple commands without waiting for their transmissions to complete, so if that is required the caller shall not submit more data until the callback is called.

Parameters

conn	Connection object.
handle	Attribute handle.
data	Data to be written.
length	Data length.
sign	Whether to sign data
func	Transmission complete callback.
user_data	User data to be passed back to callback.

Returns: 0 in case of success or negative value in case of error.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ bt_gatt_discover_func_t

◆ bt_gatt_notify_func_t

◆ bt_gatt_read_func_t

◆ bt_gatt_write_func_t

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ bt_gatt_cancel()

◆ bt_gatt_discover()

◆ bt_gatt_exchange_mtu()

◆ bt_gatt_read()

◆ bt_gatt_resubscribe()

◆ bt_gatt_subscribe()

◆ bt_gatt_unsubscribe()

◆ bt_gatt_write()

◆ bt_gatt_write_without_response()

◆ bt_gatt_write_without_response_cb()