[RFC BlueZ 01/10] doc: Add new telephony related profiles interfaces

["Frédéric Danis" <frederic.danis@collabora.com>]

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