An interface for interacting with a GATT service on a peer device. More...

#include <client2.h>

Classes
struct	LongReadOptions

struct	ReadByTypeResult
	A result returned by `ReadByType`. More...

struct	ReadValue
	Wrapper around a possible truncated value received from the server. More...

struct	WriteOptions

Public Types
enum class	RemoteServiceError { kServiceRemoved = 0 , kPeerDisconnected = 1 }

enum class	WriteMode : uint8_t { kDefault , kReliable , kWithoutResponse }

using	Ptr = internal::RaiiPtr< RemoteService2, &RemoteService2::Disconnect >

Public Member Functions
virtual async2::Poll< RemoteServiceError >	PendError (async2::Context &cx)=0

virtual void	DiscoverCharacteristics (async2::OnceRefSender< Vector< Characteristic2 > > characteristics_sender)=0

virtual async2::OnceReceiver< pw::expected< Vector< ReadByTypeResult, 5 >, Error > >	ReadByType (Uuid uuid)=0

virtual async2::OnceReceiver< pw::expected< ReadValue, Error > >	ReadCharacteristic (Handle handle, std::optional< LongReadOptions > options)=0

virtual async2::OnceReceiver< pw::expected< void, Error > >	WriteCharacteristic (Handle handle, pw::multibuf::MultiBuf &&value, WriteOptions options)=0

virtual async2::OnceReceiver< pw::expected< ReadValue, Error > >	ReadDescriptor (Handle handle, std::optional< LongReadOptions > options)=0

virtual async2::OnceReceiver< pw::expected< void, Error > >	WriteDescriptor (Handle handle, pw::multibuf::MultiBuf &&value)=0

virtual async2::OnceReceiver< pw::expected< void, Error > >	EnableNotifications (Handle handle)=0

virtual async2::Poll< ReadValue >	PendNotification (Handle handle, async2::Context &cx)=0

virtual async2::OnceReceiver< pw::expected< void, Error > >	StopNotifications (Handle handle)=0

Private Member Functions
virtual void	Disconnect ()=0

Detailed Description

An interface for interacting with a GATT service on a peer device.

Member Typedef Documentation

◆ Ptr

using pw::bluetooth::gatt::RemoteService2::Ptr = internal::RaiiPtr<RemoteService2, &RemoteService2::Disconnect>

Movable RemoteService2 smart pointer. The remote server will remain connected until the returned RemoteService2::Ptr is destroyed.

Member Enumeration Documentation

◆ RemoteServiceError

enum class pw::bluetooth::gatt::RemoteService2::RemoteServiceError

strong

Enumerator
kServiceRemoved	The service has been modified or removed.
kPeerDisconnected	The peer serving this service has disconnected.

◆ WriteMode

enum class pw::bluetooth::gatt::RemoteService2::WriteMode : uint8_t

strong

Represents the supported write modes for writing characteristics & descriptors to the server.

Enumerator
kDefault	Wait for a response from the server before returning but do not verify the echo response. Supported for both characteristics and descriptors.
kReliable	Every value blob is verified against an echo response from the server. The procedure is aborted if a value blob has not been reliably delivered to the peer. Only supported for characteristics.
kWithoutResponse	Delivery will not be confirmed before returning. Writing without a response is only supported for short characteristics with the `WRITE_WITHOUT_RESPONSE` property. The value must fit into a single message. It is guaranteed that at least 20 bytes will fit into a single message. If the value does not fit, a `kFailure` error will be produced. The value will be written at offset 0. Only supported for characteristics.

Member Function Documentation

◆ Disconnect()

virtual void pw::bluetooth::gatt::RemoteService2::Disconnect ( )

privatepure virtual

Disconnect from the remote service. This method is called by the ~RemoteServicePtr() when it goes out of scope, the API client should never call this method.

◆ DiscoverCharacteristics()

virtual void pw::bluetooth::gatt::RemoteService2::DiscoverCharacteristics ( async2::OnceRefSender< Vector< Characteristic2 > > characteristics_sender )

pure virtual

Asynchronously sends the characteristics in this service, up to Vector::.max_size(). May perform service discovery if the characteristics are not yet known.

◆ EnableNotifications()

virtual async2::OnceReceiver< pw::expected< void, Error > > pw::bluetooth::gatt::RemoteService2::EnableNotifications ( Handle handle )

pure virtual

Subscribe to notifications & indications from the characteristic with the given handle.

Either notifications or indications will be enabled depending on characteristic properties. Indications will be preferred if they are supported. This operation fails if the characteristic does not have the "notify" or "indicate" property.

A write request will be issued to configure the characteristic for notifications/indications if it contains a Client Characteristic Configuration (CCC) descriptor. This method fails if an error occurs while writing to the descriptor.

On success, PendNotification will return Ready when the peer sends a notification or indication. Indications are automatically confirmed.

Subscriptions can be canceled with StopNotifications.

Parameters

handle the handle of the characteristic to subscribe to.

Returns

The result of enabling notifications/indications.

kFailure The characteristic does not support notifications or indications.
kInvalidHandle handle is invalid.
kWriteNotPermitted CCC descriptor write error.
kInsufficient* Insufficient security properties to write to CCC descriptor.

◆ PendError()

virtual async2::Poll< RemoteServiceError > pw::bluetooth::gatt::RemoteService2::PendError ( async2::Context & cx )

pure virtual

Poll for an Error status on this service, waking cx and returning Ready when there is an error condition. When an error condition is present, any previous RemoteService2 Waker and OnceReceiver instances may or may not be woken and all other methods will be no-ops. Only 1 waker can be set at a time (additional calls will replace the existing waker).

◆ PendNotification()

