pw_bluetooth/public/pw_bluetooth/gatt/client.h - pigweed/pigweed - Git at Google

 // Copyright 2022 The Pigweed Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
 // use this file except in compliance with the License. You may obtain a copy of
 // the License at
 //
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 // License for the specific language governing permissions and limitations under
 // the License.
 #pragma once

 #include <memory>

 #include "pw_bluetooth/gatt/constants.h"
 #include "pw_bluetooth/gatt/error.h"
 #include "pw_bluetooth/gatt/types.h"
 #include "pw_bluetooth/result.h"
 #include "pw_bluetooth/types.h"
 #include "pw_containers/vector.h"
 #include "pw_function/function.h"
 #include "pw_result/result.h"
 #include "pw_span/span.h"

 namespace pw::bluetooth::gatt {

 // Represents a GATT service on a remote GATT server.
 // Clients should call `SetErrorCallback` before using in order to handle fatal
 // errors.
 class RemoteService {
  public:
   enum class RemoteServiceError {
     // The service has been modified or removed.
     kServiceRemoved = 0,

     // The peer serving this service has disconnected.
     kPeerDisconnected = 1,
   };

   // Wrapper around a possible truncated value received from the server.
   struct ReadValue {
     // Characteristic or descriptor handle.
     Handle handle;

     // The value of the characteristic or descriptor.
     Vector<std::byte> value;

     // True if `value` might be truncated (the buffer was completely filled by
     // the server and the read was a short read).  `ReadCharacteristic` or
     // `ReadDescriptor` should be used to read the complete value.
     bool maybe_truncated;
   };

   // A result returned by `ReadByType`.
   struct ReadByTypeResult {
     // Characteristic or descriptor handle.
     Handle handle;

     // The value of the characteristic or descriptor, if it was read
     // successfully, or an error explaining why the value could not be read.
     Result<Error, ReadValue> result;
   };

   // Represents the supported options to read a long characteristic or
   // descriptor value from a server. Long values are those that may not fit in a
   // single message (longer than 22 bytes).
   struct LongReadOptions {
     // The byte to start the read at. Must be less than the length of the
     // value.
     uint16_t offset = 0;

     // The maximum number of bytes to read.
     uint16_t max_bytes = kMaxValueLength;
   };

   // Represents the supported write modes for writing characteristics &
   // descriptors to the server.
   enum class WriteMode : uint8_t {
     // Wait for a response from the server before returning but do not verify
     // the echo response. Supported for both characteristics and descriptors.
     kDefault = 0,

     // 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.
     kReliable = 1,

     // 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.
     kWithoutResponse = 2,
   };

   // Represents the supported options to write a characteristic/descriptor value
   // to a server.
   struct WriteOptions {
     // The mode of the write operation. For descriptors, only
     // `WriteMode::kDefault` is supported
     WriteMode mode = WriteMode::kDefault;

     // Request a write starting at the byte indicated.
     // Must be 0 if `mode` is `WriteMode.kWithoutResponse`.
     uint16_t offset = 0;
   };

   using ReadByTypeCallback = Function<void(Result<Vector<ReadByTypeResult>>)>;
   using ReadCallback = Function<void(Result<ReadValue>)>;
   using NotificationCallback = Function<void(ReadValue)>;

   // Set a callback that will be called when there is an error with this
   // RemoteService, after which this RemoteService will be invalid.
   void SetErrorCallback(Function<void(RemoteServiceError)> error_callback);

   // Calls `characteristic_callback` with the characteristics and descriptors in
   // this service.
   void DiscoverCharacteristics(
       Function<void(Characteristic)>&& characteristic_callback);

   // Reads characteristics and descriptors with the specified type. This method
   // is useful for reading values before discovery has completed, thereby
   // reducing latency.
   // `uuid` - The UUID of the characteristics/descriptors to read.
   // `result_callback` - Results are returned via this callback. 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 a Vector. Consider reading characteristics/descriptors individually
   //    after performing discovery.
   // kFailure: The server returned an error not specific to a single result.
   void ReadByType(Uuid uuid, ReadByTypeCallback&& result_callback);

   // Reads the value of a characteristic.
   // `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.
   // `result_callback` - called with the result of the read and the value of the
   //     characteristic if successful.
   //
   // This may fail with the following errors:
   // kInvalidHandle - if `handle` is invalid
   // kInvalidParameters - if `options is invalid
   // kReadNotPermitted or kInsufficient* if the server rejects the request.
   // kFailure if the server returns an error not covered by the above errors.
   void ReadCharacteristic(Handle handle,
                           std::optional<LongReadOptions> options,
                           ReadCallback&& result_callback);

   // Writes `value` to the characteristic with `handle` using the provided
   // `options`.  It is not recommended to send additional writes while a write
   // is already in progress (the server may receive simultaneous writes in any
   // order).
   //
   // Parameters:
   // `handle` - Handle of the characteristic to be written to
   // `value` - The value to be written.
   // `options` - Options that apply to the write.
   //
   // This may fail with the following errors:
   // kInvalidHandle - if `handle` is invalid
   // kInvalidParameters - if `options is invalid
   // kWriteNotPermitted or kInsufficient* if the server rejects the request.
   // kFailure if the server returns an error not covered by the above errors.
   void WriteCharacteristic(Handle handle,
                            span<const std::byte> value,
                            WriteOptions options,
                            Function<void(Result<Error>)>&& result_callback);

   // Reads the value of the characteristic descriptor with `handle` and
   // returns it in the reply.
   // `handle` - The descriptor handle to read.
   // `options` - Options that apply to the read.
   // `result_callback` - Returns a result containing the value of the descriptor
   //     on success.
   //
   // This may fail with the following errors:
   // `kInvalidHandle` - if `handle` is invalid.
   // `kInvalidParameters` - if `options` is invalid.
   // `kReadNotPermitted` or `INSUFFICIENT_*` - if the server rejects the read
   // request. `kFailure` - if the server returns an error.
   void ReadDescriptor(Handle handle,
                       std::optional<LongReadOptions> options,
                       ReadCallback&& result_callback);

   void WriteDescriptor(Handle handle,
                        span<const std::byte> value,
                        WriteOptions options,
                        Function<void(Result<Error>)>&& result_callback);

   // 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 descriptor. This method fails if an error occurs while
   // writing to the descriptor.
   //
   // On success, `notification_callback` will be called 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.
   // `notification_callback` - will be called with the values of
   //     notifications/indications when received.
   // `result_callback` - called with the result of enabling
   //     notifications/indications.
   //
   // This may fail with the following errors:
   // `kFailure` - the characteristic does not support notifications or
   //     indications.
   // `kInvalidHandle` - `handle` is invalid.
   // `kWriteNotPermitted`or `kInsufficient*` - descriptor write error.
   void RegisterNotificationCallback(
       Handle handle,
       NotificationCallback&& notification_callback,
       Function<void(Result<Error>)> result_callback);

   // Stops notifications for the characteristic with the given `handle`.
   void StopNotifications(Handle handle);
 };

 // Represents a GATT client that interacts with services on a GATT server.
 class Client {
  public:
   // Represents a remote GATT service.
   struct RemoteServiceInfo {
     // Uniquely identifies this GATT service.
     Handle handle;

     // Indicates whether this is a primary or secondary service.
     bool primary;

     // The UUID that identifies the type of this service.
     // There may be multiple services with the same UUID.
     Uuid type;
   };

   virtual ~Client() = default;

   // Enumerates existing services found on the peer that this Client represents,
   // and provides a stream of updates thereafter. Results can be filtered by
   // specifying a list of UUIDs in `uuids`. To further interact with services,
   // clients must obtain a RemoteService protocol by calling ConnectToService().
   // `uuid_allowlist` - The allowlist of UUIDs to filter services with.
   // `updated_callback` - Will be called with services that are
   //     updated/modified.
   // `removed_callback` - Called with the handles of servies
   //     that have been removed. Note that handles may be reused.
   virtual void WatchServices(
       Vector<Uuid> uuid_allowlist,
       Function<void(RemoteServiceInfo)>&& updated_callback,
       Function<void(Handle)>&& removed_callback) = 0;

   // Stops service watching if started by `WatchServices`.
   virtual void StopWatchingServices();

   // Connects to a RemoteService. Only 1 connection per service is allowed.
   // `handle` - the handle of the service to connect to.
   //
   // This may fail with the following errors:
   // kInvalidParameters - `handle` does not correspond to a known service.
   virtual Result<Error, std::unique_ptr<RemoteService>> ConnectToService(
       Handle handle) = 0;
 };

 }  // namespace pw::bluetooth::gatt
	// Copyright 2022 The Pigweed Authors
	//
	// Licensed under the Apache License, Version 2.0 (the "License"); you may not
	// use this file except in compliance with the License. You may obtain a copy of
	// the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	// License for the specific language governing permissions and limitations under
	// the License.
	#pragma once

	#include <memory>

	#include "pw_bluetooth/gatt/constants.h"
	#include "pw_bluetooth/gatt/error.h"
	#include "pw_bluetooth/gatt/types.h"
	#include "pw_bluetooth/result.h"
	#include "pw_bluetooth/types.h"
	#include "pw_containers/vector.h"
	#include "pw_function/function.h"
	#include "pw_result/result.h"
	#include "pw_span/span.h"

	namespace pw::bluetooth::gatt {

	// Represents a GATT service on a remote GATT server.
	// Clients should call `SetErrorCallback` before using in order to handle fatal
	// errors.
	class RemoteService {
	public:
	enum class RemoteServiceError {
	// The service has been modified or removed.
	kServiceRemoved = 0,

	// The peer serving this service has disconnected.
	kPeerDisconnected = 1,
	};

	// Wrapper around a possible truncated value received from the server.
	struct ReadValue {
	// Characteristic or descriptor handle.
	Handle handle;

	// The value of the characteristic or descriptor.
	Vector<std::byte> value;

	// True if `value` might be truncated (the buffer was completely filled by
	// the server and the read was a short read). `ReadCharacteristic` or
	// `ReadDescriptor` should be used to read the complete value.
	bool maybe_truncated;
	};

	// A result returned by `ReadByType`.
	struct ReadByTypeResult {
	// Characteristic or descriptor handle.
	Handle handle;

	// The value of the characteristic or descriptor, if it was read
	// successfully, or an error explaining why the value could not be read.
	Result<Error, ReadValue> result;
	};

	// Represents the supported options to read a long characteristic or
	// descriptor value from a server. Long values are those that may not fit in a
	// single message (longer than 22 bytes).
	struct LongReadOptions {
	// The byte to start the read at. Must be less than the length of the
	// value.
	uint16_t offset = 0;

	// The maximum number of bytes to read.
	uint16_t max_bytes = kMaxValueLength;
	};

	// Represents the supported write modes for writing characteristics &
	// descriptors to the server.
	enum class WriteMode : uint8_t {
	// Wait for a response from the server before returning but do not verify
	// the echo response. Supported for both characteristics and descriptors.
	kDefault = 0,

	// 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.
	kReliable = 1,

	// 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.
	kWithoutResponse = 2,
	};

	// Represents the supported options to write a characteristic/descriptor value
	// to a server.
	struct WriteOptions {
	// The mode of the write operation. For descriptors, only
	// `WriteMode::kDefault` is supported
	WriteMode mode = WriteMode::kDefault;

	// Request a write starting at the byte indicated.
	// Must be 0 if `mode` is `WriteMode.kWithoutResponse`.
	uint16_t offset = 0;
	};

	using ReadByTypeCallback = Function<void(Result<Vector<ReadByTypeResult>>)>;
	using ReadCallback = Function<void(Result<ReadValue>)>;
	using NotificationCallback = Function<void(ReadValue)>;

	// Set a callback that will be called when there is an error with this
	// RemoteService, after which this RemoteService will be invalid.
	void SetErrorCallback(Function<void(RemoteServiceError)> error_callback);

	// Calls `characteristic_callback` with the characteristics and descriptors in
	// this service.
	void DiscoverCharacteristics(
	Function<void(Characteristic)>&& characteristic_callback);

	// Reads characteristics and descriptors with the specified type. This method
	// is useful for reading values before discovery has completed, thereby
	// reducing latency.
	// `uuid` - The UUID of the characteristics/descriptors to read.
	// `result_callback` - Results are returned via this callback. 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 a Vector. Consider reading characteristics/descriptors individually
	// after performing discovery.
	// kFailure: The server returned an error not specific to a single result.
	void ReadByType(Uuid uuid, ReadByTypeCallback&& result_callback);

	// Reads the value of a characteristic.
	// `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.
	// `result_callback` - called with the result of the read and the value of the
	// characteristic if successful.
	//
	// This may fail with the following errors:
	// kInvalidHandle - if `handle` is invalid
	// kInvalidParameters - if `options is invalid
	// kReadNotPermitted or kInsufficient* if the server rejects the request.
	// kFailure if the server returns an error not covered by the above errors.
	void ReadCharacteristic(Handle handle,
	std::optional<LongReadOptions> options,
	ReadCallback&& result_callback);

	// Writes `value` to the characteristic with `handle` using the provided
	// `options`. It is not recommended to send additional writes while a write
	// is already in progress (the server may receive simultaneous writes in any
	// order).
	//
	// Parameters:
	// `handle` - Handle of the characteristic to be written to
	// `value` - The value to be written.
	// `options` - Options that apply to the write.
	//
	// This may fail with the following errors:
	// kInvalidHandle - if `handle` is invalid
	// kInvalidParameters - if `options is invalid
	// kWriteNotPermitted or kInsufficient* if the server rejects the request.
	// kFailure if the server returns an error not covered by the above errors.
	void WriteCharacteristic(Handle handle,
	span<const std::byte> value,
	WriteOptions options,
	Function<void(Result<Error>)>&& result_callback);

	// Reads the value of the characteristic descriptor with `handle` and
	// returns it in the reply.
	// `handle` - The descriptor handle to read.
	// `options` - Options that apply to the read.
	// `result_callback` - Returns a result containing the value of the descriptor
	// on success.
	//
	// This may fail with the following errors:
	// `kInvalidHandle` - if `handle` is invalid.
	// `kInvalidParameters` - if `options` is invalid.
	// `kReadNotPermitted` or `INSUFFICIENT_*` - if the server rejects the read
	// request. `kFailure` - if the server returns an error.
	void ReadDescriptor(Handle handle,
	std::optional<LongReadOptions> options,
	ReadCallback&& result_callback);

	void WriteDescriptor(Handle handle,
	span<const std::byte> value,
	WriteOptions options,
	Function<void(Result<Error>)>&& result_callback);

	// 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 descriptor. This method fails if an error occurs while
	// writing to the descriptor.
	//
	// On success, `notification_callback` will be called 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.
	// `notification_callback` - will be called with the values of
	// notifications/indications when received.
	// `result_callback` - called with the result of enabling
	// notifications/indications.
	//
	// This may fail with the following errors:
	// `kFailure` - the characteristic does not support notifications or
	// indications.
	// `kInvalidHandle` - `handle` is invalid.
	// `kWriteNotPermitted`or `kInsufficient*` - descriptor write error.
	void RegisterNotificationCallback(
	Handle handle,
	NotificationCallback&& notification_callback,
	Function<void(Result<Error>)> result_callback);

	// Stops notifications for the characteristic with the given `handle`.
	void StopNotifications(Handle handle);
	};

	// Represents a GATT client that interacts with services on a GATT server.
	class Client {
	public:
	// Represents a remote GATT service.
	struct RemoteServiceInfo {
	// Uniquely identifies this GATT service.
	Handle handle;

	// Indicates whether this is a primary or secondary service.
	bool primary;

	// The UUID that identifies the type of this service.
	// There may be multiple services with the same UUID.
	Uuid type;
	};

	virtual ~Client() = default;

	// Enumerates existing services found on the peer that this Client represents,
	// and provides a stream of updates thereafter. Results can be filtered by
	// specifying a list of UUIDs in `uuids`. To further interact with services,
	// clients must obtain a RemoteService protocol by calling ConnectToService().
	// `uuid_allowlist` - The allowlist of UUIDs to filter services with.
	// `updated_callback` - Will be called with services that are
	// updated/modified.
	// `removed_callback` - Called with the handles of servies
	// that have been removed. Note that handles may be reused.
	virtual void WatchServices(
	Vector<Uuid> uuid_allowlist,
	Function<void(RemoteServiceInfo)>&& updated_callback,
	Function<void(Handle)>&& removed_callback) = 0;

	// Stops service watching if started by `WatchServices`.
	virtual void StopWatchingServices();

	// Connects to a RemoteService. Only 1 connection per service is allowed.
	// `handle` - the handle of the service to connect to.
	//
	// This may fail with the following errors:
	// kInvalidParameters - `handle` does not correspond to a known service.
	virtual Result<Error, std::unique_ptr<RemoteService>> ConnectToService(
	Handle handle) = 0;
	};

	} // namespace pw::bluetooth::gatt