Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 23.128.96.37 as permitted sender) client-ip=23.128.96.37;
From:   Luiz Augusto von Dentz <luiz.dentz@gmail.com>
To:     linux-bluetooth@vger.kernel.org
Subject: [PATCH v2 10/11] doc/advertisement-monitor-api: Rename to org.bluez.AdvertisementMonitor*.rst
Date:   Mon,  9 Oct 2023 16:29:32 -0700
Message-ID: <20231009232933.500652-10-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 advertisement-monitor-api.txt to
org.bluez.AdvertisementMonitor*.rst and generate manpages
org.bluez.AdvertisementMonitor*.5.
---
 Makefile.am                                   |  12 +-
 doc/advertisement-monitor-api.txt             | 187 ------------------
 doc/org.bluez.AdvertisementMonitor.rst        | 153 ++++++++++++++
 doc/org.bluez.AdvertisementMonitorManager.rst |  90 +++++++++
 4 files changed, 252 insertions(+), 190 deletions(-)
 delete mode 100644 doc/advertisement-monitor-api.txt
 create mode 100644 doc/org.bluez.AdvertisementMonitor.rst
 create mode 100644 doc/org.bluez.AdvertisementMonitorManager.rst

diff --git a/Makefile.am b/Makefile.am
index 239d2da7bb05..ae44937a50e1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -373,7 +373,9 @@ man_MANS += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
 		doc/org.bluez.GattCharacteristic.5 \
 		doc/org.bluez.GattDescriptor.5 \
 		doc/org.bluez.LEAdvertisingManager.5 \
-		doc/org.bluez.LEAdvertisement.5
+		doc/org.bluez.LEAdvertisement.5 \
+		doc/org.bluez.AdvertisementMonitorManager.5 \
+		doc/org.bluez.AdvertisementMonitor.5
 endif
 manual_pages += src/bluetoothd.8
 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
@@ -392,7 +394,9 @@ manual_pages += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \
 		doc/org.bluez.GattCharacteristic.5 \
 		doc/org.bluez.GattDescriptor.5 \
 		doc/org.bluez.LEAdvertisingManager.5 \
-		doc/org.bluez.LEAdvertisement.5
+		doc/org.bluez.LEAdvertisement.5 \
+		doc/org.bluez.AdvertisementMonitorManager.5 \
+		doc/org.bluez.AdvertisementMonitor.5
 
 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
 			src/main.conf profiles/network/network.conf \
@@ -450,7 +454,9 @@ EXTRA_DIST += doc/org.bluez.GattManager.rst doc/org.bluez.GattProfile.rst\
 		doc/org.bluez.GattCharacteristic.rst \
 		doc/org.bluez.GattDescriptor.rst \
 		doc/org.bluez.LEAdvertisingManager.rst \
-		doc/org.bluez.LEAdvertisement.rst
+		doc/org.bluez.LEAdvertisement.rst \
+		doc/org.bluez.AdvertisementMonitorManager.rst \
+		doc/org.bluez.AdvertisementMonitor.rst
 
 EXTRA_DIST += doc/obex-api.txt doc/obex-agent-api.txt
 
