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 BlueZ 7/8] doc/advertising-api: Rename to org.bluez.LEAdvertis*.rst
Date:   Fri,  6 Oct 2023 18:01:49 -0700
Message-ID: <20231007010150.4103452-7-luiz.dentz@gmail.com>
In-Reply-To: <20231007010150.4103452-1-luiz.dentz@gmail.com>
References: <20231007010150.4103452-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 advertising-api.txt to org.bluez.LEAdvertis*.rst and
generate manpages org.bluez.LEAdvertis*.5.
---
 Makefile.am                            |   7 +-
 doc/advertising-api.txt                | 278 -------------------------
 doc/org.bluez.LEAdvertisement.rst      | 195 +++++++++++++++++
 doc/org.bluez.LEAdvertisingManager.rst | 144 +++++++++++++
 4 files changed, 345 insertions(+), 279 deletions(-)
 delete mode 100644 doc/advertising-api.txt
 create mode 100644 doc/org.bluez.LEAdvertisement.rst
 create mode 100644 doc/org.bluez.LEAdvertisingManager.rst

diff --git a/Makefile.am b/Makefile.am
index 38074c773b4f..892965261bef 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -366,6 +366,8 @@ 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 \
 		doc/org.bluez.MediaTransport.5
+man_MANS += doc/org.bluez.LEAdvertisingManager.5 \
+		doc/org.bluez.LEAdvertisement.5
 endif
 manual_pages += src/bluetoothd.8
 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
@@ -377,6 +379,8 @@ 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 \
 		doc/org.bluez.MediaTransport.5
+manual_pages += doc/org.bluez.LEAdvertisingManager.5 \
+		doc/org.bluez.LEAdvertisement.5
 
 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
 			src/main.conf profiles/network/network.conf \
@@ -427,7 +431,8 @@ EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \
 		doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \
 		doc/org.bluez.MediaTransport.rst
 
-EXTRA_DIST += doc/gatt-api.txt doc/advertising-api.txt
+EXTRA_DIST += doc/gatt-api.txt doc/org.bluez.LEAdvertisingManager.rst \
+		doc/org.bluez.LEAdvertisement.rst
 
 EXTRA_DIST += doc/obex-api.txt doc/obex-agent-api.txt
 
