Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 2620:137:e000::3:7 as permitted sender) client-ip=2620:137:e000::3:7;
From:   Luiz Augusto von Dentz <luiz.dentz@gmail.com>
To:     linux-bluetooth@vger.kernel.org
Subject: [PATCH v2 04/11] doc/profile-api: Rename to org.bluez.Profile{Manager}.rst
Date:   Mon,  9 Oct 2023 16:29:26 -0700
Message-ID: <20231009232933.500652-4-luiz.dentz@gmail.com>
In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com>
References: <20231009232933.500652-1-luiz.dentz@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

This renames profile-api.txt to org.bluez.Profile{Manager}.rst and
generate manpages org.bluez.Profile{Manager}.5.
---
 Makefile.am                      |  10 +-
 doc/org.bluez.Profile.rst        |  51 ++++++++++
 doc/org.bluez.ProfileManager.rst | 141 +++++++++++++++++++++++++
 doc/profile-api.txt              | 170 -------------------------------
 4 files changed, 198 insertions(+), 174 deletions(-)
 create mode 100644 doc/org.bluez.Profile.rst
 create mode 100644 doc/org.bluez.ProfileManager.rst
 delete mode 100644 doc/profile-api.txt

diff --git a/Makefile.am b/Makefile.am
index b25bc521cab3..64004004fb2a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -359,7 +359,8 @@ if MANPAGES
 man_MANS += src/bluetoothd.8
 man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 		doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
-		doc/org.bluez.Agent.5
+		doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
+		doc/org.bluez.Profile.5
 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
 		doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
 		doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
@@ -368,7 +369,8 @@ endif
 manual_pages += src/bluetoothd.8
 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 		doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
-		doc/org.bluez.Agent.5
+		doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
+		doc/org.bluez.Profile.5
 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
 		doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
 		doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
@@ -409,13 +411,13 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
 				doc/settings-storage.txt
 
 EXTRA_DIST += doc/mgmt-api.txt \
-		doc/profile-api.txt \
 		doc/network-api.txt doc/health-api.txt \
 		doc/sap-api.txt doc/input-api.txt
 
 EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
 	      doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
-	      doc/org.bluez.Agent.rst
+	      doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \
+	      doc/org.bluez.Profile.rst
 
 EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \
 		doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \
