mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2026-03-07 04:34:07 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

bluez5: README-Telephony: document ofono service compatibility

Browse source
This commit is contained in:
George Kiagiadakis 2024-09-11 12:28:35 +03:00 • committed by Wim Taymans
parent 613021137c
commit e02eedb5a7
1 changed files with 133 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

156
spa/plugins/bluez5/README-Telephony.md
View file

@ -1,48 +1,107 @@
# PipeWire Bluetooth Telephony service # PipeWire Bluetooth Telephony service
The Telephony service is a D-Bus user session service that allows applications The Telephony service is a D-Bus service that allows applications to communicate
to communicate with the HFP native backend in order to control phone calls. with the HFP native backend in order to control phone calls. Phone call features
Phone call features are a core part of the HFP specification and are available are a core part of the HFP specification and are available when a mobile phone
when a mobile phone is paired (therefore, PipeWire acts as the Hands-Free and is paired (therefore, PipeWire acts as the Hands-Free and the phone is the Audio
the phone is the Audio Gateway). Gateway).
The service is exposed on the session bus and registered under the well-known The service is exposed on the user session bus by default, but there is an
name "org.freedesktop.PipeWire.Telephony". option to make it available on the system bus instead.
The service implements its own interfaces alongside the standard DBus
Introspectable, ObjectManager and Properties interfaces, where needed.
These interfaces are mostly compatible with the ofono Manager, VoiceCallManager
and VoiceCall interfaces. For compatibility, the `org.ofono.Manager`,
`org.ofono.VoiceCallManager` and `org.ofono.VoiceCall` are also implemented
with any additional compatibility methods & signals are necessary to allow
ofono-based applications to be able to work just by modifying the service name,
the manager object path and the operating bus (session vs system).
In addition, to the compatibility interfaces, there is a runtime option to
also register the service as `org.ofono` on the system bus, making it a drop-in
replacement for ofono. Note, however, that this service is not a full replacement,
but only for the Bluetooth-based voice calls.
## Manager Object ## Manager Object
``` ```
Service org.freedesktop.PipeWire.Telephony Service org.freedesktop.PipeWire.Telephony
or org.ofono
Object path /org/freedesktop/PipeWire/Telephony Object path /org/freedesktop/PipeWire/Telephony
Implements org.freedesktop.DBus.Introspectable or /
Implements org.ofono.Manager
org.freedesktop.DBus.Introspectable
org.freedesktop.DBus.ObjectManager org.freedesktop.DBus.ObjectManager
``` ```
The manager object is always available and allows applications to get access to The manager object is always available and allows applications to get access to
the connected audio gateways. the connected audio gateways.
AudioGateway objects are announced via the standard DBus ObjectManager interface. The object path is set to `/` when ofono service compatibility is enabled,
in which case the service name `org.ofono` is also registered instead of
`org.freedesktop.PipeWire.Telephony`.
## AudioGateway Interface The methods and signals below are made available on the `org.ofono.Manager`
interface, for compatibility. AudioGateway objects are normally announced via
the standard DBus ObjectManager interface.
### Methods
`array{object,dict} GetModems()`
Get an array of AudioGateway objects and properties that represents the
currently connected audio gateways.
### Signals
`ModemAdded(object path, dict properties)`
Signal that is sent when a new audio gateway is added. It contains the object
path of the new audio gateway and also its properties.
`ModemRemoved(object path)`
Signal that is sent when an audio gateway has been removed. The object path is
no longer accessible after this signal and only emitted for reference.
## AudioGateway Object
``` ```
Service org.freedesktop.PipeWire.Telephony Service org.freedesktop.PipeWire.Telephony
Interface org.freedesktop.PipeWire.Telephony.AudioGateway1 or org.ofono
Requires org.freedesktop.DBus.Introspectable
org.freedesktop.DBus.ObjectManager
Object path /org/freedesktop/PipeWire/Telephony/{ag0,ag1,...} Object path /org/freedesktop/PipeWire/Telephony/{ag0,ag1,...}
Implements org.freedesktop.PipeWire.Telephony.AudioGateway1
org.ofono.VoiceCallManager
org.freedesktop.DBus.Introspectable
org.freedesktop.DBus.ObjectManager
``` ```
Audio gateway objects represent the currently connected AG devices (typically Audio gateway objects represent the currently connected AG devices (typically
mobile phones) and should implement the `org.freedesktop.PipeWire.Telephony.AudioGateway1` mobile phones).
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. The methods, signals and properties listed below are made available on both
`org.freedesktop.PipeWire.Telephony.AudioGateway1` and
`org.ofono.VoiceCallManager` interfaces, unless explicitly documented otherwise.
Call objects are announced via both the standard DBus ObjectManager interface
and via the `org.ofono.VoiceCallManager` interface, for compatibility.
### Methods ### Methods
`array{object,dict} GetCalls()`
Get an array of call object paths and properties that represents the currently
present calls.
This method call should only be used once when an application starts up.
Further call additions and removal shall be monitored via CallAdded and
CallRemoved signals.
NOTE: This method is implemented only on the `org.ofono.VoiceCallManager`
interface, for compatibility. Call announcements are normally made available via
the standard `org.freedesktop.DBus.ObjectManager` interface.
`object Dial(string number)` `object Dial(string number)`
Initiates a new outgoing call. Returns the object path to the newly created Initiates a new outgoing call. Returns the object path to the newly created
@ -142,21 +201,55 @@ Possible Errors:
* org.freedesktop.DBus.Error.InvalidArgs * org.freedesktop.DBus.Error.InvalidArgs
* org.freedesktop.DBus.Error.Failed * org.freedesktop.DBus.Error.Failed
### Signals
## Call Interface `CallAdded(object path, dict properties)`
Signal that is sent when a new call is added. It contains the object path of
the new voice call and also its properties.
NOTE: This method is implemented only on the `org.ofono.VoiceCallManager`
interface, for compatibility. Call announcements are normally made available via
the standard `org.freedesktop.DBus.ObjectManager` interface.
`CallRemoved(object path)`
Signal that is sent when a voice call has been released. The object path is no
longer accessible after this signal and only emitted for reference.
NOTE: This method is implemented only on the `org.ofono.VoiceCallManager`
interface, for compatibility. Call announcements are normally made available via
the standard `org.freedesktop.DBus.ObjectManager` interface.
## Call Object
``` ```
Service org.freedesktop.PipeWire.Telephony Service org.freedesktop.PipeWire.Telephony
Interface org.freedesktop.PipeWire.Telephony.Call1 or org.ofono
Requires org.freedesktop.DBus.Introspectable
org.freedesktop.DBus.Properties
Object path /org/freedesktop/PipeWire/Telephony/{ag0,ag1,...}/{call0,call1,...} Object path /org/freedesktop/PipeWire/Telephony/{ag0,ag1,...}/{call0,call1,...}
Implements org.freedesktop.PipeWire.Telephony.Call1
org.ofono.VoiceCall
org.freedesktop.DBus.Introspectable
org.freedesktop.DBus.Properties
``` ```
Call objects represent active calls and allows managing them. Call objects represent active calls and allow managing them.
The methods, signals and properties listed below are made available on both
`org.freedesktop.PipeWire.Telephony.Call1` and `org.ofono.VoiceCall`
interfaces, unless explicitly documented otherwise.
### Methods ### Methods
`dict GetProperties()`
Returns all properties for this object. See the properties section for available
properties.
NOTE: This method is implemented only on the `org.ofono.VoiceCall` interface,
for compatibility. Properties are normally made available via the standard
`org.freedesktop.DBus.Properties` interface.
`void Answer()` `void Answer()`
Answers an incoming call. Only valid if the state of the call is "incoming". Answers an incoming call. Only valid if the state of the call is "incoming".
@ -196,6 +289,17 @@ Possible Errors:
* org.freedesktop.PipeWire.Telephony.Error.InvalidState * org.freedesktop.PipeWire.Telephony.Error.InvalidState
* org.freedesktop.DBus.Error.Failed * org.freedesktop.DBus.Error.Failed
### Signals
`PropertyChanged(string property, variant value)`
Signal is emitted whenever a property has changed. The new value is passed as
the signal argument.
NOTE: This method is implemented only on the `org.ofono.VoiceCall` interface,
for compatibility. Properties are normally made available via the standard
`org.freedesktop.DBus.Properties` interface.
### Properties ### Properties
`string LineIdentification [readonly]` `string LineIdentification [readonly]`
@ -205,6 +309,10 @@ 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 this attribute will hold the dialed number, or the COLP if received by the
audio gateway. audio gateway.
Please note that COLP may be different from the dialed number. A special
"withheld" value means the remote party refused to provide caller ID and the
"override category" option was not provisioned for the current subscriber.
`string IncomingLine [readonly, optional]` `string IncomingLine [readonly, optional]`
Contains the Called Line Identification information returned by the network. Contains the Called Line Identification information returned by the network.
@ -222,6 +330,8 @@ present.
Contains the indication if the call is part of a multiparty call or not. Contains the indication if the call is part of a multiparty call or not.
Notifications if a call becomes part or leaves a multiparty call are sent.
`string State [readonly]` `string State [readonly]`
Contains the state of the current call. The state can be one of: Contains the state of the current call. The state can be one of: