diff options
Diffstat (limited to 'core/java/android')
| -rw-r--r-- | core/java/android/uwb/IUwbAdapter.aidl | 84 | ||||
| -rw-r--r-- | core/java/android/uwb/IUwbRangingCallbacks.aidl | 67 | ||||
| -rw-r--r-- | core/java/android/uwb/RangingChangeReason.aidl (renamed from core/java/android/uwb/CloseReason.aidl) | 25 | ||||
| -rw-r--r-- | core/java/android/uwb/RangingManager.java | 154 | ||||
| -rw-r--r-- | core/java/android/uwb/RangingSession.java | 363 | ||||
| -rw-r--r-- | core/java/android/uwb/StartFailureReason.aidl | 52 | ||||
| -rw-r--r-- | core/java/android/uwb/UwbManager.java | 14 |
7 files changed, 564 insertions, 195 deletions
diff --git a/core/java/android/uwb/IUwbAdapter.aidl b/core/java/android/uwb/IUwbAdapter.aidl index 2c8b2e462510..b9c55081a103 100644 --- a/core/java/android/uwb/IUwbAdapter.aidl +++ b/core/java/android/uwb/IUwbAdapter.aidl @@ -119,42 +119,96 @@ interface IUwbAdapter { PersistableBundle getSpecificationInfo(); /** - * Request to start a new ranging session + * Request to open a new ranging session * - * This function must return before calling IUwbAdapterCallbacks - * #onRangingStarted, #onRangingClosed, or #onRangingResult. + * This function must return before calling any functions in + * IUwbAdapterCallbacks. * - * A ranging session does not need to be started before returning. + * This function does not start the ranging session, but all necessary + * components must be initialized and ready to start a new ranging + * session prior to calling IUwbAdapterCallback#onRangingOpened. * - * IUwbAdapterCallbacks#onRangingStarted must be called within - * RANGING_SESSION_START_THRESHOLD_MS milliseconds of #startRanging being called - * if the ranging session is scheduled to start successfully. + * IUwbAdapterCallbacks#onRangingOpened must be called within + * RANGING_SESSION_OPEN_THRESHOLD_MS milliseconds of #openRanging being + * called if the ranging session is opened successfully. * - * IUwbAdapterCallbacks#onRangingStartFailed must be called within - * RANGING_SESSION_START_THRESHOLD_MS milliseconds of #startRanging being called - * if the ranging session fails to be scheduled to start successfully. + * IUwbAdapterCallbacks#onRangingOpenFailed must be called within + * RANGING_SESSION_OPEN_THRESHOLD_MS milliseconds of #openRanging being called + * if the ranging session fails to be opened. * * @param rangingCallbacks the callbacks used to deliver ranging information * @param parameters the configuration to use for ranging * @return a SessionHandle used to identify this ranging request */ - SessionHandle startRanging(in IUwbRangingCallbacks rangingCallbacks, - in PersistableBundle parameters); + SessionHandle openRanging(in IUwbRangingCallbacks rangingCallbacks, + in PersistableBundle parameters); + + /** + * Request to start ranging + * + * IUwbAdapterCallbacks#onRangingStarted must be called within + * RANGING_SESSION_START_THRESHOLD_MS milliseconds of #startRanging being + * called if the ranging session starts successfully. + * + * IUwbAdapterCallbacks#onRangingStartFailed must be called within + * RANGING_SESSION_START_THRESHOLD_MS milliseconds of #startRanging being + * called if the ranging session fails to be started. + * + * @param sessionHandle the session handle to start ranging for + * @param parameters additional configuration required to start ranging + */ + void startRanging(in SessionHandle sessionHandle, + in PersistableBundle parameters); + + /** + * Request to reconfigure ranging + * + * IUwbAdapterCallbacks#onRangingReconfigured must be called after + * successfully reconfiguring the session. + * + * IUwbAdapterCallbacks#onRangingReconfigureFailed must be called after + * failing to reconfigure the session. + * + * A session must not be modified by a failed call to #reconfigureRanging. + * + * @param sessionHandle the session handle to start ranging for + * @param parameters the parameters to reconfigure and their new values + */ + void reconfigureRanging(in SessionHandle sessionHandle, + in PersistableBundle parameters); + + /** + * Request to stop ranging + * + * IUwbAdapterCallbacks#onRangingStopped must be called after + * successfully stopping the session. + * + * IUwbAdapterCallbacks#onRangingStopFailed must be called after failing + * to stop the session. + * + * @param sessionHandle the session handle to stop ranging for + */ + void stopRanging(in SessionHandle sessionHandle); /** - * Stop and close ranging for the session associated with the given handle + * Close ranging for the session associated with the given handle * * Calling with an invalid handle or a handle that has already been closed * is a no-op. * * IUwbAdapterCallbacks#onRangingClosed must be called within - * RANGING_SESSION_CLOSE_THRESHOLD_MS of #stopRanging being called. + * RANGING_SESSION_CLOSE_THRESHOLD_MS of #closeRanging being called. * - * @param sessionHandle the session handle to stop ranging for + * @param sessionHandle the session handle to close ranging for */ void closeRanging(in SessionHandle sessionHandle); /** + * The maximum allowed time to open a ranging session. + */ + const int RANGING_SESSION_OPEN_THRESHOLD_MS = 3000; // Value TBD + + /** * The maximum allowed time to start a ranging session. */ const int RANGING_SESSION_START_THRESHOLD_MS = 3000; // Value TBD diff --git a/core/java/android/uwb/IUwbRangingCallbacks.aidl b/core/java/android/uwb/IUwbRangingCallbacks.aidl index 1fc3bfd818c3..f71f3ff7ad44 100644 --- a/core/java/android/uwb/IUwbRangingCallbacks.aidl +++ b/core/java/android/uwb/IUwbRangingCallbacks.aidl @@ -17,16 +17,33 @@ package android.uwb; import android.os.PersistableBundle; -import android.uwb.CloseReason; +import android.uwb.RangingChangeReason; import android.uwb.RangingReport; import android.uwb.SessionHandle; -import android.uwb.StartFailureReason; /** * @hide */ interface IUwbRangingCallbacks { /** + * Called when the ranging session has been opened + * + * @param sessionHandle the session the callback is being invoked for + */ + void onRangingOpened(in SessionHandle sessionHandle); + + /** + * Called when a ranging session fails to start + * + * @param sessionHandle the session the callback is being invoked for + * @param reason the reason the session failed to start + * @param parameters protocol specific parameters + */ + void onRangingOpenFailed(in SessionHandle sessionHandle, + RangingChangeReason reason, + in PersistableBundle parameters); + + /** * Called when ranging has started * * May output parameters generated by the lower layers that must be sent to the @@ -47,8 +64,49 @@ interface IUwbRangingCallbacks { * @param reason the reason the session failed to start * @param parameters protocol specific parameters */ - void onRangingStartFailed(in SessionHandle sessionHandle, StartFailureReason reason, + void onRangingStartFailed(in SessionHandle sessionHandle, + RangingChangeReason reason, in PersistableBundle parameters); + + /** + * Called when ranging has been reconfigured + * + * @param sessionHandle the session the callback is being invoked for + * @param parameters the updated ranging configuration + */ + void onRangingReconfigured(in SessionHandle sessionHandle, + in PersistableBundle parameters); + + /** + * Called when a ranging session fails to be reconfigured + * + * @param sessionHandle the session the callback is being invoked for + * @param reason the reason the session failed to reconfigure + * @param parameters protocol specific parameters + */ + void onRangingReconfigureFailed(in SessionHandle sessionHandle, + RangingChangeReason reason, + in PersistableBundle parameters); + + /** + * Called when the ranging session has been stopped + * + * @param sessionHandle the session the callback is being invoked for + */ + + void onRangingStopped(in SessionHandle sessionHandle); + + /** + * Called when a ranging session fails to stop + * + * @param sessionHandle the session the callback is being invoked for + * @param reason the reason the session failed to stop + * @param parameters protocol specific parameters + */ + void onRangingStopFailed(in SessionHandle sessionHandle, + RangingChangeReason reason, + in PersistableBundle parameters); + /** * Called when a ranging session is closed * @@ -56,7 +114,8 @@ interface IUwbRangingCallbacks { * @param reason the reason the session was closed * @param parameters protocol specific parameters */ - void onRangingClosed(in SessionHandle sessionHandle, CloseReason reason, + void onRangingClosed(in SessionHandle sessionHandle, + RangingChangeReason reason, in PersistableBundle parameters); /** diff --git a/core/java/android/uwb/CloseReason.aidl b/core/java/android/uwb/RangingChangeReason.aidl index bef129e2c1c7..19d4b3949d07 100644 --- a/core/java/android/uwb/CloseReason.aidl +++ b/core/java/android/uwb/RangingChangeReason.aidl @@ -20,39 +20,44 @@ package android.uwb; * @hide */ @Backing(type="int") -enum CloseReason { +enum RangingChangeReason { /** * Unknown reason */ UNKNOWN, /** - * A local API call triggered the close, such as a call to - * IUwbAdapter.stopRanging. + * A local API call triggered the change, such as a call to + * IUwbAdapter.closeRanging. */ LOCAL_API, /** - * The maximum number of sessions has been reached. This error may be generated - * for an active session if a higher priority session begins. + * The maximum number of sessions has been reached. This may be generated for + * an active session if a higher priority session begins. */ MAX_SESSIONS_REACHED, /** - * The system state has changed resulting in the session ending (e.g. the user - * disables UWB, or the user's locale changes and an active channel is no longer - * permitted to be used). + * The system state has changed resulting in the session changing (e.g. the + * user disables UWB, or the user's locale changes and an active channel is no + * longer permitted to be used). */ SYSTEM_POLICY, /** - * The remote device has requested to terminate the session + * The remote device has requested to change the session */ REMOTE_REQUEST, /** - * The session was closed for a protocol specific reason + * The session changed for a protocol specific reason */ PROTOCOL_SPECIFIC, + + /** + * The provided parameters were invalid + */ + BAD_PARAMETERS, } diff --git a/core/java/android/uwb/RangingManager.java b/core/java/android/uwb/RangingManager.java index a9bf4abe566a..5ac95d49c1bb 100644 --- a/core/java/android/uwb/RangingManager.java +++ b/core/java/android/uwb/RangingManager.java @@ -50,7 +50,7 @@ public class RangingManager extends android.uwb.IUwbRangingCallbacks.Stub { @NonNull RangingSession.Callback callbacks) { SessionHandle sessionHandle; try { - sessionHandle = mAdapter.startRanging(this, params); + sessionHandle = mAdapter.openRanging(this, params); } catch (RemoteException e) { throw e.rethrowFromSystemServer(); } @@ -59,7 +59,7 @@ public class RangingManager extends android.uwb.IUwbRangingCallbacks.Stub { if (hasSession(sessionHandle)) { Log.w(TAG, "Newly created session unexpectedly reuses an active SessionHandle"); executor.execute(() -> callbacks.onClosed( - RangingSession.Callback.CLOSE_REASON_LOCAL_GENERIC_ERROR, + RangingSession.Callback.REASON_GENERIC_ERROR, new PersistableBundle())); } @@ -75,6 +75,67 @@ public class RangingManager extends android.uwb.IUwbRangingCallbacks.Stub { } @Override + public void onRangingOpened(SessionHandle sessionHandle) { + synchronized (this) { + if (!hasSession(sessionHandle)) { + Log.w(TAG, + "onRangingOpened - received unexpected SessionHandle: " + sessionHandle); + return; + } + + RangingSession session = mRangingSessionTable.get(sessionHandle); + session.onRangingOpened(); + } + } + + @Override + public void onRangingOpenFailed(SessionHandle sessionHandle, @RangingChangeReason int reason, + PersistableBundle parameters) { + synchronized (this) { + if (!hasSession(sessionHandle)) { + Log.w(TAG, + "onRangingOpened - received unexpected SessionHandle: " + sessionHandle); + return; + } + + RangingSession session = mRangingSessionTable.get(sessionHandle); + session.onRangingOpenFailed(convertToReason(reason), parameters); + mRangingSessionTable.remove(sessionHandle); + } + } + + @Override + public void onRangingReconfigured(SessionHandle sessionHandle, PersistableBundle parameters) { + synchronized (this) { + if (!hasSession(sessionHandle)) { + Log.w(TAG, + "onRangingReconfigured - received unexpected SessionHandle: " + + sessionHandle); + return; + } + + RangingSession session = mRangingSessionTable.get(sessionHandle); + session.onRangingReconfigured(parameters); + } + } + + @Override + public void onRangingReconfigureFailed(SessionHandle sessionHandle, + @RangingChangeReason int reason, PersistableBundle params) { + synchronized (this) { + if (!hasSession(sessionHandle)) { + Log.w(TAG, "onRangingStartFailed - received unexpected SessionHandle: " + + sessionHandle); + return; + } + + RangingSession session = mRangingSessionTable.get(sessionHandle); + session.onRangingReconfigureFailed(convertToReason(reason), params); + } + } + + + @Override public void onRangingStarted(SessionHandle sessionHandle, PersistableBundle parameters) { synchronized (this) { if (!hasSession(sessionHandle)) { @@ -89,7 +150,7 @@ public class RangingManager extends android.uwb.IUwbRangingCallbacks.Stub { } @Override - public void onRangingStartFailed(SessionHandle sessionHandle, int reason, + public void onRangingStartFailed(SessionHandle sessionHandle, @RangingChangeReason int reason, PersistableBundle params) { synchronized (this) { if (!hasSession(sessionHandle)) { @@ -99,13 +160,42 @@ public class RangingManager extends android.uwb.IUwbRangingCallbacks.Stub { } RangingSession session = mRangingSessionTable.get(sessionHandle); - session.onRangingClosed(convertStartFailureToCloseReason(reason), params); - mRangingSessionTable.remove(sessionHandle); + session.onRangingStartFailed(convertToReason(reason), params); + } + } + + @Override + public void onRangingStopped(SessionHandle sessionHandle) { + synchronized (this) { + if (!hasSession(sessionHandle)) { + Log.w(TAG, "onRangingStopped - received unexpected SessionHandle: " + + sessionHandle); + return; + } + + RangingSession session = mRangingSessionTable.get(sessionHandle); + session.onRangingStopped(); } } @Override - public void onRangingClosed(SessionHandle sessionHandle, int reason, PersistableBundle params) { + public void onRangingStopFailed(SessionHandle sessionHandle, @RangingChangeReason int reason, + PersistableBundle parameters) { + synchronized (this) { + if (!hasSession(sessionHandle)) { + Log.w(TAG, "onRangingStopFailed - received unexpected SessionHandle: " + + sessionHandle); + return; + } + + RangingSession session = mRangingSessionTable.get(sessionHandle); + session.onRangingStopFailed(convertToReason(reason), parameters); + } + } + + @Override + public void onRangingClosed(SessionHandle sessionHandle, @RangingChangeReason int reason, + PersistableBundle params) { synchronized (this) { if (!hasSession(sessionHandle)) { Log.w(TAG, "onRangingClosed - received unexpected SessionHandle: " + sessionHandle); @@ -113,7 +203,7 @@ public class RangingManager extends android.uwb.IUwbRangingCallbacks.Stub { } RangingSession session = mRangingSessionTable.get(sessionHandle); - session.onRangingClosed(convertToCloseReason(reason), params); + session.onRangingClosed(convertToReason(reason), params); mRangingSessionTable.remove(sessionHandle); } } @@ -131,48 +221,30 @@ public class RangingManager extends android.uwb.IUwbRangingCallbacks.Stub { } } - @RangingSession.Callback.CloseReason - private static int convertToCloseReason(@CloseReason int reason) { + @RangingSession.Callback.Reason + private static int convertToReason(@RangingChangeReason int reason) { switch (reason) { - case CloseReason.LOCAL_API: - return RangingSession.Callback.CLOSE_REASON_LOCAL_CLOSE_API; - - case CloseReason.MAX_SESSIONS_REACHED: - return RangingSession.Callback.CLOSE_REASON_LOCAL_MAX_SESSIONS_REACHED; - - case CloseReason.SYSTEM_POLICY: - return RangingSession.Callback.CLOSE_REASON_LOCAL_SYSTEM_POLICY; + case RangingChangeReason.LOCAL_API: + return RangingSession.Callback.REASON_LOCAL_REQUEST; - case CloseReason.REMOTE_REQUEST: - return RangingSession.Callback.CLOSE_REASON_REMOTE_REQUEST; + case RangingChangeReason.MAX_SESSIONS_REACHED: + return RangingSession.Callback.REASON_MAX_SESSIONS_REACHED; - case CloseReason.PROTOCOL_SPECIFIC: - return RangingSession.Callback.CLOSE_REASON_PROTOCOL_SPECIFIC; - - case CloseReason.UNKNOWN: - default: - return RangingSession.Callback.CLOSE_REASON_UNKNOWN; - } - } - - @RangingSession.Callback.CloseReason - private static int convertStartFailureToCloseReason(@StartFailureReason int reason) { - switch (reason) { - case StartFailureReason.BAD_PARAMETERS: - return RangingSession.Callback.CLOSE_REASON_LOCAL_BAD_PARAMETERS; + case RangingChangeReason.SYSTEM_POLICY: + return RangingSession.Callback.REASON_SYSTEM_POLICY; - case StartFailureReason.MAX_SESSIONS_REACHED: - return RangingSession.Callback.CLOSE_REASON_LOCAL_MAX_SESSIONS_REACHED; + case RangingChangeReason.REMOTE_REQUEST: + return RangingSession.Callback.REASON_REMOTE_REQUEST; - case StartFailureReason.SYSTEM_POLICY: - return RangingSession.Callback.CLOSE_REASON_LOCAL_SYSTEM_POLICY; + case RangingChangeReason.PROTOCOL_SPECIFIC: + return RangingSession.Callback.REASON_PROTOCOL_SPECIFIC_ERROR; - case StartFailureReason.PROTOCOL_SPECIFIC: - return RangingSession.Callback.CLOSE_REASON_PROTOCOL_SPECIFIC; + case RangingChangeReason.BAD_PARAMETERS: + return RangingSession.Callback.REASON_BAD_PARAMETERS; - case StartFailureReason.UNKNOWN: + case RangingChangeReason.UNKNOWN: default: - return RangingSession.Callback.CLOSE_REASON_UNKNOWN; + return RangingSession.Callback.REASON_UNKNOWN; } } } diff --git a/core/java/android/uwb/RangingSession.java b/core/java/android/uwb/RangingSession.java index b0dbd85c0812..0f87af415825 100644 --- a/core/java/android/uwb/RangingSession.java +++ b/core/java/android/uwb/RangingSession.java @@ -36,9 +36,9 @@ import java.util.concurrent.Executor; * <p>To get an instance of {@link RangingSession}, first use * {@link UwbManager#openRangingSession(PersistableBundle, 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, PersistableBundle)} with the failure reason. + * {@link RangingSession.Callback#onOpened(RangingSession)}. If opening a session fails, the failure + * is reported through {@link RangingSession.Callback#onOpenFailed(int, PersistableBundle)} with the + * failure reason. * * @hide */ @@ -50,103 +50,162 @@ public final class RangingSession implements AutoCloseable { private final Callback mCallback; private enum State { + /** + * The state of the {@link RangingSession} until + * {@link RangingSession.Callback#onOpened(RangingSession)} is invoked + */ INIT, - OPEN, - CLOSED, + + /** + * The {@link RangingSession} is initialized and ready to begin ranging + */ + IDLE, + + /** + * The {@link RangingSession} is actively ranging + */ + ACTIVE, + + /** + * The {@link RangingSession} is closed and may not be used for ranging. + */ + CLOSED } - private State mState; + private State mState = State.INIT; /** * Interface for receiving {@link RangingSession} events */ public interface Callback { /** - * Invoked when {@link UwbManager#openRangingSession(PersistableBundle, Executor, Callback)} - * is successful - * - * @param session the newly opened {@link RangingSession} - * @param sessionInfo session specific parameters from lower layers - */ - void onOpenSuccess(@NonNull RangingSession session, @NonNull PersistableBundle sessionInfo); - - /** * @hide */ @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 {} + REASON_UNKNOWN, + REASON_LOCAL_REQUEST, + REASON_REMOTE_REQUEST, + REASON_BAD_PARAMETERS, + REASON_GENERIC_ERROR, + REASON_MAX_SESSIONS_REACHED, + REASON_SYSTEM_POLICY, + REASON_PROTOCOL_SPECIFIC_ERROR}) + @interface Reason {} /** * Indicates that the session was closed or failed to open due to an unknown reason */ - int CLOSE_REASON_UNKNOWN = 0; + int 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; + int REASON_LOCAL_REQUEST = 1; /** - * Indicates that the session failed to open due to erroneous parameters passed - * to {@link UwbManager#openRangingSession(PersistableBundle, Executor, Callback)} + * Indicates that the session was closed or failed to open due to an explicit request from + * the remote device. */ - int CLOSE_REASON_LOCAL_BAD_PARAMETERS = 2; + int REASON_REMOTE_REQUEST = 2; /** - * Indicates that the session was closed due to some local error on this device besides the - * error code already listed + * Indicates that the session was closed or failed to open due to erroneous parameters */ - int CLOSE_REASON_LOCAL_GENERIC_ERROR = 3; + int REASON_BAD_PARAMETERS = 3; /** - * Indicates that the session failed to open because the number of currently open sessions - * is equal to {@link UwbManager#getMaxSimultaneousSessions()} + * Indicates an error on this device besides the error code already listed */ - int CLOSE_REASON_LOCAL_MAX_SESSIONS_REACHED = 4; + int REASON_GENERIC_ERROR = 4; /** - * Indicates that the session was closed or failed to open due to local system policy, such + * Indicates that the number of currently open sessions is equal to + * {@link UwbManager#getMaxSimultaneousSessions()} and additional sessions may not be + * opened. + */ + int REASON_MAX_SESSIONS_REACHED = 5; + + /** + * Indicates that the local system policy caused the change, such * as privacy policy, power management policy, permissions, and more. */ - int CLOSE_REASON_LOCAL_SYSTEM_POLICY = 5; + int REASON_SYSTEM_POLICY = 6; /** - * Indicates that the session was closed or failed to open due to an error with the remote - * device besides error codes already listed. + * Indicates a protocol specific error. The associated {@link PersistableBundle} should be + * consulted for additional information. */ - int CLOSE_REASON_REMOTE_GENERIC_ERROR = 6; + int REASON_PROTOCOL_SPECIFIC_ERROR = 7; /** - * Indicates that the session was closed or failed to open due to an explicit request from - * the remote device. + * Invoked when {@link UwbManager#openRangingSession(PersistableBundle, Executor, Callback)} + * is successful + * + * @param session the newly opened {@link RangingSession} + */ + void onOpened(@NonNull RangingSession session); + + /** + * Invoked if {@link UwbManager#openRangingSession(PersistableBundle, Executor, Callback)}} + * fails + * + * @param reason the failure reason + * @param params protocol specific parameters + */ + void onOpenFailed(@Reason int reason, @NonNull PersistableBundle params); + + /** + * Invoked when {@link RangingSession#start(PersistableBundle)} is successful + * @param sessionInfo session specific parameters from the lower layers + */ + void onStarted(@NonNull PersistableBundle sessionInfo); + + /** + * Invoked when {@link RangingSession#start(PersistableBundle)} fails + * + * @param reason the failure reason + * @param params protocol specific parameters + */ + void onStartFailed(@Reason int reason, @NonNull PersistableBundle params); + + /** + * Invoked when a request to reconfigure the session succeeds + * + * @param params the updated ranging configuration + */ + void onReconfigured(@NonNull PersistableBundle params); + + /** + * Invoked when a request to reconfigure the session fails + * + * @param reason reason the session failed to be reconfigured + * @param params protocol specific failure reasons */ - int CLOSE_REASON_REMOTE_REQUEST = 7; + void onReconfigureFailed(@Reason int reason, @NonNull PersistableBundle params); /** - * Indicates that the session was closed for a protocol specific reason. The associated - * {@link PersistableBundle} should be consulted for additional information. + * Invoked when a request to stop the session succeeds */ - int CLOSE_REASON_PROTOCOL_SPECIFIC = 8; + void onStopped(); /** + * Invoked when a request to stop the session fails + * + * @param reason reason the session failed to be stopped + * @param params protocol specific failure reasons + */ + void onStopFailed(@Reason int reason, @NonNull PersistableBundle params); + + /** * 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. + * {@link RangingSession#close()} or {@link AutoCloseable#close()}. * * @param reason reason for the session closure * @param parameters protocol specific parameters related to the close reason */ - void onClosed(@CloseReason int reason, @NonNull PersistableBundle parameters); + void onClosed(@Reason int reason, @NonNull PersistableBundle parameters); /** * Called once per ranging interval even when a ranging measurement fails @@ -172,12 +231,95 @@ public final class RangingSession implements AutoCloseable { * @hide */ public boolean isOpen() { - return mState == State.OPEN; + return mState == State.IDLE || mState == State.ACTIVE; + } + + /** + * Begins ranging for the session. + * + * <p>On successfully starting a ranging session, + * {@link RangingSession.Callback#onStarted(PersistableBundle)} is invoked. + * + * <p>On failure to start the session, + * {@link RangingSession.Callback#onStartFailed(int, PersistableBundle)} is invoked. + * + * @param params configuration parameters for starting the session + */ + public void start(@NonNull PersistableBundle params) { + if (mState != State.IDLE) { + throw new IllegalStateException(); + } + + try { + mAdapter.startRanging(mSessionHandle, params); + } catch (RemoteException e) { + throw e.rethrowFromSystemServer(); + } + } + + /** + * Attempts to reconfigure the session with the given parameters + * <p>This call may be made when the session is open. + * + * <p>On successfully reconfiguring the session + * {@link RangingSession.Callback#onReconfigured(PersistableBundle)} is invoked. + * + * <p>On failure to reconfigure the session, + * {@link RangingSession.Callback#onReconfigureFailed(int, PersistableBundle)} is invoked. + * + * @param params the parameters to reconfigure and their new values + */ + public void reconfigure(@NonNull PersistableBundle params) { + if (mState != State.ACTIVE && mState != State.IDLE) { + throw new IllegalStateException(); + } + + try { + mAdapter.reconfigureRanging(mSessionHandle, params); + } catch (RemoteException e) { + throw e.rethrowFromSystemServer(); + } + } + + /** + * Stops actively ranging + * + * <p>A session that has been stopped may be resumed by calling + * {@link RangingSession#start(PersistableBundle)} without the need to open a new session. + * + * <p>Stopping a {@link RangingSession} is useful when the lower layers should not discard + * the parameters of the session, or when a session needs to be able to be resumed quickly. + * + * <p>If the {@link RangingSession} is no longer needed, use {@link RangingSession#close()} to + * completely close the session and allow lower layers of the stack to perform necessarily + * cleanup. + * + * <p>Stopped sessions may be closed by the system at any time. In such a case, + * {@link RangingSession.Callback#onClosed(int, PersistableBundle)} is invoked. + * + * <p>On failure to stop the session, + * {@link RangingSession.Callback#onStopFailed(int, PersistableBundle)} is invoked. + */ + public void stop() { + if (mState != State.ACTIVE) { + throw new IllegalStateException(); + } + + try { + mAdapter.stopRanging(mSessionHandle); + } catch (RemoteException e) { + throw e.rethrowFromSystemServer(); + } } /** * Close the ranging session - * <p>If this session is currently open, it will close and stop the session. + * + * <p>After calling this function, in order resume ranging, a new {@link RangingSession} must + * be opened by calling + * {@link UwbManager#openRangingSession(PersistableBundle, Executor, Callback)}. + * + * <p>If this session is currently ranging, it will stop and close 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 @@ -192,7 +334,7 @@ public final class RangingSession implements AutoCloseable { public void close() { if (mState == State.CLOSED) { mExecutor.execute(() -> mCallback.onClosed( - Callback.CLOSE_REASON_LOCAL_CLOSE_API, new PersistableBundle())); + Callback.REASON_LOCAL_REQUEST, new PersistableBundle())); return; } @@ -206,32 +348,114 @@ public final class RangingSession implements AutoCloseable { /** * @hide */ + public void onRangingOpened() { + if (mState == State.CLOSED) { + Log.w(TAG, "onRangingOpened invoked for a closed session"); + return; + } + + mState = State.IDLE; + executeCallback(() -> mCallback.onOpened(this)); + } + + /** + * @hide + */ + public void onRangingOpenFailed(@Callback.Reason int reason, + @NonNull PersistableBundle params) { + if (mState == State.CLOSED) { + Log.w(TAG, "onRangingOpenFailed invoked for a closed session"); + return; + } + + mState = State.CLOSED; + executeCallback(() -> mCallback.onOpenFailed(reason, params)); + } + + /** + * @hide + */ public void onRangingStarted(@NonNull PersistableBundle parameters) { if (mState == State.CLOSED) { Log.w(TAG, "onRangingStarted invoked for a closed session"); return; } - mState = State.OPEN; - final long identity = Binder.clearCallingIdentity(); - try { - mExecutor.execute(() -> mCallback.onOpenSuccess(this, parameters)); - } finally { - Binder.restoreCallingIdentity(identity); + mState = State.ACTIVE; + executeCallback(() -> mCallback.onStarted(parameters)); + } + + /** + * @hide + */ + public void onRangingStartFailed(@Callback.Reason int reason, + @NonNull PersistableBundle params) { + if (mState == State.CLOSED) { + Log.w(TAG, "onRangingStartFailed invoked for a closed session"); + return; } + + executeCallback(() -> mCallback.onStartFailed(reason, params)); } /** * @hide */ - public void onRangingClosed(@Callback.CloseReason int reason, PersistableBundle parameters) { - mState = State.CLOSED; - final long identity = Binder.clearCallingIdentity(); - try { - mExecutor.execute(() -> mCallback.onClosed(reason, parameters)); - } finally { - Binder.restoreCallingIdentity(identity); + public void onRangingReconfigured(@NonNull PersistableBundle params) { + if (mState == State.CLOSED) { + Log.w(TAG, "onRangingReconfigured invoked for a closed session"); + return; + } + + executeCallback(() -> mCallback.onReconfigured(params)); + } + + /** + * @hide + */ + public void onRangingReconfigureFailed(@Callback.Reason int reason, + @NonNull PersistableBundle params) { + if (mState == State.CLOSED) { + Log.w(TAG, "onRangingReconfigureFailed invoked for a closed session"); + return; + } + + executeCallback(() -> mCallback.onReconfigureFailed(reason, params)); + } + + /** + * @hide + */ + public void onRangingStopped() { + if (mState == State.CLOSED) { + Log.w(TAG, "onRangingStopped invoked for a closed session"); + return; } + + mState = State.IDLE; + executeCallback(() -> mCallback.onStopped()); + } + + /** + * @hide + */ + public void onRangingStopFailed(@Callback.Reason int reason, + @NonNull PersistableBundle params) { + if (mState == State.CLOSED) { + Log.w(TAG, "onRangingStopFailed invoked for a closed session"); + return; + } + + executeCallback(() -> mCallback.onStopFailed(reason, params)); + } + + /** + * @hide + */ + public void onRangingClosed(@Callback.Reason int reason, + @NonNull PersistableBundle parameters) { + mState = State.CLOSED; + executeCallback(() -> mCallback.onClosed(reason, parameters)); } /** @@ -243,9 +467,16 @@ public final class RangingSession implements AutoCloseable { return; } + executeCallback(() -> mCallback.onReportReceived(report)); + } + + /** + * @hide + */ + private void executeCallback(@NonNull Runnable runnable) { final long identity = Binder.clearCallingIdentity(); try { - mExecutor.execute(() -> mCallback.onReportReceived(report)); + mExecutor.execute(runnable); } finally { Binder.restoreCallingIdentity(identity); } diff --git a/core/java/android/uwb/StartFailureReason.aidl b/core/java/android/uwb/StartFailureReason.aidl deleted file mode 100644 index 4d9c962f529b..000000000000 --- a/core/java/android/uwb/StartFailureReason.aidl +++ /dev/null @@ -1,52 +0,0 @@ -/* - * 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; - -/** - * @hide - */ -@Backing(type="int") -enum StartFailureReason { - /** - * Unknown start failure reason - */ - UNKNOWN, - - /** - * The provided parameters were invalid and ranging could not start - */ - BAD_PARAMETERS, - - /** - * The maximum number of sessions has been reached. This error may be generated - * for an active session if a higher priority session begins. - */ - MAX_SESSIONS_REACHED, - - /** - * The system state has changed resulting in the session ending (e.g. the user - * disables UWB, or the user's locale changes and an active channel is no longer - * permitted to be used). - */ - SYSTEM_POLICY, - - /** - * The session could not start because of a protocol specific reason. - */ - PROTOCOL_SPECIFIC, -} - diff --git a/core/java/android/uwb/UwbManager.java b/core/java/android/uwb/UwbManager.java index f4d801868e18..15ee5b5f22eb 100644 --- a/core/java/android/uwb/UwbManager.java +++ b/core/java/android/uwb/UwbManager.java @@ -369,13 +369,13 @@ public final class UwbManager { /** * 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>The {@link RangingSession.Callback#onOpened(RangingSession)} 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>If a session cannot be opened, then + * {@link RangingSession.Callback#onClosed(int, PersistableBundle)} will be invoked with the + * appropriate {@link RangingSession.Callback.Reason}. * * <p>An open {@link RangingSession} will be automatically closed if client application process * dies. @@ -391,7 +391,7 @@ public final class UwbManager { * @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}. + * {@link RangingSession.Callback#onOpened(RangingSession)}. */ @NonNull public AutoCloseable openRangingSession(@NonNull PersistableBundle parameters, |