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;

 /// Parameters for the LocalService.WriteValue method
 type WriteValueParameters = table {
     /// The PeerId of the GATT client making the write request.
     /// Always present.
     1: peer_id bt.PeerId;
     /// The handle of the requested descriptor/characteristic.
     /// Always present.
     2: handle Handle;
     /// The offset at which to start writing the requested value. If the offset is 0, any existing
     /// value should be overwritten by the new value. Otherwise, the existing value between
     /// offset:(offset + len(value)) should be changed to `value`.
     /// Always present.
     3: offset uint32;
     /// The new value for the descriptor/characteristic.
     /// Always present. May be the empty string.
     4: value bytes:MAX_VALUE_LENGTH;
 };

 /// The parameters used to signal a characteristic value change from a LocalService to a peer.
 type ValueChangedParameters = table {
     /// The PeerIds of the peers to signal. The LocalService should respect the Characteristic
     /// Configuration associated with a peer+handle when deciding whether to signal it.
     /// If empty/not present, all peers are signalled.
     1: peer_ids vector<bt.PeerId>:MAX;
     /// The handle of the characteristic value being signalled.
     /// Mandatory.
     2: handle Handle;
     /// The updated value of the characteristic.
     /// Mandatory.
     3: value bytes:MAX_VALUE_LENGTH;
 };

 /// Interface for serving a local GATT service.
 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 `params` The parameters of the write.
     /// - response  The implementation must send an empty response once the value has been updated
     ///   as confirmation.
     /// * error See `gatt2.Error` documentation for possible errors.
     // TODO(fxbug.dev/92757): Once table payloads are available, consider whether we could use an
     // anonymous table here instead of a table within a struct.
     WriteValue(struct {
         params WriteValueParameters;
     }) -> (struct {}) error Error;

     /// After this event, new peers will no longer be able to discover the service, although open
     /// connections to existing peer GATT clients will not be closed. This should be sent once per
     /// service lifetime; sending more than once will close the protocol.
     -> OnSupressDiscovery();

     /// 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.
     // TODO(fxbug.dev/92757): Once named payload layouts and table payloads are available, consider
     // whether this can be simply -> OnNotifyValue(ValueChangedParameters)
     -> OnNotifyValue(struct {
         update 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.
     ///
     /// If any of the peers in `update.peer_ids` fails to confirm the indication within the ATT
     /// transaction timeout (30 seconds per Bluetooth 5.2 Vol. 4 Part G 3.3.3), the link between
     /// the peer and the local adapter will be closed.
     ///
     /// + request `update` The parameters associated with the changed characteristic.
     /// + request `confirmation` When all the peers listed in `update.peer_ids` have confirmed
     ///   the indication, `confirmation` is signalled with ZX_USER_SIGNAL_0. If the implementation
     ///   wishes to receive indication confirmations on a per-peer basis, they should send this
     ///   event with a single PeerId 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 and notifications.  Implementors must keep track of the
     /// available credit they have.  For each credit the implementor can send exactly one
     /// OnNotifyValue or OnIndicateValue event.
     ValueChangedCredit(struct {
         additional_credit uint8;
     });
 };

 @discoverable
 protocol Server {
     /// Publishes the given `service` so that it is available to all remote peers.
     ///
     /// 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, including characteristics and
     ///   descriptors that will be made available to peers.
     /// + request `service` Provides the implementation of the service per the documented behavior
     ///   of a `LocalService`.
     /// - response empty Returns nothing upon successful service publication.
     /// * error See `gatt2.PublishServiceError` for possible failure modes.
     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;

	/// Parameters for the LocalService.WriteValue method
	type WriteValueParameters = table {
	/// The PeerId of the GATT client making the write request.
	/// Always present.
	1: peer_id bt.PeerId;
	/// The handle of the requested descriptor/characteristic.
	/// Always present.
	2: handle Handle;
	/// The offset at which to start writing the requested value. If the offset is 0, any existing
	/// value should be overwritten by the new value. Otherwise, the existing value between
	/// offset:(offset + len(value)) should be changed to `value`.
	/// Always present.
	3: offset uint32;
	/// The new value for the descriptor/characteristic.
	/// Always present. May be the empty string.
	4: value bytes:MAX_VALUE_LENGTH;
	};

	/// The parameters used to signal a characteristic value change from a LocalService to a peer.
	type ValueChangedParameters = table {
	/// The PeerIds of the peers to signal. The LocalService should respect the Characteristic
	/// Configuration associated with a peer+handle when deciding whether to signal it.
	/// If empty/not present, all peers are signalled.
	1: peer_ids vector<bt.PeerId>:MAX;
	/// The handle of the characteristic value being signalled.
	/// Mandatory.
	2: handle Handle;
	/// The updated value of the characteristic.
	/// Mandatory.
	3: value bytes:MAX_VALUE_LENGTH;
	};

	/// Interface for serving a local GATT service.
	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 `params` The parameters of the write.
	/// - response The implementation must send an empty response once the value has been updated
	/// as confirmation.
	/// * error See `gatt2.Error` documentation for possible errors.
	// TODO(fxbug.dev/92757): Once table payloads are available, consider whether we could use an
	// anonymous table here instead of a table within a struct.
	WriteValue(struct {
	params WriteValueParameters;
	}) -> (struct {}) error Error;

	/// After this event, new peers will no longer be able to discover the service, although open
	/// connections to existing peer GATT clients will not be closed. This should be sent once per
	/// service lifetime; sending more than once will close the protocol.
	-> OnSupressDiscovery();

	/// 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.
	// TODO(fxbug.dev/92757): Once named payload layouts and table payloads are available, consider
	// whether this can be simply -> OnNotifyValue(ValueChangedParameters)
	-> OnNotifyValue(struct {
	update 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.
	///
	/// If any of the peers in `update.peer_ids` fails to confirm the indication within the ATT
	/// transaction timeout (30 seconds per Bluetooth 5.2 Vol. 4 Part G 3.3.3), the link between
	/// the peer and the local adapter will be closed.
	///
	/// + request `update` The parameters associated with the changed characteristic.
	/// + request `confirmation` When all the peers listed in `update.peer_ids` have confirmed
	/// the indication, `confirmation` is signalled with ZX_USER_SIGNAL_0. If the implementation
	/// wishes to receive indication confirmations on a per-peer basis, they should send this
	/// event with a single PeerId 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 and notifications. Implementors must keep track of the
	/// available credit they have. For each credit the implementor can send exactly one
	/// OnNotifyValue or OnIndicateValue event.
	ValueChangedCredit(struct {
	additional_credit uint8;
	});
	};

	@discoverable
	protocol Server {
	/// Publishes the given `service` so that it is available to all remote peers.
	///
	/// 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, including characteristics and
	/// descriptors that will be made available to peers.
	/// + request `service` Provides the implementation of the service per the documented behavior
	/// of a `LocalService`.
	/// - response empty Returns nothing upon successful service publication.
	/// * error See `gatt2.PublishServiceError` for possible failure modes.
	PublishService(resource struct {
	info ServiceInfo;
	service client_end:LocalService;
	}) -> (struct {}) error PublishServiceError;
	};