Merge "Add UwbManager API Stubs"
This commit is contained in:
Brian Stack
269
core/java/android/uwb/UwbManager.java
Normal file
269
core/java/android/uwb/UwbManager.java
Normal file
@@ -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();
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user