From 2100e50b1bed1fc5a401dfee2ae1f637a524eb94 Mon Sep 17 00:00:00 2001 From: Jonathan Peppers Date: Sun, 16 Aug 2026 08:56:05 -0500 Subject: [PATCH 1/3] Document Android ranging session APIs Refs #159 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/xml/Android.Ranging/RangingManager.xml | 69 +++++++++++++++++---- docs/xml/Android.Ranging/RangingSession.xml | 18 +++++- 2 files changed, 73 insertions(+), 14 deletions(-) diff --git a/docs/xml/Android.Ranging/RangingManager.xml b/docs/xml/Android.Ranging/RangingManager.xml index 54918c379..e67cd1145 100644 --- a/docs/xml/Android.Ranging/RangingManager.xml +++ b/docs/xml/Android.Ranging/RangingManager.xml @@ -172,11 +172,27 @@ - To be added. - To be added. - To be added. - To be added. - To be added. + The executor on which the callback will be invoked. + The callback to receive session-related events. + Creates a new ranging session. + A RangingSession that can initiate, manage, and stop ranging operations. + + Creates a new ranging session. A ranging session enables the application to perform + ranging operations using available technologies such as Ultra-Wideband (UWB) or Wi-Fi + Round Trip Time (RTT). + The callback receives session-related events, including session start, stop, and + ranging updates. Provide an executor that handles callbacks on a suitable thread. + + + Java documentation for android.ranging.RangingManager.createRangingSession(java.util.concurrent.Executor, android.ranging.RangingSession.Callback). + + + + Portions of this page are modifications based on work created and shared by the + Android Open Source Project + and used according to terms described in the + Creative Commons 2.5 Attribution License. + @@ -236,10 +252,25 @@ - To be added. - To be added. - To be added. - To be added. + The executor on which the callback will be invoked. + The callback that receives capabilities updates. + Registers a callback to receive ranging capabilities updates. + + Registers a callback to receive ranging capabilities updates. + Callback events are dispatched through the provided executor, which controls the + thread on which they run. Use Context.getMainExecutor() to dispatch events on + the application's main thread, or provide an executor for another suitable thread. + + + Java documentation for android.ranging.RangingManager.registerCapabilitiesCallback(java.util.concurrent.Executor, android.ranging.RangingManager.RangingCapabilitiesCallback). + + + + Portions of this page are modifications based on work created and shared by the + Android Open Source Project + and used according to terms described in the + Creative Commons 2.5 Attribution License. + @@ -327,9 +358,23 @@ - To be added. - To be added. - To be added. + The capabilities callback to unregister. + Unregisters a previously registered ranging capabilities callback. + + Unregisters a previously registered ranging capabilities callback. + After it is unregistered, the callback no longer receives ranging capabilities + updates. + + + Java documentation for android.ranging.RangingManager.unregisterCapabilitiesCallback(android.ranging.RangingManager.RangingCapabilitiesCallback). + + + + Portions of this page are modifications based on work created and shared by the + Android Open Source Project + and used according to terms described in the + Creative Commons 2.5 Attribution License. + diff --git a/docs/xml/Android.Ranging/RangingSession.xml b/docs/xml/Android.Ranging/RangingSession.xml index afb53696f..77a999f2e 100644 --- a/docs/xml/Android.Ranging/RangingSession.xml +++ b/docs/xml/Android.Ranging/RangingSession.xml @@ -146,8 +146,22 @@ - To be added. - To be added. + Closes this resource and relinquishes its underlying resources. + + Closes this resource and relinquishes its underlying resources. + This method is invoked automatically for objects managed by a + try-with-resources statement. + + + Java documentation for android.ranging.RangingSession.close(). + + + + Portions of this page are modifications based on work created and shared by the + Android Open Source Project + and used according to terms described in the + Creative Commons 2.5 Attribution License. + From 2bbb977be26867272f51dcd6d80e2adcebcd4843 Mon Sep 17 00:00:00 2001 From: Jonathan Peppers Date: Sun, 16 Aug 2026 09:06:59 -0500 Subject: [PATCH 2/3] Address ranging documentation review Refs #159 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/xml/Android.Ranging/RangingManager.xml | 2 +- docs/xml/Android.Ranging/RangingSession.xml | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/xml/Android.Ranging/RangingManager.xml b/docs/xml/Android.Ranging/RangingManager.xml index e67cd1145..658aa442a 100644 --- a/docs/xml/Android.Ranging/RangingManager.xml +++ b/docs/xml/Android.Ranging/RangingManager.xml @@ -258,7 +258,7 @@ Registers a callback to receive ranging capabilities updates. Callback events are dispatched through the provided executor, which controls the - thread on which they run. Use Context.getMainExecutor() to dispatch events on + thread on which they run. Use Context.getMainExecutor() to dispatch events on the application's main thread, or provide an executor for another suitable thread. diff --git a/docs/xml/Android.Ranging/RangingSession.xml b/docs/xml/Android.Ranging/RangingSession.xml index 77a999f2e..b5625098f 100644 --- a/docs/xml/Android.Ranging/RangingSession.xml +++ b/docs/xml/Android.Ranging/RangingSession.xml @@ -146,11 +146,11 @@ - Closes this resource and relinquishes its underlying resources. + Closes this resource, relinquishing any underlying resources. - Closes this resource and relinquishes its underlying resources. - This method is invoked automatically for objects managed by a - try-with-resources statement. + Closes this resource, relinquishing any underlying resources. + This method is invoked automatically on objects managed by the + try-with-resources statement. Java documentation for android.ranging.RangingSession.close(). From a2b0b76c018cbaa42f1caf728fb5777f8e47fd79 Mon Sep 17 00:00:00 2001 From: Jonathan Peppers Date: Mon, 17 Aug 2026 08:32:30 -0500 Subject: [PATCH 3/3] Correct ranging API contracts Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 59d8bac3-4d1e-4af6-9b60-b12951db8cec --- docs/xml/Android.Ranging/RangingManager.xml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/xml/Android.Ranging/RangingManager.xml b/docs/xml/Android.Ranging/RangingManager.xml index 658aa442a..9cd94d874 100644 --- a/docs/xml/Android.Ranging/RangingManager.xml +++ b/docs/xml/Android.Ranging/RangingManager.xml @@ -175,7 +175,8 @@ The executor on which the callback will be invoked. The callback to receive session-related events. Creates a new ranging session. - A RangingSession that can initiate, manage, and stop ranging operations. + A RangingSession that can initiate, manage, and stop ranging operations if + the session is successfully created; otherwise, null. Creates a new ranging session. A ranging session enables the application to perform ranging operations using available technologies such as Ultra-Wideband (UWB) or Wi-Fi @@ -362,8 +363,9 @@ Unregisters a previously registered ranging capabilities callback. Unregisters a previously registered ranging capabilities callback. - After it is unregistered, the callback no longer receives ranging capabilities - updates. + After it is unregistered, no further ranging capabilities updates are dispatched to + the callback. Callbacks that were already queued on the callback's executor, or are + already in progress, can still be delivered after this method returns. Java documentation for android.ranging.RangingManager.unregisterCapabilitiesCallback(android.ranging.RangingManager.RangingCapabilitiesCallback).