| // Copyright 2020 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.hfp; |
| |
| using fuchsia.bluetooth as bt; |
| using zx; |
| |
| const uint64 MAX_PICONET_SIZE = 8; |
| |
| /// Represents the action of redialing the last dialed number. |
| struct RedialLast { |
| }; |
| |
| /// Represents the action of transferring an active call to the Headset. |
| struct TransferActive { |
| }; |
| |
| /// Represents the signal strength of a connection between the Audio Gateway and |
| /// a network. |
| enum SignalStrength : int8 { |
| NONE = 1; |
| VERY_LOW = 2; |
| LOW = 3; |
| MEDIUM = 4; |
| HIGH = 5; |
| VERY_HIGH = 6; |
| }; |
| |
| /// Network information for the Audio Gateway. Typically this represents |
| /// information regarding the state of connectivity to a telephony network. |
| table NetworkInformation { |
| /// Report the status of registration with the network. See HFP v1.8, |
| /// Section 4.4 |
| 1: bool service_available; |
| /// Report the signal strength of the connection to the network. See |
| /// the HFP v1.8, Section 4.5. |
| 2: SignalStrength signal_strength; |
| /// Report the roaming status of the connection to the network. See |
| /// HFP v1.8, Section 4.6 |
| 3: bool roaming; |
| }; |
| |
| /// A command from the HF with a value representing what number to dial. |
| strict union CallAction { |
| /// A complete number to be dialed by the call handler service. See HFP v1.8 |
| /// Section 4.18. |
| 1: Number dial_from_number; |
| /// A phone book memory location from which a number to be dialed should be |
| /// looked up. See HFP v1.8 Section 4.19. |
| 2: Memory dial_from_location; |
| /// The call handler service should dial the last used number. See HFP v1.8 |
| /// Section 4.20. |
| 3: RedialLast redial_last; |
| /// Request to transfer an active call to the headset rather than initiating |
| /// a new outgoing call. A call must already be in progress on the Audio |
| /// Gateway in order for a transfer of audio to the Handsfree device to take |
| /// place. See HFP v1.8 Section 4.16. |
| 4: TransferActive transfer_active; |
| }; |
| |
| /// Represents a Binary-Coded Decimal (BCD) Number as specified in TS 124.008 |
| /// 10.5.4.7 |
| alias Number = string:256; |
| |
| /// Represents a specific phone book memory location |
| alias Memory = string:256; |
| |
| [Discoverable] |
| protocol Hfp { |
| /// Register as the call manager for this device. |
| /// |
| /// There can only be one call manager registered at a time. If one is |
| /// registered at the time a call to `Register` is made, the newer |
| /// CallManager channel will be closed. |
| Register(CallManager manager); |
| }; |
| |
| protocol CallManager { |
| /// Signal that a peer that supports the HFP Hands-Free role is connected. |
| /// |
| /// `id` is the unique identifier associated with the peer. |
| /// `handle` is the channel that the call manager should use to manage |
| /// a the peer. If the call manager does not intend to handle a given peer, |
| /// it must close the handle with a `ZX_ERR_UNAVAILABLE` epitaph. |
| /// |
| /// Multiple concurrent PeerConnected requests can be made by the client. |
| /// The empty response is used as a flow control mechanism to allow the |
| /// client to limit the number of pending PeerConnected requests. |
| PeerConnected(bt.PeerId id, request<PeerHandler> handle) -> (); |
| }; |
| |
| /// The Call Service will serve a call handler protocol for each connected |
| /// headset that it chooses to manage calls through. |
| /// |
| /// If the peer handler is closed by either channel endpoint, all protocols |
| /// associated with this peer handler are closed. This includes any Call, |
| /// and HeadsetGain protocols. Channels closed by a server end will include an |
| /// epitaph `ZX_ERR_HANDLE_CLOSED` in this situation. |
| protocol PeerHandler { |
| /// Hanging get to provide the Hfp service with an `update` on the |
| /// `NetworkInformation`. Any fields in `update` that are not present will |
| /// be treated as unmodified by the update. |
| /// |
| /// The call service _should_ provide a fully populated `update` when it is |
| /// called for the first time. |
| /// |
| /// The most up-to-date `NetworkInformation` is used during the connection |
| /// initialization process of the peer, and updates are propagated to the |
| /// peer if it supports AG Indicators. |
| WatchNetworkInformation() -> (NetworkInformation update); |
| |
| /// Hanging get which returns when a new call is initiated by the call |
| /// service or an ongoing call is transferred to the headset. |
| /// WaitForCall returns a `Call` client end rather than passing in |
| /// a `request<Call>` server end so that `InitiateOutgoingCall` can be |
| /// called before or after `WaitForCall`. |
| /// `remote` is returned to identify the remote party by Number. |
| /// `state` is returned so that the Hands Free device can be notified |
| /// immediately without waiting for another FIDL response. |
| WaitForCall() -> (Call call, Number remote, CallState state); |
| |
| /// Used to request an outgoing call be initiated by the call service. |
| /// `InitiateOutgoingCall` will complete after the outgoing call has been |
| /// initiated and the corrisponding `Call` protocol has been provided to the |
| /// client via the `WaitForCall` hanging get. |
| /// An error is returned if the call could not be placed as requested. |
| InitiateOutgoingCall(CallAction action) -> () error zx.status; |
| |
| /// Request the name of the network operator for the call service. A null |
| /// value is returned if there is no operator name available. |
| QueryOperator() -> (string:16? operator); |
| |
| /// Request subscriber numbers from the call manager. There can be zero |
| /// or more numbers returned. Sending more than 128 numbers is not supported |
| /// at this time. |
| // The length of `numbers` is constrained to keep the message size below |
| // the maximum channel message size of 64KiB. |
| SubscriberNumberInformation() -> (vector<Number>:128 numbers); |
| |
| /// Request by the HF to enable or disable the Noise Reduction/Echo Cancellation |
| /// functionality on the AG based on the `enabled` boolean. |
| /// A `ZX_ERR_NOT_SUPPORTED` error is returned if Noice Reduction/Echo |
| /// Cancellation is not supported by the device. |
| SetNrecMode(bool enabled) -> () error zx.status; |
| |
| /// Headset battery level from 0 ~ 100 |
| /// See https://www.bluetooth.com/specifications/assigned-numbers/hands-free-profile/ |
| ReportHeadsetBatteryLevel(uint8 level); |
| |
| /// Tear off protocol for Headset Gain. |
| /// |
| /// Only one HeadsetGain protocol can be active for a PeerHandler protocol |
| /// at any given time. Older HeadsetGain protocols are given preference. If |
| /// a HeadsetGain protocol is active when a new GainControl request is made, |
| /// the new HeadsetGain protocol will be closed immediately. |
| GainControl(HeadsetGain control); |
| }; |
| |
| /// Control Headset Speaker and Microphone gain and receive reports of current |
| /// values as specified in HFP v1.8, Section 4.29. This protocol is served by the |
| /// Hfp service. |
| /// |
| /// Gain is represented as an absolute value on a scale from 0 to 15. 0 is the |
| /// minimum gain and 15 is the maximum gain. It is related to a particular |
| /// (implementation dependent) volume level controlled by the Headset. |
| /// |
| /// |
| /// Epitaphs: |
| /// |
| /// This channel will be closed with a `ZX_ERR_ALREADY_BOUND` epitaph if there |
| /// is already an active `HeadsetGain` channel. |
| /// |
| /// This channel will be closed with a `ZX_ERR_NOT_SUPPORTED` epitaph if the Hfp |
| /// service is not configured to support remote volume control or the peer |
| /// headset does not support remote volume control. If the channel is closed |
| /// with this error, the client should not attempt to reopen it using the |
| /// `PeerHandler::GainControl` request on the same PeerHandler connection. |
| /// |
| /// This channel will be closed with a `ZX_ERR_INVALID_ARGUMENT` epitaph if |
| /// invalid arguments are passed to requests. See documentation on specific |
| /// requests for more details. |
| protocol HeadsetGain { |
| /// Make a request to the headset to set the speaker gain to `requested`. |
| /// |
| /// `requested` must be in the range [0-15] inclusive. Any values outside of |
| /// this range will result in the channel closing with a |
| /// `ZX_ERR_INVALID_ARGUMENT` epitaph. |
| SetSpeakerGain(uint8 requested); |
| |
| /// Hanging get to watch for updates to the headset speaker gain. Responses |
| /// represent the current gain value that is set. |
| /// |
| /// The returned `gain` value will always be in the range [0-15] inclusive. |
| WatchSpeakerGain() -> (uint8 gain); |
| |
| /// Make a request to the Headset to set the microphone gain to `requested`. |
| /// |
| /// `requested` must be in the range [0-15] inclusive. Any values outside of |
| /// this range will result in the channel closing with a |
| /// `ZX_ERR_INVALID_ARGUMENT` epitaph. |
| SetMicrophoneGain(uint8 requested); |
| |
| /// Hanging get to watch for updates to the headset microphone gain. Responses |
| /// represent the current gain value that is set. |
| /// |
| /// The returned `gain` value will always be in the range [0-15] inclusive. |
| WatchMicrophoneGain() -> (uint8 gain); |
| }; |
| |
| /// Represents the valid states of a call. |
| enum CallState { |
| /// There is a callsetup procedure in progress for an outgoing call. |
| /// This state should not be set by the Call protocol client. |
| /// It is the initial state of an unanswered outgoing call. |
| OUTGOING_DIALING = 1; |
| /// There is a callsetup procedure in progress for an outgoing call and the |
| /// remote party has been alerted to the callsetup. This state is an |
| /// optional transition from OUTGOING_DIALING. |
| OUTGOING_ALERTING = 2; |
| /// There is a callsetup procedure in progress for an incoming call. |
| INCOMING_RINGING = 3; |
| /// There is a callsetup procedure in progress for an incoming call. |
| INCOMING_WAITING = 4; |
| /// A call is in progress but another call is active. |
| ONGOING_HELD = 5; |
| /// A call is active. |
| ONGOING_ACTIVE = 6; |
| /// The call has been termianted. |
| TERMINATED = 7; |
| /// The call has been transferred to the AG, after which the HF is no longer |
| /// tracking its state. |
| TRANSFERRED_TO_AG = 8; |
| }; |
| |
| /// Dual-tone multi-frequency signaling codes. |
| enum DtmfCode : uint32 { |
| /// Represented by ASCII "1" in AT commands. |
| ONE = 1; |
| /// Represented by ASCII "2" in AT commands. |
| TWO = 2; |
| /// Represented by ASCII "3" in AT commands. |
| THREE = 3; |
| /// Represented by ASCII "4" in AT commands. |
| FOUR = 4; |
| /// Represented by ASCII "5" in AT commands. |
| FIVE = 5; |
| /// Represented by ASCII "6" in AT commands. |
| SIX = 6; |
| /// Represented by ASCII "7" in AT commands. |
| SEVEN = 7; |
| /// Represented by ASCII "8" in AT commands. |
| EIGHT = 8; |
| /// Represented by ASCII "9" in AT commands. |
| NINE = 9; |
| /// Represented by ASCII "#" in AT commands. |
| NUMBER_SIGN = 10; |
| /// Represented by ASCII "0" in AT commands. |
| ZERO = 11; |
| /// Represented by ASCII "*" in AT commands. |
| ASTERISK = 12; |
| /// Represented by ASCII "A" in AT commands. |
| A = 13; |
| /// Represented by ASCII "B" in AT commands. |
| B = 14; |
| /// Represented by ASCII "C" in AT commands. |
| C = 15; |
| /// Represented by ASCII "D" in AT commands. |
| D = 16; |
| }; |
| |
| /// Controls the lifecycle of a call that has been routed through a headset. |
| protocol Call { |
| /// A hanging get method for call state. See the `CallState` documentation |
| /// for information on possible states. |
| WatchState() -> (CallState state); |
| |
| /// Request that the Call be set to the ONGOING_HELD CallState |
| RequestHold(); |
| |
| /// Request that the Call be set to the ONGOING_ACTIVE CallState. |
| /// This has the side effect of placing all other Calls that are routed to |
| /// this peer in the ONGOING_HELD call state if it succeeds. |
| RequestActive(); |
| |
| /// Request that the Call be TERMINATED. |
| RequestTerminate(); |
| |
| /// Request that the Call's audio be transfered to the Audio Gateway and |
| /// the call state set to TRANSFERRED_TO_AG. |
| RequestTransferAudio(); |
| |
| /// Send a code that the call service should transmit to its network |
| /// connection. The request returns after the code has been transmitted to |
| /// the network. |
| /// |
| /// Can return an error if the call service failed to transmit the code to |
| /// the network. |
| SendDtmfCode(DtmfCode code) -> () error zx.status; |
| }; |