sdk/fidl/fuchsia.bluetooth.gatt2/server.fidl - fuchsia - Git at Google

 // Copyright 2021 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 library fuchsia.bluetooth.gatt2;

 using fuchsia.bluetooth as bt;
 using zx;

 /// The amount of credits defined to be available for sending indications/notifications when a
 /// LocalService is first published.
 const INITIAL_VALUE_CHANGED_CREDITS uint32 = 10;

 /// The parameters used to signal a characteristic value change from a LocalService to a peer.
 type ValueChangedParameters = table {
     /// The handle of the characteristic value being signalled.
     /// Mandatory.
     1: handle Handle;
     /// The updated value of the characteristic.
     /// Note for clients using indications/notifications for high-throughput (not recommended):
     /// While statically constrained to `MAX_VALUE_LENGTH`, the real limit depends on the specific
     /// peer's configuration as notified by `LocalService.PeerUpdate`. Any bytes exceeding that
     /// limit are truncated internally by the stack.
     /// Mandatory.
     2: value bytes:MAX_VALUE_LENGTH;
     /// Only signal a subset of peers.
     /// If not present or empty, all peers that can be updated are signaled.
     /// If included, only the set of peers in this list will be signaled.
     /// Peers are only signaled if they have configured updates or notifications per `LocalService.`
     /// `CharacteristicConfiguration`; other peers in `peer_ids` will be ignored.
     3: peer_ids vector<bt.PeerId>:MAX;
 };

 /// Interface for serving a local GATT service. Closing the server_end of this protocol causes the
 /// GATT service to be removed from the local GATT database. Similarly, closure of the client_end
 /// of this protocol means the Bluetooth stack has removed this service from its GATT database.
 protocol LocalService {
     /// This notifies the current configuration of a particular characteristic/descriptor for a
     /// particular peer. It will be called when the peer GATT client changes the configuration.
     ///
     /// The Bluetooth stack maintains the state of each peer's configuration across reconnections.
     /// As such, this method will also be called when a peer connects for each characteristic with
     /// the initial, persisted state of the newly-connected peer's configuration. However, clients
     /// should not rely on this state being persisted indefinitely by the Bluetooth stack.
     ///
     /// + request `peer_id` The PeerId of the GATT client associated with this particular CCC.
     /// + request `handle` The handle of the characteristic associated with the `notify` and
     ///  `indicate` parameters.
     /// + request `notify` True if the client has enabled notifications, false otherwise.
     /// + request `indicate` True if the client has enabled indications, false otherwise.
     /// - response empty Returns nothing to acknowledge the characteristic configuration.
     CharacteristicConfiguration(struct {
         peer_id bt.PeerId;
         handle Handle;
         notify bool;
         indicate bool;
     }) -> ();

     /// Called when a peer requests to read the value of a characteristic or descriptor. It is
     /// guaranteed that the peer satisfies the permssions associated with this attribute.
     ///
     /// + request `peer_id` The PeerId of the GATT client making the read request.
     /// + request `handle` The handle of the requested descriptor/characteristic.
     /// + request `offset` The offset at which to start reading the requested value.
     /// - response `value` The value of the characteristic.
     /// * error See `gatt2.Error` documentation for possible errors.
     ReadValue(struct {
         peer_id bt.PeerId;
         handle Handle;
         offset int32;
     }) -> (struct {
         value bytes:MAX_VALUE_LENGTH;
     }) error Error;

     /// Called when a peer issues a request to write the value of a characteristic or descriptor. It
     /// is guaranteed that the peer satisfies the permissions associated with this attribute.
     ///
     /// + request `peer_id` The PeerId of the GATT client making the write request. Always present.
     /// + request `handle` The handle of the requested descriptor/characteristic. Always present.
     /// + request `offset` The offset at which to start writing the value. If the offset is 0, any
     ///   existing value should be overwritten by the new value. Otherwise, the existing value from
     ///   offset:(offset + len(value)) should be changed to `value`. Always present.
     /// + request `value` The new value for the descriptor/characteristic. Always present, but may
     ///   be the empty string.
     /// - response  The implementation must send an empty response once the value has been updated
     ///   as confirmation.
     /// * error See `gatt2.Error` documentation for possible errors.
     WriteValue(table {
         1: peer_id bt.PeerId;
         2: handle Handle;
         3: offset uint32;
         4: value bytes:MAX_VALUE_LENGTH;
     }) -> (struct {}) error Error;

     /// Called to provide GATT information specific to a peer. PeerUpdate will not be called unless
     /// the prior invocation received a response. As such, the implementation can simply ignore the
     /// first invocation if they are not interested in any PeerUpdate fields.
     ///
     /// A PeerUpdate will be made before propagating any other interaction from the peer to the
     /// LocalService (Write/ReadValue, CharacteristicConfiguration) on a best-effort basis, as long
     /// as all preceding PeerUpdates were acknowledged.
     ///
     /// + request `peer_id` The PeerId the update pertains to. Always present.
     /// + request `mtu` The maximum number of bytes that fit in a notification/indication to this
     ///   peer. Any bytes past this limit are silently truncated. Most clients need not concern
     ///   themselves with this unless they are using notifications/indications for high throughput.
     ///   Optional.
     /// - response An empty response to acknowledge that the update was received.
     PeerUpdate(table {
         1: peer_id bt.PeerId;
         2: mtu uint16;
     }) -> ();

     /// After this event, new peers will no longer be able to discover the service, although peers
     /// which have already discovered this service may still access it. This should be sent once per
     /// service lifetime; sending more than once closes the protocol and disconnects GATT clients.
     @transitional("Not currently supported. Comment on fxbug.dev/98598 to request support")
     -> OnSuppressDiscovery();

     /// This event is used to send a notification to a peer. Notifications should be used instead of
     /// indications when the service does *not* require peer confirmation of the update.
     ///
     /// Notifications should not be sent to peers which have not enabled notifications on a
     /// particular characteristic - if they are sent, they will not be propagated. The Bluetooth
     /// stack will track this configuration for the lifetime of the service.
     ///
     /// LocalServices must keep track of available credit provided by the `ValueChangedCredit`
     /// method and send at most that many `OnNotifyValue` and `OnIndicateValue` events. If more
     /// events are sent than available credits, the protocol will be closed.
     -> OnNotifyValue(ValueChangedParameters);

     /// This event is used to send an indication to a peer. Indications should be used instead of
     /// notifications when the service *does* require peer confirmation of the update.
     ///
     /// Indications should not be sent to peers which have not enabled indications on a particular
     /// characteristic - if they are sent, they will not be propagated. The Bluetooth stack will
     /// track this configuration for the lifetime of the service.
     ///
     /// LocalServices must keep track of available credit provided by the `ValueChangedCredit`
     /// method and send at most that many `OnNotifyValue` and `OnIndicateValue` events. If more
     /// events are sent than available credits, the protocol will be closed.
     ///
     /// + request `update` The parameters associated with the changed characteristic.
     /// + request `confirmation` When all peers that will be updated have confirmed the indication,
     ///   `confirmation` is signalled with ZX_EVENTPAIR_SIGNALLED. `confirmation` will be closed if
     ///   indicating any peer fails, such as if the peer hasn't configured indications, is not
     ///   connected, or does not confirm within the ATT transaction timeout of 30 seconds (Bluetooth
     ///   5.3 Vol. 3 Part F 3.3.3). To track indication confirmation on a per-peer basis, the
     ///   implementation can send this event with a single ID in `update.peer_ids`.
     // `confirmation` is an EventPair instead of an Event because the language bindings for Events
     // treat them as resources/move-only, but the LocalService will need to retain a handle to the
     // `confirmation` kernel object in order to wait on the signal from the other side.
     -> OnIndicateValue(resource struct {
         update ValueChangedParameters;
         confirmation zx.handle:EVENTPAIR;
     });

     /// Add credit for sending indications/notifications. Implementors are defined to start out with
     /// INITIAL_VALUE_CHANGED_CREDITS credits before this method is called. Implementors must keep
     /// track of the available credit they have. The implementor can send exactly one OnNotifyValue
     /// or OnIndicateValue event for each credit. Note that `ValueChangedCredit` will only be called
     /// if at least one indication/notification has been sent since the prior call.
     ValueChangedCredit(struct {
         additional_credit uint8;
     });
 };

 @discoverable
 protocol Server {
     /// Publishes the given `service` so that it is available to all remote peers. Upon publication,
     /// the service is defined to have INITIAL_VALUE_CHANGED_CREDITS credits available for sending
     /// indications/notifications.
     ///
     /// The caller must assign distinct handles to the characteristics and descriptors listed in
     /// `info`. These identifiers will be used in requests sent to `service`.
     ///
     /// + request `info` Defines the structure of the GATT service. Includes characteristics and
     ///   descriptors that will be made available to peers, as well as the service handle, which is
     ///   required to be unique across all services published to this Server.
     /// + request `service` Provides the implementation of the service per the documented behavior
     ///   of a `LocalService`.
     /// - response An empty response indicates the service was successfully published.
     /// * error See `gatt2.PublishServiceError` for possible failure modes.
     @transitional("Implementation and migration progress tracked in http://fxbug.dev/36375")
     PublishService(resource struct {
         info ServiceInfo;
         service client_end:LocalService;
     }) -> (struct {}) error PublishServiceError;
 };
	// Copyright 2021 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.
	library fuchsia.bluetooth.gatt2;

	using fuchsia.bluetooth as bt;
	using zx;

	/// The amount of credits defined to be available for sending indications/notifications when a
	/// LocalService is first published.
	const INITIAL_VALUE_CHANGED_CREDITS uint32 = 10;

	/// The parameters used to signal a characteristic value change from a LocalService to a peer.
	type ValueChangedParameters = table {
	/// The handle of the characteristic value being signalled.
	/// Mandatory.
	1: handle Handle;
	/// The updated value of the characteristic.
	/// Note for clients using indications/notifications for high-throughput (not recommended):
	/// While statically constrained to `MAX_VALUE_LENGTH`, the real limit depends on the specific
	/// peer's configuration as notified by `LocalService.PeerUpdate`. Any bytes exceeding that
	/// limit are truncated internally by the stack.
	/// Mandatory.
	2: value bytes:MAX_VALUE_LENGTH;
	/// Only signal a subset of peers.
	/// If not present or empty, all peers that can be updated are signaled.
	/// If included, only the set of peers in this list will be signaled.
	/// Peers are only signaled if they have configured updates or notifications per `LocalService.`
	/// `CharacteristicConfiguration`; other peers in `peer_ids` will be ignored.
	3: peer_ids vector<bt.PeerId>:MAX;
	};

	/// Interface for serving a local GATT service. Closing the server_end of this protocol causes the
	/// GATT service to be removed from the local GATT database. Similarly, closure of the client_end
	/// of this protocol means the Bluetooth stack has removed this service from its GATT database.
	protocol LocalService {
	/// This notifies the current configuration of a particular characteristic/descriptor for a
	/// particular peer. It will be called when the peer GATT client changes the configuration.
	///
	/// The Bluetooth stack maintains the state of each peer's configuration across reconnections.
	/// As such, this method will also be called when a peer connects for each characteristic with
	/// the initial, persisted state of the newly-connected peer's configuration. However, clients
	/// should not rely on this state being persisted indefinitely by the Bluetooth stack.
	///
	/// + request `peer_id` The PeerId of the GATT client associated with this particular CCC.
	/// + request `handle` The handle of the characteristic associated with the `notify` and
	/// `indicate` parameters.
	/// + request `notify` True if the client has enabled notifications, false otherwise.
	/// + request `indicate` True if the client has enabled indications, false otherwise.
	/// - response empty Returns nothing to acknowledge the characteristic configuration.
	CharacteristicConfiguration(struct {
	peer_id bt.PeerId;
	handle Handle;
	notify bool;
	indicate bool;
	}) -> ();

	/// Called when a peer requests to read the value of a characteristic or descriptor. It is
	/// guaranteed that the peer satisfies the permssions associated with this attribute.
	///
	/// + request `peer_id` The PeerId of the GATT client making the read request.
	/// + request `handle` The handle of the requested descriptor/characteristic.
	/// + request `offset` The offset at which to start reading the requested value.
	/// - response `value` The value of the characteristic.
	/// * error See `gatt2.Error` documentation for possible errors.
	ReadValue(struct {
	peer_id bt.PeerId;
	handle Handle;
	offset int32;
	}) -> (struct {
	value bytes:MAX_VALUE_LENGTH;
	}) error Error;

	/// Called when a peer issues a request to write the value of a characteristic or descriptor. It
	/// is guaranteed that the peer satisfies the permissions associated with this attribute.
	///
	/// + request `peer_id` The PeerId of the GATT client making the write request. Always present.
	/// + request `handle` The handle of the requested descriptor/characteristic. Always present.
	/// + request `offset` The offset at which to start writing the value. If the offset is 0, any
	/// existing value should be overwritten by the new value. Otherwise, the existing value from
	/// offset:(offset + len(value)) should be changed to `value`. Always present.
	/// + request `value` The new value for the descriptor/characteristic. Always present, but may
	/// be the empty string.
	/// - response The implementation must send an empty response once the value has been updated
	/// as confirmation.
	/// * error See `gatt2.Error` documentation for possible errors.
	WriteValue(table {
	1: peer_id bt.PeerId;
	2: handle Handle;
	3: offset uint32;
	4: value bytes:MAX_VALUE_LENGTH;
	}) -> (struct {}) error Error;

	/// Called to provide GATT information specific to a peer. PeerUpdate will not be called unless
	/// the prior invocation received a response. As such, the implementation can simply ignore the
	/// first invocation if they are not interested in any PeerUpdate fields.
	///
	/// A PeerUpdate will be made before propagating any other interaction from the peer to the
	/// LocalService (Write/ReadValue, CharacteristicConfiguration) on a best-effort basis, as long
	/// as all preceding PeerUpdates were acknowledged.
	///
	/// + request `peer_id` The PeerId the update pertains to. Always present.
	/// + request `mtu` The maximum number of bytes that fit in a notification/indication to this
	/// peer. Any bytes past this limit are silently truncated. Most clients need not concern
	/// themselves with this unless they are using notifications/indications for high throughput.
	/// Optional.
	/// - response An empty response to acknowledge that the update was received.
	PeerUpdate(table {
	1: peer_id bt.PeerId;
	2: mtu uint16;
	}) -> ();

	/// After this event, new peers will no longer be able to discover the service, although peers
	/// which have already discovered this service may still access it. This should be sent once per
	/// service lifetime; sending more than once closes the protocol and disconnects GATT clients.
	@transitional("Not currently supported. Comment on fxbug.dev/98598 to request support")
	-> OnSuppressDiscovery();

	/// This event is used to send a notification to a peer. Notifications should be used instead of
	/// indications when the service does not require peer confirmation of the update.
	///
	/// Notifications should not be sent to peers which have not enabled notifications on a
	/// particular characteristic - if they are sent, they will not be propagated. The Bluetooth
	/// stack will track this configuration for the lifetime of the service.
	///
	/// LocalServices must keep track of available credit provided by the `ValueChangedCredit`
	/// method and send at most that many `OnNotifyValue` and `OnIndicateValue` events. If more
	/// events are sent than available credits, the protocol will be closed.
	-> OnNotifyValue(ValueChangedParameters);

	/// This event is used to send an indication to a peer. Indications should be used instead of
	/// notifications when the service does require peer confirmation of the update.
	///
	/// Indications should not be sent to peers which have not enabled indications on a particular
	/// characteristic - if they are sent, they will not be propagated. The Bluetooth stack will
	/// track this configuration for the lifetime of the service.
	///
	/// LocalServices must keep track of available credit provided by the `ValueChangedCredit`
	/// method and send at most that many `OnNotifyValue` and `OnIndicateValue` events. If more
	/// events are sent than available credits, the protocol will be closed.
	///
	/// + request `update` The parameters associated with the changed characteristic.
	/// + request `confirmation` When all peers that will be updated have confirmed the indication,
	/// `confirmation` is signalled with ZX_EVENTPAIR_SIGNALLED. `confirmation` will be closed if
	/// indicating any peer fails, such as if the peer hasn't configured indications, is not
	/// connected, or does not confirm within the ATT transaction timeout of 30 seconds (Bluetooth
	/// 5.3 Vol. 3 Part F 3.3.3). To track indication confirmation on a per-peer basis, the
	/// implementation can send this event with a single ID in `update.peer_ids`.
	// `confirmation` is an EventPair instead of an Event because the language bindings for Events
	// treat them as resources/move-only, but the LocalService will need to retain a handle to the
	// `confirmation` kernel object in order to wait on the signal from the other side.
	-> OnIndicateValue(resource struct {
	update ValueChangedParameters;
	confirmation zx.handle:EVENTPAIR;
	});

	/// Add credit for sending indications/notifications. Implementors are defined to start out with
	/// INITIAL_VALUE_CHANGED_CREDITS credits before this method is called. Implementors must keep
	/// track of the available credit they have. The implementor can send exactly one OnNotifyValue
	/// or OnIndicateValue event for each credit. Note that `ValueChangedCredit` will only be called
	/// if at least one indication/notification has been sent since the prior call.
	ValueChangedCredit(struct {
	additional_credit uint8;
	});
	};

	@discoverable
	protocol Server {
	/// Publishes the given `service` so that it is available to all remote peers. Upon publication,
	/// the service is defined to have INITIAL_VALUE_CHANGED_CREDITS credits available for sending
	/// indications/notifications.
	///
	/// The caller must assign distinct handles to the characteristics and descriptors listed in
	/// `info`. These identifiers will be used in requests sent to `service`.
	///
	/// + request `info` Defines the structure of the GATT service. Includes characteristics and
	/// descriptors that will be made available to peers, as well as the service handle, which is
	/// required to be unique across all services published to this Server.
	/// + request `service` Provides the implementation of the service per the documented behavior
	/// of a `LocalService`.
	/// - response An empty response indicates the service was successfully published.
	/// * error See `gatt2.PublishServiceError` for possible failure modes.
	@transitional("Implementation and migration progress tracked in http://fxbug.dev/36375")
	PublishService(resource struct {
	info ServiceInfo;
	service client_end:LocalService;
	}) -> (struct {}) error PublishServiceError;
	};