diff options
| -rw-r--r-- | core/java/android/uwb/UwbManager.java | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/core/java/android/uwb/UwbManager.java b/core/java/android/uwb/UwbManager.java new file mode 100644 index 000000000000..8097dc6dca11 --- /dev/null +++ b/core/java/android/uwb/UwbManager.java @@ -0,0 +1,269 @@ +/* + * 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.annotation.NonNull; +import android.annotation.SuppressLint; +import android.os.PersistableBundle; + +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.util.List; +import java.util.Set; +import java.util.concurrent.Executor; + +/** + * This class provides a way to perform Ultra Wideband (UWB) operations such as querying the + * device's capabilities and determining the distance and angle between the local device and a + * remote device. + * + * <p>To get a {@link UwbManager}, call the <code>Context.getSystemService(UwbManager.class)</code>. + * + * @hide + */ +public final class UwbManager { + /** + * Interface for receiving UWB adapter state changes + */ + public interface AdapterStateCallback { + @Retention(RetentionPolicy.SOURCE) + @IntDef(value = { + STATE_CHANGED_REASON_SESSION_STARTED, + STATE_CHANGED_REASON_ALL_SESSIONS_CLOSED, + STATE_CHANGED_REASON_SYSTEM_POLICY, + STATE_CHANGED_REASON_SYSTEM_BOOT, + STATE_CHANGED_REASON_ERROR_UNKNOWN}) + @interface StateChangedReason {} + + /** + * Indicates that the state change was due to opening of first UWB session + */ + int STATE_CHANGED_REASON_SESSION_STARTED = 0; + + /** + * Indicates that the state change was due to closure of all UWB sessions + */ + int STATE_CHANGED_REASON_ALL_SESSIONS_CLOSED = 1; + + /** + * Indicates that the state change was due to changes in system policy + */ + int STATE_CHANGED_REASON_SYSTEM_POLICY = 2; + + /** + * Indicates that the current state is due to a system boot + */ + int STATE_CHANGED_REASON_SYSTEM_BOOT = 3; + + /** + * Indicates that the state change was due to some unknown error + */ + int STATE_CHANGED_REASON_ERROR_UNKNOWN = 4; + + /** + * Invoked when underlying UWB adapter's state is changed + * <p>Invoked with the adapter's current state after registering an + * {@link AdapterStateCallback} using + * {@link UwbManager#registerAdapterStateCallback(Executor, AdapterStateCallback)}. + * + * <p>Possible values for the state to change are + * {@link #STATE_CHANGED_REASON_SESSION_STARTED}, + * {@link #STATE_CHANGED_REASON_ALL_SESSIONS_CLOSED}, + * {@link #STATE_CHANGED_REASON_SYSTEM_POLICY}, + * {@link #STATE_CHANGED_REASON_SYSTEM_BOOT}, + * {@link #STATE_CHANGED_REASON_ERROR_UNKNOWN}. + * + * @param isEnabled true when UWB adapter is enabled, false when it is disabled + * @param reason the reason for the state change + */ + void onStateChanged(boolean isEnabled, @StateChangedReason int reason); + } + + /** + * Use <code>Context.getSystemService(UwbManager.class)</code> to get an instance. + */ + private UwbManager() { + throw new UnsupportedOperationException(); + } + /** + * Register an {@link AdapterStateCallback} to listen for UWB adapter state changes + * <p>The provided callback will be invoked by the given {@link Executor}. + * + * <p>When first registering a callback, the callbacks's + * {@link AdapterStateCallback#onStateChanged(boolean, int)} is immediately invoked to indicate + * the current state of the underlying UWB adapter with the most recent + * {@link AdapterStateCallback.StateChangedReason} that caused the change. + * + * @param executor an {@link Executor} to execute given callback + * @param callback user implementation of the {@link AdapterStateCallback} + */ + public void registerAdapterStateCallback(Executor executor, AdapterStateCallback callback) { + throw new UnsupportedOperationException(); + } + + /** + * Unregister the specified {@link AdapterStateCallback} + * <p>The same {@link AdapterStateCallback} object used when calling + * {@link #registerAdapterStateCallback(Executor, AdapterStateCallback)} must be used. + * + * <p>Callbacks are automatically unregistered when application process goes away + * + * @param callback user implementation of the {@link AdapterStateCallback} + */ + public void unregisterAdapterStateCallback(AdapterStateCallback callback) { + throw new UnsupportedOperationException(); + } + + /** + * Get a {@link PersistableBundle} with the supported UWB protocols and parameters. + * <p>The {@link PersistableBundle} should be parsed using a support library + * + * <p>Android reserves the '^android.*' namespace</p> + * + * @return {@link PersistableBundle} of the device's supported UWB protocols and parameters + */ + @NonNull + public PersistableBundle getSpecificationInfo() { + throw new UnsupportedOperationException(); + } + + /** + * Check if ranging is supported, regardless of ranging method + * + * @return true if ranging is supported + */ + public boolean isRangingSupported() { + throw new UnsupportedOperationException(); + } + + @Retention(RetentionPolicy.SOURCE) + @IntDef(value = { + ANGLE_OF_ARRIVAL_SUPPORT_TYPE_NONE, + ANGLE_OF_ARRIVAL_SUPPORT_TYPE_2D, + ANGLE_OF_ARRIVAL_SUPPORT_TYPE_3D_HEMISPHERICAL, + ANGLE_OF_ARRIVAL_SUPPORT_TYPE_3D_SPHERICAL}) + public @interface AngleOfArrivalSupportType {} + + /** + * Indicate absence of support for angle of arrival measurement + */ + public static final int ANGLE_OF_ARRIVAL_SUPPORT_TYPE_NONE = 1; + + /** + * Indicate support for planar angle of arrival measurement, due to antenna + * limitation. Typically requires at least two antennas. + */ + public static final int ANGLE_OF_ARRIVAL_SUPPORT_TYPE_2D = 2; + + /** + * Indicate support for three dimensional angle of arrival measurement. + * Typically requires at least three antennas. However, due to antenna + * arrangement, a platform may only support hemi-spherical azimuth angles + * ranging from -pi/2 to pi/2 + */ + public static final int ANGLE_OF_ARRIVAL_SUPPORT_TYPE_3D_HEMISPHERICAL = 2; + + /** + * Indicate support for three dimensional angle of arrival measurement. + * Typically requires at least three antennas. This mode supports full + * azimuth angles ranging from -pi to pi. + */ + public static final int ANGLE_OF_ARRIVAL_SUPPORT_TYPE_3D_SPHERICAL = 3; + + + /** + * Gets the {@link AngleOfArrivalSupportType} supported on this platform + * <p>Possible return values are + * {@link #ANGLE_OF_ARRIVAL_SUPPORT_TYPE_NONE}, + * {@link #ANGLE_OF_ARRIVAL_SUPPORT_TYPE_2D}, + * {@link #ANGLE_OF_ARRIVAL_SUPPORT_TYPE_3D_HEMISPHERICAL}, + * {@link #ANGLE_OF_ARRIVAL_SUPPORT_TYPE_3D_SPHERICAL}. + * + * @return angle of arrival type supported + */ + @AngleOfArrivalSupportType + public int getAngleOfArrivalSupport() { + throw new UnsupportedOperationException(); + } + + /** + * Get a {@link List} of supported channel numbers based on the device's current location + * <p>The returned values are ordered by the system's desired ordered of use, with the first + * entry being the most preferred. + * + * <p>Channel numbers are defined based on the IEEE 802.15.4z standard for UWB. + * + * @return {@link List} of supported channel numbers ordered by preference + */ + @NonNull + public List<Integer> getSupportedChannelNumbers() { + throw new UnsupportedOperationException(); + } + + /** + * Get a {@link List} of supported preamble code indices + * <p> Preamble code indices are defined based on the IEEE 802.15.4z standard for UWB. + * + * @return {@link List} of supported preamble code indices + */ + @NonNull + public Set<Integer> getSupportedPreambleCodeIndices() { + throw new UnsupportedOperationException(); + } + + /** + * Get the timestamp resolution for events in nanoseconds + * <p>This value defines the maximum error of all timestamps for events reported to + * {@link RangingSession.Callback}. + * + * @return the timestamp resolution in nanoseconds + */ + @SuppressLint("MethodNameUnits") + public long elapsedRealtimeResolutionNanos() { + throw new UnsupportedOperationException(); + } + + /** + * Get the number of simultaneous sessions allowed in the system + * + * @return the maximum allowed number of simultaneously open {@link RangingSession} instances. + */ + public int getMaxSimultaneousSessions() { + throw new UnsupportedOperationException(); + } + + /** + * Get the maximum number of remote devices in a {@link RangingSession} when the local device + * is the initiator. + * + * @return the maximum number of remote devices per {@link RangingSession} + */ + public int getMaxRemoteDevicesPerInitiatorSession() { + throw new UnsupportedOperationException(); + } + + /** + * Get the maximum number of remote devices in a {@link RangingSession} when the local device + * is a responder. + * + * @return the maximum number of remote devices per {@link RangingSession} + */ + public int getMaxRemoteDevicesPerResponderSession() { + throw new UnsupportedOperationException(); + } +} |