Date:   Thu, 25 Nov 2021 15:06:27 +0800
In-Reply-To: <20211125150558.Bluez.v4.1.I78857808e0b20c6e4dd934b174d3f1106fe3402d@changeid>
Message-Id: <20211125150558.Bluez.v4.5.I29367ca288fc8f4fcc3b4063425b791501c6534c@changeid>
Mime-Version: 1.0
References: <20211125150558.Bluez.v4.1.I78857808e0b20c6e4dd934b174d3f1106fe3402d@changeid>
Subject: [Bluez PATCH v4 5/5] doc: Add Name Request Fail flag in device found event
From:   Archie Pusaka <apusaka@google.com>
To:     linux-bluetooth <linux-bluetooth@vger.kernel.org>,
        Luiz Augusto von Dentz <luiz.dentz@gmail.com>,
        Marcel Holtmann <marcel@holtmann.org>
Cc:     CrosBT Upstreaming <chromeos-bluetooth-upstreaming@chromium.org>,
        Archie Pusaka <apusaka@chromium.org>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

From: Archie Pusaka <apusaka@chromium.org>

Userspace should use this new flag to decide whether to do the remote
name resolving or not.
---

Changes in v4:
* Add information about NameResolving cache

Changes in v3:
* Update the flag name to be more inlined with the spec.

Changes in v2:
* Update docs to reflect not sending DONT_CARE flag behavior.

 doc/mgmt-api.txt         |  7 +++++++
 doc/settings-storage.txt | 11 ++++++++++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 1ab513eb17..ebe56afa44 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -4090,6 +4090,7 @@ Device Connected Event
 		1	Legacy Pairing
 		2	Reserved (not in use)
 		3	Initiated Connection
+		4	Reserved (not in use)
 
 
 Device Disconnected Event
@@ -4264,6 +4265,7 @@ Device Found Event
 		1	Legacy Pairing
 		2	Not Connectable
 		3	Reserved (not in use)
+		4	Name Request Failed
 
 	For the RSSI field a value of 127 indicates that the RSSI is
 	not available. That can happen with Bluetooth 1.1 and earlier
@@ -4286,6 +4288,11 @@ Device Found Event
 	accept any connections. This can be indicated by Low Energy
 	devices that are in broadcaster role.
 
+	The Name Request Failed flag indicates that name resolving
+	procedure has ended with failure for this device. The user space
+	should use this information to determine when is a good time to
+	retry the name resolving procedure.
+
 
 Discovering Event
 =================
diff --git a/doc/settings-storage.txt b/doc/settings-storage.txt
index 3c637c3521..26584f2015 100644
--- a/doc/settings-storage.txt
+++ b/doc/settings-storage.txt
@@ -179,7 +179,7 @@ Cache directory file format
 ============================
 
 Each file, named by remote device address, may includes multiple groups
-(General, ServiceRecords, Attributes, Endpoints).
+(General, ServiceRecords, Attributes, Endpoints, NameResolving).
 
 In ServiceRecords, SDP records are stored using their handle as key
 (hexadecimal format).
@@ -193,6 +193,9 @@ In "Endpoints" group A2DP remote endpoints are stored using the seid as key
 an entry which key is set to "LastUsed" which represented the last endpoint
 used.
 
+In "NameResolving", information regarding remote name resolving are stored to
+prevent wasting time resolving name for unresponsive devices.
+
 [General] group contains:
 
   Name		String		Remote device friendly name
@@ -247,6 +250,12 @@ Sample Attributes section:
 					local and remote seids as hexadecimal
 					encoded string.
 
+[NameResolving] group contains:
+
+  FailedTime	Integer		The last time  we failed to complete name
+				resolving procedure, measured from an
+				arbitrary, fixed point in the past.
+
 Info file format
 ================
 
-- 
2.34.0.rc2.393.gf8c9666880-goog