diff --git a/doc/advertising-api.txt b/doc/advertising-api.txt
deleted file mode 100644
index a0077843defd..000000000000
--- a/doc/advertising-api.txt
+++ /dev/null
@@ -1,278 +0,0 @@
-BlueZ D-Bus LE Advertising API Description
-******************************************
-
-Advertising packets are structured data which is broadcast on the LE Advertising
-channels and available for all devices in range.  Because of the limited space
-available in LE Advertising packets (31 bytes), each packet's contents must be
-carefully controlled.
-
-BlueZ acts as a store for the Advertisement Data which is meant to be sent.
-It constructs the correct Advertisement Data from the structured
-data and configured the kernel to send the correct advertisement.
-
-Advertisement Data objects are registered freely and then referenced by BlueZ
-when constructing the data sent to the kernel.
-
-LE Advertisement Data hierarchy
-===============================
-
-Specifies the Advertisement Data to be broadcast and some advertising
-parameters.  Properties which are not present will not be included in the
-data.  Required advertisement data types will always be included.
-All UUIDs are 128-bit versions in the API, and 16 or 32-bit
-versions of the same UUID will be used in the advertising data as appropriate.
-
-Service		org.bluez
-Interface	org.bluez.LEAdvertisement1
-Object path	freely definable
-
-Methods		void Release() [noreply]
-
-			This method gets called when the service daemon
-			removes the Advertisement. A client can use it to do
-			cleanup tasks. There is no need to call
-			UnregisterAdvertisement because when this method gets
-			called it has already been unregistered.
-
-Properties	string Type
-
-			Determines the type of advertising packet requested.
-
-			Possible values: "broadcast" or "peripheral"
-
-		array{string} ServiceUUIDs
-
-			List of UUIDs to include in the "Service UUID" field of
-			the Advertising Data.
-
-		dict ManufacturerData
-
-			Manufactuer Data fields to include in
-			the Advertising Data.  Keys are the Manufacturer ID
-			to associate with the data.
-
-		array{string} SolicitUUIDs
-
-			Array of UUIDs to include in "Service Solicitation"
-			Advertisement Data.
-
-		dict ServiceData
-
-			Service Data elements to include. The keys are the
-			UUID to associate with the data.
-
-		dict Data [Experimental]
-
-			Advertising Type to include in the Advertising
-			Data. Key is the advertising type and value is the
-			data as byte array.
-
-			Note: Types already handled by other properties shall
-			not be used.
-
-			Possible values:
-				<type> <byte array>
-				...
-
-			Example:
-				<Transport Discovery> <Organization Flags...>
-				0x26                   0x01         0x01...
-
-		bool Discoverable [Experimental]
-
-			Advertise as general discoverable. When present this
-			will override adapter Discoverable property.
-
-			Note: This property shall not be set when Type is set
-			to broadcast.
-
-		uint16 DiscoverableTimeout [Experimental]
-
-			The discoverable timeout in seconds. A value of zero
-			means that the timeout is disabled and it will stay in
-			discoverable/limited mode forever.
-
-			Note: This property shall not be set when Type is set
-			to broadcast.
-
-		array{string} Includes
-
-			List of features to be included in the advertising
-			packet.
-
-			Possible values: as found on
-					LEAdvertisingManager.SupportedIncludes
-
-		string LocalName
-
-			Local name to be used in the advertising report. If the
-			string is too big to fit into the packet it will be
-			truncated.
-
-			If this property is available 'local-name' cannot be
-			present in the Includes.
-
-		uint16 Appearance
-
-			Appearance to be used in the advertising report.
-
-			Possible values: as found on GAP Service.
-
-		uint16_t Duration
-
-			Rotation duration of the advertisement in seconds. If
-			there are other applications advertising no duration is
-			set the default is 2 seconds.
-
-		uint16_t Timeout
-
-			Timeout of the advertisement in seconds. This defines
-			the lifetime of the advertisement.
-
-		string SecondaryChannel [Experimental]
-
-			Secondary channel to be used. Primary channel is
-			always set to "1M" except when "Coded" is set.
-
-			Possible value: "1M" (default)
-					"2M"
-					"Coded"
-
-		uint32 MinInterval [Experimental]
-
-			Minimum advertising interval to be used by the
-			advertising set, in milliseconds. Acceptable values
-			are in the range [20ms, 10,485s]. If the provided
-			MinInterval is larger than the provided MaxInterval,
-			the registration will return failure.
-
-		uint32 MaxInterval [Experimental]
-
-			Maximum advertising interval to be used by the
-			advertising set, in milliseconds. Acceptable values
-			are in the range [20ms, 10,485s]. If the provided
-			MinInterval is larger than the provided MaxInterval,
-			the registration will return failure.
-
-		int16 TxPower [Experimental]
-
-			Requested transmission power of this advertising set.
-			The provided value is used only if the "CanSetTxPower"
-			feature is enabled on the Advertising Manager. The
-			provided value must be in range [-127 to +20], where
-			units are in dBm.
-
-
-LE Advertising Manager hierarchy
-================================
-
-The Advertising Manager allows external applications to register Advertisement
-Data which should be broadcast to devices.  Advertisement Data elements must
-follow the API for LE Advertisement Data described above.
-
-Service		org.bluez
-Interface	org.bluez.LEAdvertisingManager1
-Object path	/org/bluez/{hci0,hci1,...}
-
-Methods		RegisterAdvertisement(object advertisement, dict options)
-
-			Registers an advertisement object to be sent over the LE
-			Advertising channel.  The service must be exported
-			under interface LEAdvertisement1.
-
-			InvalidArguments error indicates that the object has
-			invalid or conflicting properties.
-
-			InvalidLength error indicates that the data
-			provided generates a data packet which is too long.
-
-			The properties of this object are parsed when it is
-			registered, and any changes are ignored.
-
-			If the same object is registered twice it will result in
-			an AlreadyExists error.
-
-			If the maximum number of advertisement instances is
-			reached it will result in NotPermitted error.
-
-			Possible errors: org.bluez.Error.InvalidArguments
-					 org.bluez.Error.AlreadyExists
-					 org.bluez.Error.InvalidLength
-					 org.bluez.Error.NotPermitted
-
-		UnregisterAdvertisement(object advertisement)
-
-			This unregisters an advertisement 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.InvalidArguments
-					 org.bluez.Error.DoesNotExist
-
-Properties	byte ActiveInstances
-
-			Number of active advertising instances.
-
-		byte SupportedInstances
-
-			Number of available advertising instances.
-
-		array{string} SupportedIncludes
-
-			List of supported system includes.
-
-			Possible values: "tx-power"
-					 "appearance"
-					 "local-name"
-					 "rsi"
-
-		array{string} SupportedSecondaryChannels [Experimental]
-
-			List of supported Secondary channels. Secondary
-			channels can be used to advertise with the
-			corresponding PHY.
-
-			Possible values: "1M"
-					 "2M"
-					 "Coded"
-
-		dict SupportedCapabilities [Experimental]
-
-			Enumerates Advertising-related controller capabilities
-			useful to the client.
-
-			Possible Values:
-
-				byte MaxAdvLen
-
-					Max advertising data length
-
-				byte MaxScnRspLen
-
-					Max advertising scan response length
-
-				int16 MinTxPower
-
-					Min advertising tx power (dBm)
-
-				int16 MaxTxPower
-
-					Max advertising tx power (dBm)
-
-		array{string} SupportedFeatures [readonly,optional,Experimental]
-
-			List of supported platform features. If no features
-			are available on the platform, the SupportedFeatures
-			array will be empty.
-
-			Possible values: "CanSetTxPower"
-
-						Indicates whether platform can
-						specify tx power on each
-						advertising instance.
-
-					 "HardwareOffload"
-
-						Indicates whether multiple
-						advertising will be offloaded
-						to the controller.
diff --git a/doc/org.bluez.LEAdvertisement.rst b/doc/org.bluez.LEAdvertisement.rst
new file mode 100644
index 000000000000..4609bde74a5e
--- /dev/null
+++ b/doc/org.bluez.LEAdvertisement.rst
@@ -0,0 +1,195 @@
+=========================
+org.bluez.LEAdvertisement
+=========================
+
+---------------------------------------------
+BlueZ D-Bus LEAdvertisement API documentation
+---------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Description
+===========
+
+Advertising packets are structured data which is broadcast on the LE Advertising
+channels and available for all devices in range.  Because of the limited space
+available in LE Advertising packets, each packet's contents must be carefully
+controlled.
+
+The service daemon acts as a store for the Advertisement Data which is meant to
+be sent. It constructs the correct Advertisement Data from the structured
+data and configured the kernel to send the correct advertisement.
+
+Interface
+=========
+
+Specifies the Advertisement Data to be broadcast and some advertising
+parameters.  Properties which are not present will not be included in the
+data.  Required advertisement data types will always be included.
+All UUIDs are 128-bit versions in the API, and 16 or 32-bit
+versions of the same UUID will be used in the advertising data as appropriate.
+
+:Service:	org.bluez
+:Interface:	org.bluez.LEAdvertisement1
+:Object path:	freely definable
+
+Methods
+-------
+
+void Release() [noreply]
+````````````````````````
+
+	This method gets called when the service daemon removes the
+	Advertisement. A client can use it to do cleanup tasks. There is no
+	need to call **UnregisterAdvertisement()** because when this method
+	gets called it has already been unregistered.
+
+Properties
+----------
+
+string Type [readonly]
+``````````````````````
+
+	Determines the type of advertising packet requested.
+
+	Possible values:
+
+	:"broadcast":
+	:"peripheral":
+
+array{string} ServiceUUIDs
+``````````````````````````
+
+	List of UUIDs to include in the "Service UUID" field of the Advertising
+	Data.
+
+dict ManufacturerData
+`````````````````````
+
+	Manufacturer Data fields to include in the Advertising Data.  Keys are
+	the Manufacturer ID to associate with the data.
+
+array{string} SolicitUUIDs
+``````````````````````````
+
+	Array of UUIDs to include in "Service Solicitation" Advertisement Data.
+
+dict ServiceData
+````````````````
+
+	Service Data elements to include. The keys are the UUID to associate
+	with the data.
+
+dict Data [Experimental]
+````````````````````````
+
+	Advertising Data to include. Key is the advertising type and value is
+	the data as byte array.
+
+	Note: Types already handled by other properties shall not be used.
+
+	Possible values:
+
+	:<type>:
+
+		<byte array>
+
+	Example:
+		<Transport Discovery> <Organization Flags...>
+		0x26                   0x01         0x01...
+
+bool Discoverable [Experimental]
+````````````````````````````````
+
+	Advertise as general discoverable. When present this will override
+	adapter Discoverable property.
+
+	Note: This property shall not be set when **Type** is set to
+	"broadcast".
+
+uint16 DiscoverableTimeout [Experimental]
+`````````````````````````````````````````
+
+	The discoverable timeout in seconds. A value of zero means that the
+	timeout is disabled and it will stay in discoverable/limited mode
+	forever.
+
+	Note: This property shall not be set when **Type** is set to
+	"broadcast".
+
+array{string} Includes
+``````````````````````
+
+	List of features to be included in the advertising packet.
+
+	Possible values:
+
+	See **org.bluez.LEAdvertisingManager(5)** **SupportedIncludes**
+	property.
+
+string LocalName
+````````````````
+
+	Local name to be used in the advertising report. If the string is too
+	big to fit into the packet it will be truncated.
+
+	If this property is available 'local-name' cannot be present in the
+	**Includes**.
+
+uint16 Appearance
+`````````````````
+
+	Appearance to be used in the advertising report.
+
+	Possible values: as found on GAP Service.
+
+uint16_t Duration
+`````````````````
+
+	Rotation duration of the advertisement in seconds. If there are other
+	applications advertising no duration is set the default is 2 seconds.
+
+uint16_t Timeout
+````````````````
+
+	Timeout of the advertisement in seconds. This defines the lifetime of
+	the advertisement.
+
+string SecondaryChannel [Experimental]
+``````````````````````````````````````
+
+	Secondary channel to be used. Primary channel is always set to "1M"
+	except when "Coded" is set.
+
+	Possible value:
+
+	:"1M" (default):
+	:"2M":
+	:"Coded":
+
+uint32 MinInterval [Experimental]
+`````````````````````````````````
+
+	Minimum advertising interval to be used by the advertising set, in
+	milliseconds. Acceptable values are in the range [20ms, 10,485s].
+	If the provided MinInterval is larger than the provided MaxInterval,
+	the registration will return failure.
+
+uint32 MaxInterval [Experimental]
+`````````````````````````````````
+
+	Maximum advertising interval to be used by the advertising set, in
+	milliseconds. Acceptable values are in the range [20ms, 10,485s]. If the
+	provided MinInterval is larger than the provided MaxInterval, the
+	registration will return failure.
+
+int16 TxPower [Experimental]
+````````````````````````````
+
+	Requested transmission power of this advertising set. The provided value
+	is used only if the "CanSetTxPower" feature is enabled on the
+	**org.bluez.LEAdvertisingManager(5)**. The provided value must be in
+	range [-127 to +20], where units are in dBm.
diff --git a/doc/org.bluez.LEAdvertisingManager.rst b/doc/org.bluez.LEAdvertisingManager.rst
new file mode 100644
index 000000000000..b9d5cafc6ff3
--- /dev/null
+++ b/doc/org.bluez.LEAdvertisingManager.rst
@@ -0,0 +1,144 @@
+==============================
+org.bluez.LEAdvertisingManager
+==============================
+
+-------------------------------------------------
+BlueZ D-Bus LEAvertisingManager API documentation
+-------------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+The Advertising Manager allows external applications to register Advertisement
+Data which should be broadcast to devices.  Advertisement Data elements must
+follow the API for LE Advertisement Data described above.
+
+:Service:	org.bluez
+:Interface:	org.bluez.LEAdvertisingManager1
+:Object path:	/org/bluez/{hci0,hci1,...}
+
+Methods
+-------
+
+void RegisterAdvertisement(object advertisement, dict options)
+``````````````````````````````````````````````````````````````
+
+	Registers an advertisement object to be sent over the LE Advertising
+	channel.  The service must implement **org.bluez.LEAdvertisement(5)**
+	interface.
+
+	Possible errors:
+
+	:org.bluez.Error.InvalidArguments:
+
+		Indicates that the object has invalid or conflicting properties.
+
+	:org.bluez.Error.AlreadyExists:
+
+		Indicates the object is already registered.
+
+	:org.bluez.Error.InvalidLength:
+
+		Indicates that the data provided generates a data packet which
+		is too long
+
+	:org.bluez.Error.NotPermitted:
+
+		Indicates the maximum number of advertisement instances has
+		been reached.
+
+void UnregisterAdvertisement(object advertisement)
+``````````````````````````````````````````````````
+
+	Unregisters an advertisement that has been previously registered using
+	**RegisterAdvertisement()**.  The object path parameter must match the
+	same value that has been used on registration.
+
+	Possible errors:
+
+	:org.bluez.Error.InvalidArguments:
+	:org.bluez.Error.DoesNotExist:
+
+Properties
+----------
+
+byte ActiveInstances [readonly]
+```````````````````````````````
+
+	Number of active advertising instances.
+
+byte SupportedInstances [readonly]
+``````````````````````````````````
+
+	Number of available advertising instances.
+
+array{string} SupportedIncludes [readonly]
+``````````````````````````````````````````
+
+	List of supported system includes.
+
+	Possible values:
+
+	:"tx-power":
+	:"appearance":
+	:"local-name":
+	:"rsi":
+
+array{string} SupportedSecondaryChannels [readonly, Experimental]
+`````````````````````````````````````````````````````````````````
+
+	List of supported Secondary channels. Secondary channels can be used to
+	advertise with the corresponding PHY.
+
+	Possible values:
+
+	:"1M":
+	:"2M":
+	:"Coded":
+
+dict SupportedCapabilities [readonly, Experimental]
+```````````````````````````````````````````````````
+
+	Enumerates Advertising-related controller capabilities useful to the
+	client.
+
+	Possible Values:
+
+	:byte MaxAdvLen:
+
+		Max advertising data length
+
+	:byte MaxScnRspLen:
+
+		Max advertising scan response length
+
+	;int16 MinTxPower:
+
+		Min advertising tx power (dBm)
+
+	:int16 MaxTxPower:
+
+		Max advertising tx power (dBm)
+
+array{string} SupportedFeatures [readonly,optional,Experimental]
+````````````````````````````````````````````````````````````````
+
+	List of supported platform features. If no features are available on
+	the platform, the SupportedFeatures array will be empty.
+
+	Possible values:
+
+	:"CanSetTxPower":
+
+		Indicates whether platform can specify tx power on each
+		advertising instance.
+
+	:"HardwareOffload":
+
+		Indicates whether multiple advertising will be offloaded to the
+		controller.
-- 
2.41.0