Add UWB RangingSession

Introduces the UWB RangingSession used to control ranging. Also
introduces a function to UwbManager to start ranging.

Bug: 170323306
Test: Builds
Change-Id: I014ebb203cff064b3009b246acb967d018833b06

core/java/android/uwb/RangingSession.java

@@ -0,0 +1,148 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.uwb;
+
+import android.annotation.IntDef;
+import android.os.PersistableBundle;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.concurrent.Executor;
+
+/**
+ * This class provides a way to control an active UWB ranging session.
+ * <p>It also defines the required {@link RangingSession.Callback} that must be implemented
+ * in order to be notified of UWB ranging results and status events related to the
+ * {@link RangingSession}.
+ *
+ * <p>To get an instance of {@link RangingSession}, first use
+ * {@link UwbManager#openRangingSession(RangingParams, Executor, Callback)} to request to open a
+ * session. Once the session is opened, a {@link RangingSession} object is provided through
+ * {@link RangingSession.Callback#onOpenSuccess(RangingSession, PersistableBundle)}. If opening a
+ * session fails, the failure is reported through {@link RangingSession.Callback#onClosed(int)} with
+ * the failure reason.
+ *
+ * @hide
+ */
+public final class RangingSession implements AutoCloseable {
+    /**
+     * Interface for receiving {@link RangingSession} events
+     */
+    public interface Callback {
+        /**
+         * Invoked when {@link UwbManager#openRangingSession(RangingParams, Executor, Callback)}
+         * is successful
+         *
+         * @param session the newly opened {@link RangingSession}
+         * @param sessionInfo session specific parameters from lower layers
+         */
+        void onOpenSuccess(RangingSession session, PersistableBundle sessionInfo);
+
+        @Retention(RetentionPolicy.SOURCE)
+        @IntDef(value = {
+                CLOSE_REASON_UNKNOWN,
+                CLOSE_REASON_LOCAL_CLOSE_API,
+                CLOSE_REASON_LOCAL_BAD_PARAMETERS,
+                CLOSE_REASON_LOCAL_GENERIC_ERROR,
+                CLOSE_REASON_LOCAL_MAX_SESSIONS_REACHED,
+                CLOSE_REASON_LOCAL_SYSTEM_POLICY,
+                CLOSE_REASON_REMOTE_GENERIC_ERROR,
+                CLOSE_REASON_REMOTE_REQUEST})
+        @interface CloseReason {}
+
+        /**
+         * Indicates that the session was closed or failed to open due to an unknown reason
+         */
+        int CLOSE_REASON_UNKNOWN = 0;
+
+        /**
+         * Indicates that the session was closed or failed to open because
+         * {@link AutoCloseable#close()} or {@link RangingSession#close()} was called
+         */
+        int CLOSE_REASON_LOCAL_CLOSE_API = 1;
+
+        /**
+         * Indicates that the session failed to open due to erroneous parameters passed
+         * to {@link UwbManager#openRangingSession(RangingParams, Executor, Callback)}
+         */
+        int CLOSE_REASON_LOCAL_BAD_PARAMETERS = 2;
+
+        /**
+         * Indicates that the session was closed due to some local error on this device besides the
+         * error code already listed
+         */
+        int CLOSE_REASON_LOCAL_GENERIC_ERROR = 3;
+
+        /**
+         * Indicates that the session failed to open because the number of currently open sessions
+         * is equal to {@link UwbManager#getMaxSimultaneousSessions()}
+         */
+        int CLOSE_REASON_LOCAL_MAX_SESSIONS_REACHED = 4;
+
+        /**
+         * Indicates that the session was closed or failed to open due to local system policy, such
+         * as privacy policy, power management policy, permissions, and more.
+         */
+        int CLOSE_REASON_LOCAL_SYSTEM_POLICY = 5;
+
+        /**
+         * Indicates that the session was closed or failed to open due to an error with the remote
+         * device besides error codes already listed.
+         */
+        int CLOSE_REASON_REMOTE_GENERIC_ERROR = 6;
+
+        /**
+         * Indicates that the session was closed or failed to open due to an explicit request from
+         * the remote device.
+         */
+        int CLOSE_REASON_REMOTE_REQUEST = 7;
+
+        /**
+         * Invoked when session is either closed spontaneously, or per user request via
+         * {@link RangingSession#close()} or {@link AutoCloseable#close()}, or when session failed
+         * to open.
+         *
+         * @param reason reason for the session closure
+         */
+        void onClosed(@CloseReason int reason);
+
+        /**
+         * Called once per ranging interval even when a ranging measurement fails
+         *
+         * @param rangingReport ranging report for this interval's measurements
+         */
+        void onReportReceived(RangingReport rangingReport);
+    }
+
+    /**
+     * Close the ranging session
+     * <p>If this session is currently open, it will close and stop the session.
+     * <p>If the session is in the process of being opened, it will attempt to stop the session from
+     * being opened.
+     * <p>If the session is already closed, the registered {@link Callback#onClosed(int)} callback
+     * will still be invoked.
+     *
+     * <p>{@link Callback#onClosed(int)} will be invoked using the same callback
+     * object given to {@link UwbManager#openRangingSession(RangingParams, Executor, Callback)} when
+     * the {@link RangingSession} was opened. The callback will be invoked after each call to
+     * {@link #close()}, even if the {@link RangingSession} is already closed.
+     */
+    @Override
+    public void close() {
+        throw new UnsupportedOperationException();
+    }
+}

core/java/android/uwb/UwbManager.java

@@ -266,4 +266,33 @@ public final class UwbManager {
     public int getMaxRemoteDevicesPerResponderSession() {
         throw new UnsupportedOperationException();
     }
+
+    /**
+     * Open a {@link RangingSession} with the given parameters
+     * <p>This function is asynchronous and will return before ranging begins. The
+     * {@link RangingSession.Callback#onOpenSuccess(RangingSession, PersistableBundle)} function is
+     * called with a {@link RangingSession} object used to control ranging when the session is
+     * successfully opened.
+     *
+     * <p>If a session cannot be opened, then {@link RangingSession.Callback#onClosed(int)} will be
+     * invoked with the appropriate {@link RangingSession.Callback.CloseReason}.
+     *
+     * <p>An open {@link RangingSession} will be automatically closed if client application process
+     * dies.
+     *
+     * @param params {@link RangingParams} used to initialize this {@link RangingSession}
+     * @param executor {@link Executor} to run callbacks
+     * @param callbacks {@link RangingSession.Callback} to associate with the
+     *                  {@link RangingSession} that is being opened.
+     *
+     * @return an {@link AutoCloseable} that is able to be used to close or cancel the opening of a
+     *         {@link RangingSession} that has been requested through {@link #openRangingSession}
+     *         but has not yet been made available by
+     *         {@link RangingSession.Callback#onOpenSuccess}.
+     */
+    @NonNull
+    public AutoCloseable openRangingSession(@NonNull RangingParams params,
+            @NonNull Executor executor, @NonNull RangingSession.Callback callbacks) {
+        throw new UnsupportedOperationException();
+    }
 }