diff --git a/doc/advertisement-monitor-api.txt b/doc/advertisement-monitor-api.txt
deleted file mode 100644
index 9189f2cceb96..000000000000
--- a/doc/advertisement-monitor-api.txt
+++ /dev/null
@@ -1,187 +0,0 @@
-BlueZ D-Bus Advertisement Monitor API Description
-*************************************************
-
-This API allows an client to specify a job of monitoring advertisements by
-registering the root of hierarchy and then exposing advertisement monitors
-under the root with filtering conditions, thresholds of RSSI and timers
-of RSSI thresholds.
-
-Once a monitoring job is activated by BlueZ, the client can expect to get
-notified on the targeted advertisements no matter if there is an ongoing
-discovery session (a discovery session is started/stopped with methods in
-org.bluez.Adapter1 interface).
-
-Advertisement Monitor hierarchy
-===============================
-Service		org.bluez
-Interface	org.bluez.AdvertisementMonitor1 [experimental]
-Object path	freely definable
-
-Methods		void Release() [noreply]
-
-			This gets called as a signal for a client to perform
-			clean-up when (1)a monitor cannot be activated after it
-			was exposed or (2)a monitor has been deactivated.
-
-		void Activate() [noreply]
-
-			After a monitor was exposed, this gets called as a
-			signal for client to get acknowledged when a monitor
-			has been activated, so the client can expect to receive
-			calls on DeviceFound() or DeviceLost().
-
-		void DeviceFound(object device) [noreply]
-
-			This gets called to notify the client of finding the
-			targeted device. Once receiving the call, the client
-			should start to monitor the corresponding device to
-			retrieve the changes on RSSI and advertisement content.
-
-		void DeviceLost(object device) [noreply]
-
-			This gets called to notify the client of losing the
-			targeted device. Once receiving this call, the client
-			should stop monitoring the corresponding device.
-
-Properties	string Type [read-only]
-
-			The type of the monitor. See SupportedMonitorTypes in
-			org.bluez.AdvertisementMonitorManager1 for the available
-			options.
-
-		Int16 RSSILowThreshold [read-only, optional]
-
-			Used in conjunction with RSSILowTimeout to determine
-			whether a device becomes out-of-range. Valid range is
-			-127 to 20 (dBm), while 127 indicates unset.
-
-		Int16 RSSIHighThreshold [read-only, optional]
-
-			Used in conjunction with RSSIHighTimeout to determine
-			whether a device becomes in-range. Valid range is
-			-127 to 20 (dBm), while 127 indicates unset.
-
-		Uint16 RSSILowTimeout [read-only, optional]
-
-			The time it takes to consider a device as out-of-range.
-			If this many seconds elapses without receiving any
-			signal at least as strong as RSSILowThreshold, a
-			currently in-range device will be considered as
-			out-of-range (lost). Valid range is 1 to 300 (seconds),
-			while 0 indicates unset.
-
-		Uint16 RSSIHighTimeout [read-only, optional]
-
-			The time it takes to consider a device as in-range.
-			If this many seconds elapses while we continuously
-			receive signals at least as strong as RSSIHighThreshold,
-			a currently out-of-range device will be considered as
-			in-range (found). Valid range is 1 to 300 (seconds),
-			while 0 indicates unset.
-
-		Uint16 RSSISamplingPeriod [read-only, optional]
-
-			Grouping rules on how to propagate the received
-			advertisement packets to the client. Valid range is 0 to
-			255 while 256 indicates unset.
-
-			The meaning of this property is as follows:
-			0:
-				All advertisement packets from in-range devices
-				would be propagated.
-			255:
-				Only the first advertisement packet of in-range
-				devices would be propagated. If the device
-				becomes lost, then the first packet when it is
-				found again will also be propagated.
-			1 to 254:
-				Advertisement packets would be grouped into
-				100ms * N time period. Packets in the same group
-				will only be reported once, with the RSSI value
-				being averaged out.
-
-			Currently this is unimplemented in user space, so the
-			value is only used to be forwarded to the kernel.
-
-		array{(uint8, uint8, array{byte})} Patterns [read-only, optional]
-
-			If the Type property is set to "or_patterns", then this
-			property must exist and have at least one entry in the
-			array.
-
-			The structure of a pattern contains the following:
-			uint8 start_position
-				The index in an AD data field where the search
-				should start. The beginning of an AD data field
-				is index 0.
-			uint8 AD_data_type
-				See https://www.bluetooth.com/specifications/
-				assigned-numbers/generic-access-profile/ for
-				the possible allowed value.
-			array{byte} content_of_pattern
-				This is the value of the pattern. The maximum
-				length of the bytes is 31.
-
-Advertisement Monitor Manager hierarchy
-=======================================
-Service		org.bluez
-Interface	org.bluez.AdvertisementMonitorManager1 [experimental]
-Object path	/org/bluez/{hci0,hci1,...}
-
-Methods		void RegisterMonitor(object application)
-
-			This registers the root path of a hierarchy of
-			advertisement monitors.
-			The application object path together with the D-Bus
-			system bus connection ID define the identification of
-			the application registering advertisement monitors.
-			Once a root path is registered by a client via this
-			method, the client can freely expose/unexpose
-			advertisement monitors without re-registering the root
-			path again. After use, the client should call
-			UnregisterMonitor() method to invalidate the
-			advertisement monitors.
-
-			Possible errors: org.bluez.Error.InvalidArguments
-					 org.bluez.Error.AlreadyExists
-					 org.bluez.Error.Failed
-
-		void UnregisterMonitor(object application)
-
-			This unregisters a hierarchy of advertisement monitors
-			that has been previously registered. The object path
-			parameter must match the same value that has been used
-			on registration. Upon unregistration, the advertisement
-			monitor(s) should expect to receive Release() method as
-			the signal that the advertisement monitor(s) has been
-			deactivated.
-
-			Possible errors: org.bluez.Error.InvalidArguments
-					 org.bluez.Error.DoesNotExist
-
-Properties	array{string} SupportedMonitorTypes [read-only]
-
-			This lists the supported types of advertisement
-			monitors. An application should check this before
-			instantiate and expose an object of
-			org.bluez.AdvertisementMonitor1.
-
-			Possible values for monitor types:
-
-			"or_patterns"
-				Patterns with logic OR applied. With this type,
-				property "Patterns" must exist and has at least
-				one pattern.
-
-		array{string} SupportedFeatures [read-only]
-
-			This lists the features of advertisement monitoring
-			supported by BlueZ.
-
-			Possible values for features:
-
-			"controller-patterns"
-				If the controller is capable of performing
-				advertisement monitoring by patterns, BlueZ
-				would offload the patterns to the controller to
-				reduce power consumption.
diff --git a/doc/org.bluez.AdvertisementMonitor.rst b/doc/org.bluez.AdvertisementMonitor.rst
new file mode 100644
index 000000000000..98852ac68b59
--- /dev/null
+++ b/doc/org.bluez.AdvertisementMonitor.rst
@@ -0,0 +1,153 @@
+==============================
+org.bluez.AdvertisementMonitor
+==============================
+
+--------------------------------------------------
+BlueZ D-Bus AdvertisementMonitor API documentation
+--------------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Description
+===========
+
+This API allows an client to specify a job of monitoring advertisements by
+registering the root of hierarchy and then exposing advertisement monitors
+under the root with filtering conditions, thresholds of RSSI and timers
+of RSSI thresholds.
+
+Once a monitoring job is activated by **bluetoothd(8)**, the client can expect
+to get notified on the targeted advertisements no matter if there is an ongoing
+discovery session (see **StartDiscovery()** in **org.bluez.Adapter(5)**).
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.AdvertisementMonitor1 [experimental]
+:Object path:	freely definable
+
+Methods
+-------
+
+void Release() [noreply]
+````````````````````````
+
+	This gets called as a signal for a client to perform clean-up when:
+
+	- Monitor cannot be activated after it was exposed
+	- Monitor has been deactivated.
+
+void Activate() [noreply]
+`````````````````````````
+
+	After a monitor was exposed, this gets called as a signal for client to
+	get acknowledged when a monitor has been activated, so the client can
+	expect to receive calls on **DeviceFound()** or **DeviceLost()**.
+
+void DeviceFound(object device) [noreply]
+`````````````````````````````````````````
+
+	This gets called to notify the client of finding the targeted device.
+	Once receiving the call, the client should start to monitor the
+	corresponding device to retrieve the changes on RSSI and advertisement
+	content.
+
+void DeviceLost(object device) [noreply]
+````````````````````````````````````````
+
+	This gets called to notify the client of losing the targeted device.
+	Once receiving this call, the client should stop monitoring the
+	corresponding device.
+
+Properties
+----------
+
+string Type [read-only]
+```````````````````````
+
+	The type of the monitor. See **SupportedMonitorTypes** in
+	**org.bluez.AdvertisementMonitorManager(5)** for the available options.
+
+int16 RSSILowThreshold [read-only, optional]
+````````````````````````````````````````````
+
+	Used in conjunction with **RSSILowTimeout** to determine whether a
+	device becomes out-of-range. Valid range is -127 to 20 (dBm), while 127
+	indicates unset.
+
+int16 RSSIHighThreshold [read-only, optional]
+`````````````````````````````````````````````
+
+	Used in conjunction with RSSIHighTimeout to determine whether a device
+	becomes in-range. Valid range is -127 to 20 (dBm), while 127 indicates
+	unset.
+
+uint16 RSSILowTimeout [read-only, optional]
+```````````````````````````````````````````
+
+	The time it takes to consider a device as out-of-range. If this many
+	seconds elapses without receiving any signal at least as strong as
+	**RSSILowThreshold**, a currently in-range device will be considered as
+	out-of-range (lost). Valid range is 1 to 300 (seconds), while 0
+	indicates unset.
+
+uint16 RSSIHighTimeout [read-only, optional]
+````````````````````````````````````````````
+
+	The time it takes to consider a device as in-range. If this many
+	seconds elapses while we continuouslyreceive signals at least as strong
+	as **RSSIHighThreshold**, a currently out-of-range device will be
+	considered as in-range (found). Valid range is 1 to 300 (seconds),
+	while 0 indicates unset.
+
+uint16 RSSISamplingPeriod [read-only, optional]
+```````````````````````````````````````````````
+
+	Grouping rules on how to propagate the received advertisement packets
+	to the client.
+
+	Possible values:
+
+	:0:
+		All advertisement packets from in-range devices would be
+		propagated.
+
+	:255:
+		Only the first advertisement packet of in-range devices would
+		be propagated. If the device becomes lost, then the first
+		packet when it is found again will also be propagated.
+
+	:1 to 254:
+		Advertisement packets would be grouped into 100ms * N time
+		period. Packets in the same group will only be reported once,
+		with the RSSI value being averaged out.
+
+	Currently this is unimplemented in user space, so the value is only
+	used to be forwarded to the kernel.
+
+array{(uint8, uint8, array{byte})} Patterns [read-only, optional]
+`````````````````````````````````````````````````````````````````
+
+	If the **Type** property is set to **"or_patterns"**, then this
+	property must exist and have at least one entry in the array.
+
+	The structure of a pattern contains the following:
+
+	:uint8 start_position:
+
+		The index in an AD data field where the search hould start. The
+		beginning of an AD data field is index 0.
+
+	:uint8 AD_data_type:
+
+		See https://www.bluetooth.com/specifications/assigned-numbers/
+		generic-access-profile/ for the possible allowed value.
+
+	:array{byte} content_of_pattern:
+
+		This is the value of the pattern. The maximum length of the
+		bytes is 31.
diff --git a/doc/org.bluez.AdvertisementMonitorManager.rst b/doc/org.bluez.AdvertisementMonitorManager.rst
new file mode 100644
index 000000000000..3775a483543c
--- /dev/null
+++ b/doc/org.bluez.AdvertisementMonitorManager.rst
@@ -0,0 +1,90 @@
+=====================================
+org.bluez.AdvertisementMonitorManager
+=====================================
+
+---------------------------------------------------------
+BlueZ D-Bus AdvertisementMonitorManager API documentation
+---------------------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+Service		org.bluez
+Interface	org.bluez.AdvertisementMonitorManager1 [experimental]
+Object path	/org/bluez/{hci0,hci1,...}
+
+Methods
+-------
+
+void RegisterMonitor(object application)
+````````````````````````````````````````
+
+	Registers the root path of a hierarchy of advertisement monitors
+	implementing **org.bluez.AdvertisementMonitor(5)**.
+
+	The application object path together with the D-Bus ystem bus
+	connection ID define the identification of the application registering
+	advertisement monitors.
+
+	Once a root path is registered by a client via this method, the client
+	can freely expose/unexpose advertisement monitors without re-registering
+	the root path again. After use, the client should call
+	**UnregisterMonitor()** method to invalidate the advertisement monitors.
+
+	Possible errors:
+
+	:org.bluez.Error.InvalidArguments:
+	:org.bluez.Error.AlreadyExists:
+	:org.bluez.Error.Failed:
+
+void UnregisterMonitor(object application)
+``````````````````````````````````````````
+
+	Unregisters a hierarchy of advertisement monitors that has been
+	previously registered with **RegisterMonitor()**. The object path
+	parameter must match the same value that has been used on registration.
+
+	Upon unregistration, the advertisement monitor(s) should expect to
+	receive **Release()** method as the signal that the advertisement
+	monitor(s) has been deactivated.
+
+	Possible errors:
+
+	:org.bluez.Error.InvalidArguments:
+	:org.bluez.Error.DoesNotExist:
+
+Properties
+----------
+
+array{string} SupportedMonitorTypes [read-only]
+```````````````````````````````````````````````
+
+	This lists the supported types of advertisement monitors. An application
+	should check this before instantiate and expose an object of
+	**org.bluez.AdvertisementMonitor(5)**.
+
+	Possible values:
+
+	:"or_patterns":
+
+		Patterns with logic OR applied. With this type, property
+		**Patterns** must exist and has at least one pattern.
+
+array{string} SupportedFeatures [read-only]
+```````````````````````````````````````````
+
+	This lists the features of advertisement monitoring supported by
+	**bluetoothd(8)**.
+
+	Possible values:
+
+	:"controller-patterns":
+
+		If the controller is capable of performing advertisement
+		monitoring by patterns, **bluetoothd(8)** would offload the
+		patterns to the controller to reduce power consumption.
-- 
2.41.0