1 /* 2 * Copyright (C) 2024 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 com.android.server.ranging; 18 19 import android.annotation.Nullable; 20 import android.content.AttributionSource; 21 import android.ranging.RangingData; 22 import android.ranging.RangingDevice; 23 import android.ranging.raw.RawResponderRangingConfig; 24 25 import androidx.annotation.NonNull; 26 27 import com.android.server.ranging.RangingUtils.InternalReason; 28 import com.android.server.ranging.session.RangingSessionConfig; 29 30 import com.google.common.collect.ImmutableSet; 31 32 /** RangingAdapter representing a common ranging class for multiple ranging technologies. */ 33 public interface RangingAdapter { 34 35 /** Returns {@link RangingTechnology} of this adapter. */ 36 @NonNull getTechnology()37 RangingTechnology getTechnology(); 38 39 /** 40 * Start ranging. Does nothing if the ranging technology is not enabled on device or if ranging 41 * has already been started. In the latter case, this method will not overwrite the existing 42 * callback. 43 * 44 * @param config for the ranging session. 45 * @param callback to be called on the occurrence of ranging events. 46 */ start(@onNull RangingSessionConfig.TechnologyConfig config, @Nullable AttributionSource nonPrivilegedAttributionSource, @NonNull Callback callback)47 void start(@NonNull RangingSessionConfig.TechnologyConfig config, 48 @Nullable AttributionSource nonPrivilegedAttributionSource, 49 @NonNull Callback callback); 50 51 /** Stop ranging. */ stop()52 void stop(); 53 54 /** Dynamic add/remove peers. Defaults to unsupported.*/ isDynamicUpdatePeersSupported()55 default boolean isDynamicUpdatePeersSupported() { 56 return false; 57 } 58 addPeer(RawResponderRangingConfig params)59 default void addPeer(RawResponderRangingConfig params) {} 60 removePeer(RangingDevice device)61 default void removePeer(RangingDevice device) {} 62 reconfigureRangingInterval(int intervalSkipCount)63 default void reconfigureRangingInterval(int intervalSkipCount) {} 64 appForegroundStateUpdated(boolean appInForeground)65 default void appForegroundStateUpdated(boolean appInForeground) { 66 if (appInForeground) { 67 appMovedToForeground(); 68 } else { 69 appMovedToBackground(); 70 } 71 } appMovedToBackground()72 void appMovedToBackground(); 73 appMovedToForeground()74 void appMovedToForeground(); 75 appInBackgroundTimeout()76 void appInBackgroundTimeout(); 77 78 /** Callback for getting notified when ranging starts or stops. */ 79 interface Callback { 80 /** 81 * Notifies the caller that ranging has started with a particular peer. onStarted will not 82 * be called after start if API failed to initialize, in that case onClosed with an 83 * appropriate error code will be called instead. 84 * 85 * @param peers that ranging was started with. Must be non-empty. Multicast technologies 86 * may start ranging with multiple peers at once. 87 */ onStarted(@onNull ImmutableSet<RangingDevice> peers)88 void onStarted(@NonNull ImmutableSet<RangingDevice> peers); 89 90 91 /** 92 * Notifies the caller that ranging has stopped with a particular peer. 93 * 94 * @param peers that ranging was stopped with. Must be non-empty. Multicast technologies 95 * may stop ranging with multiple peers at once. 96 * @param reason why ranging was stopped. 97 */ onStopped(@onNull ImmutableSet<RangingDevice> peers, @InternalReason int reason)98 void onStopped(@NonNull ImmutableSet<RangingDevice> peers, @InternalReason int reason); 99 100 /** 101 * Notifies the caller on each instance of ranging data received from the ranging 102 * technology. 103 * 104 * @param peer device whose distance was measured. 105 * @param data the distance measurement and other position-related data. 106 */ onRangingData(@onNull RangingDevice peer, @NonNull RangingData data)107 void onRangingData(@NonNull RangingDevice peer, @NonNull RangingData data); 108 109 /** 110 * Notifies the caller that the ranging session was closed. 111 * 112 * @param reason why the session was closed. 113 */ onClosed(@nternalReason int reason)114 void onClosed(@InternalReason int reason); 115 } 116 } 117