blob: cc8f73e977077cafec53f4814fbb1f0460bad722 [file] [log] [blame]
// 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 MAX_PICONET_SIZE uint64 = 8;
/// Represents the action of redialing the last dialed number.
type RedialLast = struct {};
/// Represents the action of transferring an active call to the Headset.
type TransferActive = struct {};
/// Represents the signal strength of a connection between the Audio Gateway and
/// a network.
type SignalStrength = strict enum : 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.
type NetworkInformation = table {
/// Report the status of registration with the network. See HFP v1.8,
/// Section 4.4
1: service_available bool;
/// Report the signal strength of the connection to the network. See
/// the HFP v1.8, Section 4.5.
2: signal_strength SignalStrength;
/// Report the roaming status of the connection to the network. See
/// HFP v1.8, Section 4.6
3: roaming bool;
};
/// A command from the HF with a value representing what number to dial.
type CallAction = strict union {
/// A complete number to be dialed by the call handler service. See HFP v1.8
/// Section 4.18.
1: dial_from_number 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: dial_from_location Memory;
/// The call handler service should dial the last used number. See HFP v1.8
/// Section 4.20.
3: redial_last RedialLast;
/// 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: transfer_active TransferActive;
};
/// Represents a text string of V.250 dialing digits.
/// See TS 127.007v06.08.00, Section 6.2 for more information.
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.
///
/// A call manager can be unregistered by closing either end of the channel.
Register(resource struct {
manager client_end:CallManager;
});
};
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(resource struct {
id bt.PeerId;
handle server_end:PeerHandler;
}) -> ();
};
/// The Call Manager 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 manager _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() -> (struct {
update NetworkInformation;
});
/// Hanging get which returns when a new call Client is initiated by the
/// call manager or an ongoing call is transferred to the headset.
/// `RequestOutgoingCall` can be called before or after `WatchNextCall`.
WatchNextCall() -> (resource struct {
call NextCall;
});
/// Used to request an outgoing call be initiated by the call manager.
/// `RequestOutgoingCall` shall complete after the outgoing call has been
/// initiated and the corresponding `Call` protocol has been returned via a
/// `WatchNextCall` result.
///
/// An error is returned if the call could not be placed as requested.
/// ZX_ERR_NOT_SUPPORTED can be used if the system does not support
/// the requested action.
/// ZX_ERR_ALREADY_EXISTS can be used if there is already a call in progress
/// and the system does not support additional calls.
RequestOutgoingCall(struct {
action CallAction;
}) -> (struct {}) error zx.status;
/// Request the name of the network operator for the call manager. A null
/// value is returned if there is no operator name available.
QueryOperator() -> (struct {
operator string:<16, optional>;
});
/// 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() -> (struct {
numbers vector<Number>:128;
});
/// 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(struct {
enabled bool;
}) -> (struct {}) error zx.status;
/// Headset battery level from 0 ~ 100
/// See https://www.bluetooth.com/specifications/assigned-numbers/hands-free-profile/
ReportHeadsetBatteryLevel(struct {
level uint8;
});
/// 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(resource struct {
control client_end:HeadsetGain;
});
};
/// 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(struct {
requested uint8;
});
/// 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() -> (struct {
gain uint8;
});
/// 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(struct {
requested uint8;
});
/// 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() -> (struct {
gain uint8;
});
};
/// Represents the valid states of a call.
type CallState = flexible enum {
/// 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;
};
/// The direction of call initiation.
type CallDirection = strict enum {
/// Call originated on this device. This is also known as an Outgoing call.
MOBILE_ORIGINATED = 1;
/// Call is terminated on this device. This is also known as an Incoming call.
MOBILE_TERMINATED = 2;
};
/// Information for the next call reported by a Peer Handler.
type NextCall = resource table {
/// Channel for this call.
/// This field is required.
1: call client_end:Call;
/// The Number of the remote party on the call.
/// This field is required.
2: remote Number;
/// State of the call when it is reported by the Peer Handler.
/// This field is required.
3: state CallState;
/// Direction of the call's initiation. See `CallDirection` documentation
/// for more information.
/// This field is required.
4: direction CallDirection;
};
/// Dual-tone multi-frequency signaling codes.
type DtmfCode = strict enum : uint8 {
/// Represented by ASCII "1" in AT commands.
ONE = 49;
/// Represented by ASCII "2" in AT commands.
TWO = 50;
/// Represented by ASCII "3" in AT commands.
THREE = 51;
/// Represented by ASCII "4" in AT commands.
FOUR = 52;
/// Represented by ASCII "5" in AT commands.
FIVE = 53;
/// Represented by ASCII "6" in AT commands.
SIX = 54;
/// Represented by ASCII "7" in AT commands.
SEVEN = 55;
/// Represented by ASCII "8" in AT commands.
EIGHT = 56;
/// Represented by ASCII "9" in AT commands.
NINE = 57;
/// Represented by ASCII "#" in AT commands.
NUMBER_SIGN = 35;
/// Represented by ASCII "0" in AT commands.
ZERO = 48;
/// Represented by ASCII "*" in AT commands.
ASTERISK = 42;
/// Represented by ASCII "A" in AT commands.
A = 65;
/// Represented by ASCII "B" in AT commands.
B = 66;
/// Represented by ASCII "C" in AT commands.
C = 67;
/// Represented by ASCII "D" in AT commands.
D = 68;
};
/// 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() -> (struct {
state CallState;
});
/// 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 manager 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 manager failed to transmit the code to
/// the network.
SendDtmfCode(struct {
code DtmfCode;
}) -> (struct {}) error zx.status;
};