Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Wed, 13 Oct 2021 05:42:08 -0700
In-Reply-To: <20211013124210.1454876-1-mmandlik@google.com>
Message-Id: <20211013053935.BlueZ.v2.1.I7f6bdb9282c1e12ffc6c662674678f2b1cb69182@changeid>
Mime-Version: 1.0
References: <20211013124210.1454876-1-mmandlik@google.com>
Subject: [BlueZ PATCH v2 1/3] doc: Introduce the Adv Monitor Device Lost event
From:   Manish Mandlik <mmandlik@google.com>
To:     marcel@holtmann.org, luiz.dentz@gmail.com
Cc:     chromeos-bluetooth-upstreaming@chromium.org,
        linux-bluetooth@vger.kernel.org,
        Manish Mandlik <mmandlik@google.com>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

Add a flag 'Device Tracked' to the existing 'Device Found' event to
indicate that the controller has started tracking the device matching
an Advertisement Monitor with handle 'Monitor_Handle'.

Add a new event 'Adv Monitor Device Lost' to indicate that the
controller has stopped tracking that particular device.

---

Changes in v2:
- Instead of creating a new 'Device Tracking' event, add a flag 'Device
  Tracked' in the existing 'Device Found' event and add a new 'Device
  Lost' event to indicate that the controller has stopped tracking that
  device.

 doc/mgmt-api.txt | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 5355fedb0..0fd884ed0 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -107,7 +107,8 @@ Configuration command, Default Runtime Configuration Changed event, Get
 Device Flags command, Set Device Flags command, Device Flags Changed event,
 Read Advertisement Monitor Features command, Add Advertisement Patterns
 Monitor command, Remove Advertisement Monitor command, Advertisement Monitor
-Added event and Advertisement Monitor Removed event.
+Added event, Advertisement Monitor Removed event, Updated Device Found event
+and Added Advertisement Monitor Device Lost event.
 
 
 Example
@@ -4247,6 +4248,7 @@ Device Found Event
 				Address_Type (1 Octet)
 				RSSI (1 Octet)
 				Flags (4 Octets)
+				Monitor_Handle (2 Octets)
 				EIR_Data_Length (2 Octets)
 				EIR_Data (0-65535 Octets)
 
@@ -4263,6 +4265,7 @@ Device Found Event
 		1	Legacy Pairing
 		2	Not Connectable
 		3	Reserved (not in use)
+		4	Device Tracked
 
 	For the RSSI field a value of 127 indicates that the RSSI is
 	not available. That can happen with Bluetooth 1.1 and earlier
@@ -4285,6 +4288,10 @@ Device Found Event
 	accept any connections. This can be indicated by Low Energy
 	devices that are in broadcaster role.
 
+	The Device Tracked flag indicates that the controller has started
+	monitoring a particular device matching the Advertisement Monitor
+	with handle Monitor_Handle.
+
 
 Discovering Event
 =================
@@ -4910,3 +4917,26 @@ Controller Resume Event
 	Address_Type. Otherwise, Address and Address_Type will both be zero.
 
 	This event will be sent to all management sockets.
+
+
+Advertisement Monitor Device Lost Event
+=======================================
+
+	Event code:		0x002f
+	Controller Index:	<controller_id>
+	Event Parameters:	Monitor_Handle (2 Octets)
+				Address (6 Octets)
+				Address_Type (1 Octet)
+
+	This event indicates that the controller has stopped tracking the
+	device that was being tracked by monitor with handle Monitor_Handle.
+
+	The address of the device being tracked will be shared in Address and
+	Address_Type.
+
+	Possible values for the Address_Type parameter:
+		0	BR/EDR
+		1	LE Public
+		2	LE Random
+
+	This event will be sent to all management sockets.
-- 
2.33.0.882.g93a45727a2-goog