From 16c4cd05a98e9ae4849e13d8509f2cc63841ce91 Mon Sep 17 00:00:00 2001 From: George Kiagiadakis Date: Wed, 3 Jul 2024 20:03:02 +0300 Subject: [PATCH] bluez5: initial telephony service API documentation --- spa/plugins/bluez5/README-Telephony.md | 235 +++++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 spa/plugins/bluez5/README-Telephony.md diff --git a/spa/plugins/bluez5/README-Telephony.md b/spa/plugins/bluez5/README-Telephony.md new file mode 100644 index 000000000..d7fa14c58 --- /dev/null +++ b/spa/plugins/bluez5/README-Telephony.md @@ -0,0 +1,235 @@ +# PipeWire Bluetooth Telephony service + +The Telephony service is a D-Bus user session service that allows applications +to communicate with the HFP native backend in order to control phone calls. +Phone call features are a core part of the HFP specification and are available +when a mobile phone is paired (therefore, PipeWire acts as the Hands-Free and +the phone is the Audio Gateway). + +The service is exposed on the session bus and registered under the well-known +name "org.freedesktop.PipeWire.Telephony". + +## Manager Object + +``` +Service org.freedesktop.PipeWire.Telephony +Object path /org/freedesktop/PipeWire/Telephony +Implements org.freedesktop.DBus.Introspectable + org.freedesktop.DBus.ObjectManager +``` + +The manager object is always available and allows applications to get access to +the connected audio gateways. + +AudioGateway objects are announced via the standard DBus ObjectManager interface. + +## AudioGateway Interface + +``` +Service org.freedesktop.PipeWire.Telephony +Interface org.freedesktop.PipeWire.Telephony.AudioGateway1 +Requires org.freedesktop.DBus.Introspectable + org.freedesktop.DBus.ObjectManager +Object path /org/freedesktop/PipeWire/Telephony/{ag0,ag1,...} +``` + +Audio gateway objects represent the currently connected AG devices (typically +mobile phones) and should implement the `org.freedesktop.PipeWire.Telephony.AudioGateway1` +interface as well the standard `org.freedesktop.DBus.Introspectable`, +`org.freedesktop.DBus.Properties` and `org.freedesktop.DBus.ObjectManager` +interfaces. + +Call objects are announced via the standard DBus ObjectManager interface. + +### Methods + +`object Dial(string number)` + +Initiates a new outgoing call. Returns the object path to the newly created +call. + +The number must be a string containing the following characters: +`[0-9+*#,ABCD]{1,80}` In other words, it must be a non-empty string consisting +of 1 to 80 characters. The character set can contain numbers, `+`, `*`, `#`, `,` +and the letters `A` to `D`. Besides this sanity checking no further number +validation is performed. It is assumed that the gateway and/or the network will +perform further validation. + +NOTE: If an active call (single or multiparty) exists, then it is automatically +put on hold if the dial procedure is successful. + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.InvalidArgs + * org.freedesktop.DBus.Error.Failed + +`void SwapCalls()` + +Swaps Active and Held calls. The effect of this is that all calls (0 or more +including calls in a multi-party conversation) that were Active are now Held, +and all calls (0 or more) that were Held are now Active. + +GSM specification does not allow calls to be swapped in the case where Held, +Active and Waiting calls exist. Some modems implement this anyway, thus it is +manufacturer specific whether this method will succeed in the case of Held, +Active and Waiting calls. + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.Failed + +`void ReleaseAndAnswer()` + +Releases currently active call (0 or more) and answers the currently waiting +call. Please note that if the current call is a multiparty call, then all +parties in the multi-party call will be released. + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.Failed + +`void ReleaseAndSwap()` + +Releases currently active call (0 or more) and activates any currently held +calls. Please note that if the current call is a multiparty call, then all +parties in the multi-party call will be released. + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.Failed + +`void HoldAndAnswer()` + +Puts the current call (including multi-party calls) on hold and answers the +currently waiting call. Calling this function when a user already has a both +Active and Held calls is invalid, since in GSM a user can have only a single +Held call at a time. + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.Failed + +`void HangupAll()` + +Releases all calls except waiting calls. This includes multiparty calls. + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.Failed + +`array{object} CreateMultiparty()` + +Joins active and held calls together into a multi-party call. If one of the +calls is already a multi-party call, then the other call is added to the +multiparty conversation. Returns the new list of calls participating in the +multiparty call. + +There can only be one subscriber controlled multi-party call according to the +GSM specification. + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.Failed + +`void SendTones(string tones)` + +Sends the DTMF tones to the network. The tones have a fixed duration. Tones +can be one of: '0' - '9', '*', '#', 'A', 'B', 'C', 'D'. The last four are +typically not used in normal circumstances. + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.InvalidArgs + * org.freedesktop.DBus.Error.Failed + + +## Call Interface + +``` +Service org.freedesktop.PipeWire.Telephony +Interface org.freedesktop.PipeWire.Telephony.Call1 +Requires org.freedesktop.DBus.Introspectable + org.freedesktop.DBus.Properties +Object path /org/freedesktop/PipeWire/Telephony/{ag0,ag1,...}/{call0,call1,...} +``` + +Call objects represent active calls and allows managing them. + +### Methods + +`void Answer()` + +Answers an incoming call. Only valid if the state of the call is "incoming". + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.Failed + +`void Hangup()` + +Hangs up the call. + +For an incoming call, the call is hung up using ATH or equivalent. For a +waiting call, the remote party is notified by using the User Determined User +Busy (UDUB) condition. This is generally implemented using CHLD=0. + +Please note that the GSM specification does not allow the release of a held call +when a waiting call exists. This is because 27.007 allows CHLD=1X to operate +only on active calls. Hence a held call cannot be hung up without affecting the +state of the incoming call (e.g. using other CHLD alternatives). Most +manufacturers provide vendor extensions that do allow the state of the held call +to be modified using CHLD=1X or equivalent. It should be noted that Bluetooth +HFP specifies the classic 27.007 behavior and does not allow CHLD=1X to modify +the state of held calls. + +Based on the discussion above, it should also be noted that releasing a +particular party of a held multiparty call might not be possible on some +implementations. It is recommended for the applications to structure their UI +accordingly. + +NOTE: Releasing active calls does not produce side-effects. That is the state +of held or waiting calls is not affected. As an exception, in the case where a +single active call and a waiting call are present, releasing the active call +will result in the waiting call transitioning to the 'incoming' state. + +Possible Errors: + * org.freedesktop.PipeWire.Telephony.Error.InvalidState + * org.freedesktop.DBus.Error.Failed + +### Properties + +`string LineIdentification [readonly]` + +Contains the Line Identification information returned by the network, if +present. For incoming calls this is effectively the CLIP. For outgoing calls +this attribute will hold the dialed number, or the COLP if received by the +audio gateway. + +`string IncomingLine [readonly, optional]` + +Contains the Called Line Identification information returned by the network. +This is only available for incoming calls and indicates the local subscriber +number which was dialed by the remote party. This is useful for subscribers +which have a multiple line service with their network provider and would like to +know what line the call is coming in on. + +`string Name [readonly]` + +Contains the Name Identification information returned by the network, if +present. + +`boolean Multiparty [readonly]` + +Contains the indication if the call is part of a multiparty call or not. + +`string State [readonly]` + +Contains the state of the current call. The state can be one of: + - "active" - The call is active + - "held" - The call is on hold + - "dialing" - The call is being dialed + - "alerting" - The remote party is being alerted + - "incoming" - Incoming call in progress + - "waiting" - Call is waiting + - "disconnected" - No further use of this object is allowed, it will be + destroyed shortly