Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5f566d68 authored by Brian Stack's avatar Brian Stack
Browse files

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
parent 17e71839
Loading
Loading
Loading
Loading
+148 −0
Original line number Diff line number Diff line
/*
 * 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();
    }
}
+29 −0
Original line number Diff line number Diff line
@@ -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();
    }
}