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 android.ranging.oob; 18 19 import android.annotation.FlaggedApi; 20 import android.annotation.NonNull; 21 import android.annotation.SuppressLint; 22 23 import com.android.ranging.flags.Flags; 24 25 import java.util.concurrent.Executor; 26 27 /** 28 * TransportHandle is used as the Out-Of-Band (OOB) transport mechanism by ranging module. 29 * In cases where module is used in a non-raw ranging mode, the user shall provide an implementation 30 * of the TransportHandle, allowing ranging module to do the necessary OOB communication with a peer 31 * device using the provided transport handle. Some examples of OOB transport between two peer 32 * devices are: 33 * <ul> 34 * <li>BLE GATT connection</li> 35 * <li>Wi-Fi MDNS link</li> 36 * <li>Internet</li> 37 * </ul> 38 */ 39 @FlaggedApi(Flags.FLAG_RANGING_STACK_ENABLED) 40 public interface TransportHandle extends AutoCloseable { 41 42 /** Send data to the peer device via the implemented OOB transport. 43 * 44 * @param data the data to be sent to the peer device. Must not be null. 45 * @throws IllegalArgumentException if the provided data is null or invalid 46 */ sendData(@onNull byte[] data)47 void sendData(@NonNull byte[] data); 48 49 /** 50 * Registers a callback to receive updates from the transport mechanism. 51 * 52 * <p>The callback should be used to notify information about the peer device including the 53 * data received from the peer device. 54 * 55 * @param executor the {@link Executor} on which the callback should be invoked. Must not be 56 * null. 57 * @param callback the {@link ReceiveCallback} instance to receive updates. Must not be null. 58 * @throws IllegalArgumentException if either {@code executor} or {@code callback} is null. 59 */ 60 @SuppressLint({"PairedRegistration"}) registerReceiveCallback(@onNull Executor executor, @NonNull ReceiveCallback callback)61 void registerReceiveCallback(@NonNull Executor executor, @NonNull ReceiveCallback callback); 62 63 /** TransportHandle callback. */ 64 interface ReceiveCallback { 65 /** 66 * Notifies and provides data received from the peer device. 67 * 68 * @param data the data received from the peer device. Must not be null. 69 */ onReceiveData(@onNull byte[] data)70 void onReceiveData(@NonNull byte[] data); 71 72 /** 73 * Called when a data send operation fails. 74 */ onSendFailed()75 void onSendFailed(); 76 77 /** 78 * Notifies the receiver that the TransportHandle instance can't be used to receive or send 79 * data until {@see onReconnect()} is called. 80 */ onDisconnect()81 void onDisconnect(); 82 83 /** 84 * Notifies the receiver the TransportHandle instance can be used again to send and receive 85 * data. Should only be called if {@see onDisconnect()} preceded it. 86 */ onReconnect()87 void onReconnect(); 88 89 /** 90 * Notifies the receiver that the TransportHandle instance can't be used anymore to receive 91 * or send data. Also call this in {@link AutoCloseable#close()}. 92 */ onClose()93 void onClose(); 94 } 95 } 96