mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-10-31 22:25:38 -04: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