diff --git a/doc/org.bluez.Profile.rst b/doc/org.bluez.Profile.rst
new file mode 100644
index 000000000000..d8ae669c7323
--- /dev/null
+++ b/doc/org.bluez.Profile.rst
@@ -0,0 +1,51 @@
+=================
+org.bluez.Profile
+=================
+
+-------------------------------------
+BlueZ D-Bus Profile API documentation
+-------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	unique name
+:Interface:	org.bluez.Profile1
+:Object path:	freely definable
+
+Methods
+-------
+
+void Release() [noreply]
+````````````````````````
+
+	This method gets called when the service daemon unregisters the profile.
+	A profile can use it to do cleanup tasks. There is no need to unregister
+	the profile, because when this method gets called it has already been
+	unregistered.
+
+void NewConnection(object device, fd, dict fd_properties)
+`````````````````````````````````````````````````````````
+
+	This method gets called when a new service level connection has been
+	made and authorized.
+
+	Possible fd_properties values:
+
+	:uint16 Version [optional]:
+
+		Profile version.
+
+	:uint16 Features [optional]:
+
+		Profile features.
+
+	Possible errors:
+
+	:org.bluez.Error.Rejected:
+	:org.bluez.Error.Canceled:
diff --git a/doc/org.bluez.ProfileManager.rst b/doc/org.bluez.ProfileManager.rst
new file mode 100644
index 000000000000..ccd7a2673d77
--- /dev/null
+++ b/doc/org.bluez.ProfileManager.rst
@@ -0,0 +1,141 @@
+========================
+org.bluez.ProfileManager
+========================
+
+--------------------------------------------
+BlueZ D-Bus ProfileManager API documentation
+--------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.ProfileManager1
+:Object path:	/org/bluez
+
+Methods
+-------
+
+void RegisterProfile(object profile, string uuid, dict options)
+```````````````````````````````````````````````````````````````
+
+	Registers profile agent.
+
+	The object path defines the path of the profile that will be called
+	when there is a connection and must implement **org.bluez.Profile(5)**
+	interface.
+
+	If an application disconnects from the bus all its registered profiles
+	will be removed.
+
+	Possible uuid values:
+
+	:"0000111f-0000-1000-8000-00805f9b34fb":
+
+		HFP AG, default profile Version is 1.7, profile Features is
+		0b001001 and RFCOMM channel is 13. Authentication is required.
+
+	:"0000111e-0000-1000-8000-00805f9b34fb":
+
+		HFP HS, default profile Version is 1.7, profile Features is
+		0b000000 and RFCOMM channel is 7. Authentication is required.
+
+	:"00001112-0000-1000-8000-00805f9b34fb":
+
+		HSP AG, default profile Version is 1.2, RFCOMM channel is 12 and
+		Authentication is required. Does not support any Features,
+		option is ignored.
+
+	:"00001108-0000-1000-8000-00805f9b34fb":
+
+		HSP HS, default profile Version is 1.2, profile Features is 0b0
+		and RFCOMM channel is 6. Authentication is required.
+		Features is one bit value, specify capability of Remote Audio
+		Volume Control (by default turned off).
+
+	:"<vendor UUID>":
+
+		Vendor defined UUID, no defaults, must set options.
+
+	Possible options values:
+
+	:string Name:
+
+		Human readable name for the profile
+
+	:string Service:
+
+		The primary service class UUID (if different from the actual
+		profile UUID).
+
+	:string Role:
+
+		For asymmetric profiles that do not have UUIDs available to
+		uniquely identify each side this parameter allows specifying the
+		precise local role.
+
+		Possible values:
+
+		:"client":
+		:"server":
+
+	:uint16 Channel:
+
+		RFCOMM channel number that is used for client and server UUIDs.
+
+		If applicable it will be used in the SDP record as well.
+
+	:uint16 PSM:
+
+		PSM number that is used for client and server UUIDs.
+
+		If applicable it will be used in the SDP record as well.
+
+	:boolean RequireAuthentication:
+
+		Pairing is required before connections will be established.
+		No devices will be connected if not paired.
+
+	:boolean RequireAuthorization:
+
+		Request authorization before any connection will be established.
+
+	:boolean AutoConnect:
+
+		In case of a client UUID this will force connection of the
+		RFCOMM or L2CAP channels when a remote device is connected.
+
+	:string ServiceRecord:
+
+		Provide a manual SDP record.
+
+	:uint16 Version:
+
+		Profile version (for SDP record)
+
+	:uint16 Features:
+
+		Profile features (for SDP record)
+
+	Possible errors:
+
+	:org.bluez.Error.InvalidArguments:
+	:org.bluez.Error.AlreadyExists:
+
+void UnregisterProfile(object profile)
+``````````````````````````````````````
+
+	Unregisters profile object that has been previously registered using
+	**RegisterProfile**.
+
+	The object path parameter must match the same value that has been used
+	on registration.
+
+	Possible errors:
+
+	:org.bluez.Error.DoesNotExist:
diff --git a/doc/profile-api.txt b/doc/profile-api.txt
deleted file mode 100644
index 183c6c11a7ba..000000000000
--- a/doc/profile-api.txt
+++ /dev/null
@@ -1,170 +0,0 @@
-BlueZ D-Bus Profile API description
-***********************************
-
-
-Profile Manager hierarchy
-=========================
-
-Service		org.bluez
-Interface	org.bluez.ProfileManager1
-Object path	/org/bluez
-
-		void RegisterProfile(object profile, string uuid, dict options)
-
-			This registers a profile implementation.
-
-			If an application disconnects from the bus all
-			its registered profiles will be removed.
-
-			Some predefined services:
-
-			HFP AG UUID: 0000111f-0000-1000-8000-00805f9b34fb
-
-				Default profile Version is 1.7, profile Features
-				is 0b001001 and RFCOMM channel is 13.
-				Authentication is required.
-
-			HFP HS UUID: 0000111e-0000-1000-8000-00805f9b34fb
-
-				Default profile Version is 1.7, profile Features
-				is 0b000000 and RFCOMM channel is 7.
-				Authentication is required.
-
-			HSP AG UUID: 00001112-0000-1000-8000-00805f9b34fb
-
-				Default profile Version is 1.2, RFCOMM channel
-				is 12 and Authentication is required. Does not
-				support any Features, option is ignored.
-
-			HSP HS UUID: 00001108-0000-1000-8000-00805f9b34fb
-
-				Default profile Version is 1.2, profile Features
-				is 0b0 and RFCOMM channel is 6. Authentication
-				is required. Features is one bit value, specify
-				capability of Remote Audio Volume Control
-				(by default turned off).
-
-			Available options:
-
-				string Name
-
-					Human readable name for the profile
-
-				string Service
-
-					The primary service class UUID
-					(if different from the actual
-					 profile UUID)
-
-				string Role
-
-					For asymmetric profiles that do not
-					have UUIDs available to uniquely
-					identify each side this
-					parameter allows specifying the
-					precise local role.
-
-					Possible values: "client", "server"
-
-				uint16 Channel
-
-					RFCOMM channel number that is used
-					for client and server UUIDs.
-
-					If applicable it will be used in the
-					SDP record as well.
-
-				uint16 PSM
-
-					PSM number that is used for client
-					and server UUIDs.
-
-					If applicable it will be used in the
-					SDP record as well.
-
-				boolean RequireAuthentication
-
-					Pairing is required before connections
-					will be established. No devices will
-					be connected if not paired.
-
-				boolean RequireAuthorization
-
-					Request authorization before any
-					connection will be established.
-
-				boolean AutoConnect
-
-					In case of a client UUID this will
-					force connection of the RFCOMM or
-					L2CAP channels when a remote device
-					is connected.
-
-				string ServiceRecord
-
-					Provide a manual SDP record.
-
-				uint16 Version
-
-					Profile version (for SDP record)
-
-				uint16 Features
-
-					Profile features (for SDP record)
-
-			Possible errors: org.bluez.Error.InvalidArguments
-			                 org.bluez.Error.AlreadyExists
-
-		void UnregisterProfile(object profile)
-
-			This unregisters the profile that has been previously
-			registered. The object path parameter must match the
-			same value that has been used on registration.
-
-			Possible errors: org.bluez.Error.DoesNotExist
-
-
-Profile hierarchy
-=================
-
-Service		unique name
-Interface	org.bluez.Profile1
-Object path	freely definable
-
-Methods		void Release() [noreply]
-
-			This method gets called when the service daemon
-			unregisters the profile. A profile can use it to do
-			cleanup tasks. There is no need to unregister the
-			profile, because when this method gets called it has
-			already been unregistered.
-
-		void NewConnection(object device, fd, dict fd_properties)
-
-			This method gets called when a new service level
-			connection has been made and authorized.
-
-			Common fd_properties:
-
-			uint16 Version		Profile version (optional)
-			uint16 Features		Profile features (optional)
-
-			Possible errors: org.bluez.Error.Rejected
-			                 org.bluez.Error.Canceled
-
-		void RequestDisconnection(object device)
-
-			This method gets called when a profile gets
-			disconnected.
-
-			The file descriptor is no longer owned by the service
-			daemon and the profile implementation needs to take
-			care of cleaning up all connections.
-
-			If multiple file descriptors are indicated via
-			NewConnection, it is expected that all of them
-			are disconnected before returning from this
-			method call.
-
-			Possible errors: org.bluez.Error.Rejected
-			                 org.bluez.Error.Canceled
-- 
2.41.0