These are interfaces are meant to be generic to the telephony related
"headset" profiles like HSP HS, HFP HF, and CCP.
---
Makefile.am | 4 +
doc/org.bluez.TelephonyAg.rst | 200 ++++++++++++++++++++++++++++++++
doc/org.bluez.TelephonyCall.rst | 144 +++++++++++++++++++++++
3 files changed, 348 insertions(+)
create mode 100644 doc/org.bluez.TelephonyAg.rst
create mode 100644 doc/org.bluez.TelephonyCall.rst
diff --git a/Makefile.am b/Makefile.am
index 0f0037d5b..c53970d17 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -388,6 +388,7 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
doc/org.bluez.obex.Message.5 \
doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
doc/org.bluez.obex.Image.5
+man_MANS += doc/org.bluez.TelephonyAg.5 doc/org.bluez.TelephonyCall.5
endif
manual_pages += src/bluetoothd.8
manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
@@ -422,6 +423,7 @@ manual_pages += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
doc/org.bluez.obex.Message.5 \
doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
doc/org.bluez.obex.Image.5
+manual_pages += doc/org.bluez.TelephonyAg.5 doc/org.bluez.TelephonyCall.5
EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
src/main.conf profiles/network/network.conf \
@@ -506,6 +508,8 @@ EXTRA_DIST += doc/org.bluez.obex.Client.rst doc/org.bluez.obex.Session.rst \
doc/org.bluez.obex.AgentManager.rst doc/org.bluez.obex.Agent.rst \
doc/org.bluez.obex.Image.rst
+EXTRA_DIST += doc/org.bluez.TelephonyAg.rst doc/org.bluez.TelephonyCall.rst
+
EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
doc/pts-opp.txt
diff --git a/doc/org.bluez.TelephonyAg.rst b/doc/org.bluez.TelephonyAg.rst
new file mode 100644
index 000000000..e0a78a6a1
--- /dev/null
+++ b/doc/org.bluez.TelephonyAg.rst
@@ -0,0 +1,200 @@
+======================
+org.bluez.TelephonyAg1
+======================
+
+-----------------------------------------------------
+BlueZ D-Bus Telephony Audio Gateway API documentation
+-----------------------------------------------------
+
+:Version: BlueZ
+:Date: May 2025
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: org.bluez
+:Interface: org.bluez.TelephonyAg1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/{ccp,hfp,hsp}
+
+Methods
+-------
+
+object Dial(string number)
+``````````````````````````
+
+ Call number, if number is void try to call last dialed 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}` 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.
+
+ If number is an empty string, it will try to call last dialed number.
+
+ 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.bluez.Error.InvalidState:
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+ :org.bluez.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.bluez.Error.InvalidState
+ :org.bluez.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.bluez.Error.InvalidState
+ :org.bluez.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.bluez.Error.InvalidState
+ :org.bluez.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.bluez.Error.InvalidState
+ :org.bluez.Error.Failed
+
+void HangupAll()
+````````````````
+
+ Releases all calls except waiting calls. This includes multiparty
+ calls.
+
+ Possible Errors:
+ :org.bluez.Error.InvalidState
+ :org.bluez.Error.Failed
+
+void HangupActive()
+```````````````````
+
+ Releases active calls. This includes multiparty active calls.
+
+ Possible Errors:
+ :org.bluez.Error.InvalidState
+ :org.bluez.Error.Failed
+
+void HangupHeld()
+`````````````````
+
+ Releases held calls except waiting calls. This includes multiparty
+ held calls.
+
+ Possible Errors:
+ :org.bluez.Error.InvalidState
+ :org.bluez.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.bluez.Error.InvalidState
+ :org.bluez.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.bluez.Error.InvalidState
+ :org.bluez.Error.InvalidArgs
+ :org.bluez.Error.Failed
+
+Properties
+----------
+
+string State [readonly]
+```````````````````````
+
+ Contains the state of the current connection.
+
+ Possible values:
+
+ :"connecting":
+
+ RFComm connection in progress
+
+ :"slc_connecting":
+
+ Service Level Connection in progress
+
+ :"connected":
+
+ RFComm and Service Level Connection are connected
+
+ :"disconnecting":
+
+ No further use of this object is allowed, it will be destroyed
+ shortly
+
+boolean Service [readonly]
+``````````````````````````
+
+ Network service availability.
+
+byte Signal [readonly]
+``````````````````````
+
+ Network level signal from 0 to 5.
+
+boolean Roaming [readonly]
+``````````````````````````
+
+ Network roaming usage.
+
+byte BattChg [readonly]
+```````````````````````
+
+ Battery level from 0 to 5.
diff --git a/doc/org.bluez.TelephonyCall.rst b/doc/org.bluez.TelephonyCall.rst
new file mode 100644
index 000000000..63f862378
--- /dev/null
+++ b/doc/org.bluez.TelephonyCall.rst
@@ -0,0 +1,144 @@
+========================
+org.bluez.TelephonyCall1
+========================
+
+--------------------------------------------
+BlueZ D-Bus Telephony Call API documentation
+--------------------------------------------
+
+:Version: BlueZ
+:Date: May 2025
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: org.bluez
+:Interface: org.bluez.TelephonyCall1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/{ccp,hfp,hsp}/callX
+
+Methods
+-------
+
+void Answer()
+`````````````
+
+ Answers an incoming call. Only valid if the state of the call is
+ "incoming".
+
+ Possible Errors:
+ :org.bluez.Error.InvalidState
+ :org.bluez.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.bluez.Error.InvalidState
+ :org.bluez.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.
+
+ 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]
+````````````````````````````````````````
+
+ 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.
+
+ Notifications if a call becomes part or leaves a multiparty call are
+ sent.
+
+string State [readonly]
+```````````````````````
+
+ Contains the state of the current call.
+
+ Possible values:
+
+ :"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
--
2.43.0
