mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-11-02 09:01:50 -05:00
bluez5: initial telephony service API documentation
This commit is contained in:
George Kiagiadakis
Wim Taymans
parent
23c797136a
commit
16c4cd05a9
1 changed files with 235 additions and 0 deletions
235
spa/plugins/bluez5/README-Telephony.md
Normal file
235
spa/plugins/bluez5/README-Telephony.md
Normal file
|
|
@ -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
|
||||||
Loading…
Add table
Add a link
Reference in a new issue