1 /* 2 * Copyright 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.uwb; 18 19 import android.content.AttributionSource; 20 import android.os.PersistableBundle; 21 import android.uwb.IUwbAdapterStateCallbacks; 22 import android.uwb.IUwbRangingCallbacks; 23 import android.uwb.SessionHandle; 24 25 /** 26 * @hide 27 */ 28 interface IUwbAdapter { 29 /* 30 * Register the callbacks used to notify the framework of events and data 31 * 32 * The provided callback's IUwbAdapterStateCallbacks#onAdapterStateChanged 33 * function must be called immediately following registration with the current 34 * state of the UWB adapter. 35 * 36 * @param callbacks callback to provide range and status updates to the framework 37 */ registerAdapterStateCallbacks(in IUwbAdapterStateCallbacks adapterStateCallbacks)38 void registerAdapterStateCallbacks(in IUwbAdapterStateCallbacks adapterStateCallbacks); 39 40 /* 41 * Unregister the callbacks used to notify the framework of events and data 42 * 43 * Calling this function with an unregistered callback is a no-op 44 * 45 * @param callbacks callback to unregister 46 */ unregisterAdapterStateCallbacks(in IUwbAdapterStateCallbacks callbacks)47 void unregisterAdapterStateCallbacks(in IUwbAdapterStateCallbacks callbacks); 48 49 /** 50 * Get the accuracy of the ranging timestamps 51 * 52 * @return accuracy of the ranging timestamps in nanoseconds 53 */ getTimestampResolutionNanos()54 long getTimestampResolutionNanos(); 55 56 /** 57 * Provides the capabilities and features of the device 58 * 59 * @return specification specific capabilities and features of the device 60 */ getSpecificationInfo()61 PersistableBundle getSpecificationInfo(); 62 63 /** 64 * Request to open a new ranging session 65 * 66 * This function does not start the ranging session, but all necessary 67 * components must be initialized and ready to start a new ranging 68 * session prior to calling IUwbAdapterCallback#onRangingOpened. 69 * 70 * IUwbAdapterCallbacks#onRangingOpened must be called within 71 * RANGING_SESSION_OPEN_THRESHOLD_MS milliseconds of #openRanging being 72 * called if the ranging session is opened successfully. 73 * 74 * IUwbAdapterCallbacks#onRangingOpenFailed must be called within 75 * RANGING_SESSION_OPEN_THRESHOLD_MS milliseconds of #openRanging being called 76 * if the ranging session fails to be opened. 77 * 78 * If the provided sessionHandle is already open for the calling client, then 79 * #onRangingOpenFailed must be called and the new session must not be opened. 80 * 81 * @param attributionSource AttributionSource to use for permission enforcement. 82 * @param sessionHandle the session handle to open ranging for 83 * @param rangingCallbacks the callbacks used to deliver ranging information 84 * @param parameters the configuration to use for ranging 85 */ openRanging(in AttributionSource attributionSource, in SessionHandle sessionHandle, in IUwbRangingCallbacks rangingCallbacks, in PersistableBundle parameters)86 void openRanging(in AttributionSource attributionSource, 87 in SessionHandle sessionHandle, 88 in IUwbRangingCallbacks rangingCallbacks, 89 in PersistableBundle parameters); 90 91 /** 92 * Request to start ranging 93 * 94 * IUwbAdapterCallbacks#onRangingStarted must be called within 95 * RANGING_SESSION_START_THRESHOLD_MS milliseconds of #startRanging being 96 * called if the ranging session starts successfully. 97 * 98 * IUwbAdapterCallbacks#onRangingStartFailed must be called within 99 * RANGING_SESSION_START_THRESHOLD_MS milliseconds of #startRanging being 100 * called if the ranging session fails to be started. 101 * 102 * @param sessionHandle the session handle to start ranging for 103 * @param parameters additional configuration required to start ranging 104 */ startRanging(in SessionHandle sessionHandle, in PersistableBundle parameters)105 void startRanging(in SessionHandle sessionHandle, 106 in PersistableBundle parameters); 107 108 /** 109 * Request to reconfigure ranging 110 * 111 * IUwbAdapterCallbacks#onRangingReconfigured must be called after 112 * successfully reconfiguring the session. 113 * 114 * IUwbAdapterCallbacks#onRangingReconfigureFailed must be called after 115 * failing to reconfigure the session. 116 * 117 * A session must not be modified by a failed call to #reconfigureRanging. 118 * 119 * @param sessionHandle the session handle to start ranging for 120 * @param parameters the parameters to reconfigure and their new values 121 */ reconfigureRanging(in SessionHandle sessionHandle, in PersistableBundle parameters)122 void reconfigureRanging(in SessionHandle sessionHandle, 123 in PersistableBundle parameters); 124 125 /** 126 * Request to stop ranging 127 * 128 * IUwbAdapterCallbacks#onRangingStopped must be called after 129 * successfully stopping the session. 130 * 131 * IUwbAdapterCallbacks#onRangingStopFailed must be called after failing 132 * to stop the session. 133 * 134 * @param sessionHandle the session handle to stop ranging for 135 */ stopRanging(in SessionHandle sessionHandle)136 void stopRanging(in SessionHandle sessionHandle); 137 138 /** 139 * Close ranging for the session associated with the given handle 140 * 141 * Calling with an invalid handle or a handle that has already been closed 142 * is a no-op. 143 * 144 * IUwbAdapterCallbacks#onRangingClosed must be called within 145 * RANGING_SESSION_CLOSE_THRESHOLD_MS of #closeRanging being called. 146 * 147 * @param sessionHandle the session handle to close ranging for 148 */ closeRanging(in SessionHandle sessionHandle)149 void closeRanging(in SessionHandle sessionHandle); 150 151 /** 152 * Disables or enables UWB for a user 153 * 154 * The provided callback's IUwbAdapterStateCallbacks#onAdapterStateChanged 155 * function must be called immediately following state change. 156 * 157 * @param enabled value representing intent to disable or enable UWB. If 158 * true, any subsequent calls to #openRanging will be allowed. If false, 159 * all active ranging sessions will be closed and subsequent calls to 160 * #openRanging will be disallowed. 161 */ setEnabled(boolean enabled)162 void setEnabled(boolean enabled); 163 164 /** 165 * Returns the current enabled/disabled UWB state. 166 * 167 * Possible values are: 168 * IUwbAdapterState#STATE_DISABLED 169 * IUwbAdapterState#STATE_ENABLED_ACTIVE 170 * IUwbAdapterState#STATE_ENABLED_INACTIVE 171 * 172 * @return value representing enabled/disabled UWB state. 173 */ getAdapterState()174 int getAdapterState(); 175 176 /** 177 * The maximum allowed time to open a ranging session. 178 */ 179 const int RANGING_SESSION_OPEN_THRESHOLD_MS = 3000; // Value TBD 180 181 /** 182 * The maximum allowed time to start a ranging session. 183 */ 184 const int RANGING_SESSION_START_THRESHOLD_MS = 3000; // Value TBD 185 186 /** 187 * The maximum allowed time to notify the framework that a session has been 188 * closed. 189 */ 190 const int RANGING_SESSION_CLOSE_THRESHOLD_MS = 3000; // Value TBD 191 } 192