virtual async2::Poll< ReadValue > pw::bluetooth::gatt::RemoteService2::PendNotification	(	Handle	handle,
		async2::Context &	cx
	)

pure virtual

After notifications have been enabled with EnableNotifications, this method can be used to check for notifications. This method will safely return Pending when notifications are disabled.

Parameters

handle	The handle of the characteristic to await for notifications.
cx	The Context to awaken when a notification is available. Only one Waker per handle is supported at a time (subsequent calls will overwrite the old Waker).

◆ ReadByType()

virtual async2::OnceReceiver< pw::expected< Vector< ReadByTypeResult, 5 >, Error > > pw::bluetooth::gatt::RemoteService2::ReadByType ( Uuid uuid )

pure virtual

Reads characteristics and descriptors with the specified type. This method is useful for reading values before discovery has completed, thereby reducing latency.

Parameters

uuid	The UUID of the characteristics/descriptors to read.

Returns: The result of the read. Results may be empty if no matching values are read. If reading a value results in a permission error, the handle and error will be included.

This may fail with the following errors:

kInvalidParameters: if uuid refers to an internally reserved descriptor type (e.g. the Client Characteristic Configuration descriptor).
kTooManyResults: More results were read than can fit in the Vector. Consider reading characteristics/descriptors individually after performing discovery.
kFailure: The server returned an error not specific to a single result.

◆ ReadCharacteristic()

virtual async2::OnceReceiver< pw::expected< ReadValue, Error > > pw::bluetooth::gatt::RemoteService2::ReadCharacteristic	(	Handle	handle,
		std::optional< LongReadOptions >	options
	)

pure virtual

Reads the value of a characteristic.

Parameters

handle	The handle of the characteristic to be read.
options	If null, a short read will be performed, which may be truncated to what fits in a single message (at least 22 bytes). If long read options are present, performs a long read with the indicated options.

Returns

The result of the read and the value of the characteristic if successful. Returns the following errors:

kInvalidHandle handle is invalid.
kInvalidParameters options is invalid.
kReadNotPermitted The server rejected the request.
kInsufficient* The server rejected the request.
kApplicationError* An application error was returned by the GATT profile.
kFailure The server returned an error not covered by the above.

◆ ReadDescriptor()

virtual async2::OnceReceiver< pw::expected< ReadValue, Error > > pw::bluetooth::gatt::RemoteService2::ReadDescriptor	(	Handle	handle,
		std::optional< LongReadOptions >	options
	)

pure virtual

Reads the value of the characteristic descriptor with handle and returns it in the reply.

Parameters

handle	The descriptor handle to read.
options	Options that apply to the read.
result_sender	Set to a result containing the value of the descriptor on success.

Return values

kInvalidHandle	`handle` is invalid.
kInvalidParameters	`options` is invalid.
kReadNotPermitted
kInsufficient*	The server rejected the request.
kApplicationError*	An application error was returned by the GATT profile.
kFailure	The server returned an error not covered by the above errors.

◆ StopNotifications()

virtual async2::OnceReceiver< pw::expected< void, Error > > pw::bluetooth::gatt::RemoteService2::StopNotifications ( Handle handle )

pure virtual

Stops notifications for the characteristic with the given handle.

Returns

The result of disabling notifications/indications. Possible errors:

kFailure The characteristic does not support notifications or indications.
kInvalidHandle handle is invalid.
kWriteNotPermitted CCC descriptor write error.
Insufficient* CCC descriptor write error.

◆ WriteCharacteristic()

virtual async2::OnceReceiver< pw::expected< void, Error > > pw::bluetooth::gatt::RemoteService2::WriteCharacteristic	(	Handle	handle,
		pw::multibuf::MultiBuf &&	value,
		WriteOptions	options
	)

pure virtual

Writes value to the characteristic with handle using the provided options.

Parameters

handle	Handle of the characteristic to be written to
value	The value to be written.
options	Options that apply to the write.

Returns

A result is returned when a response to the write is received. For WriteWithoutResponse, this is set as soon as the write is sent. Returns the following errors:

kInvalidHandle handle is invalid.
kInvalidParameters`options is invalid.
kWriteNotPermitted The server rejected the request.
kInsufficient* The server rejected the request.
kApplicationError* An application error was returned by the GATT profile.
kFailure The server returned an error not covered by the above errors.

◆ WriteDescriptor()

virtual async2::OnceReceiver< pw::expected< void, Error > > pw::bluetooth::gatt::RemoteService2::WriteDescriptor	(	Handle	handle,
		pw::multibuf::MultiBuf &&	value
	)

pure virtual

Writes value to the descriptor with handle using the provided. It is not recommended to send additional writes while a write is already in progress.

Parameters

handle	Handle of the descriptor to be written to.
value	The value to be written.

Returns

The result upon completion of the write. Possible errors:

kInvalidHandle handle is invalid.
kInvalidParameters `options is invalid.
kWriteNotPermitted The server rejected the request.
kInsufficient* The server rejected the request.
kApplicationError* An application error was returned by the GATT profile.
kFailure The server returned an error not covered by the above errors.

The documentation for this class was generated from the following file:

pw_bluetooth/public/pw_bluetooth/gatt/client2.h

Classes

Public Types

Public Member Functions

Private Member Functions

Detailed Description

Member Typedef Documentation

◆ Ptr

Member Enumeration Documentation

◆ RemoteServiceError

◆ WriteMode

Member Function Documentation

◆ Disconnect()

◆ DiscoverCharacteristics()

◆ EnableNotifications()

◆ PendError()

◆ PendNotification()

◆ ReadByType()

◆ ReadCharacteristic()

◆ ReadDescriptor()

◆ StopNotifications()

◆ WriteCharacteristic()

◆ WriteDescriptor()