1 /* 2 * Copyright (C) 2016 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.net.wifi.aware; 18 19 import android.annotation.NonNull; 20 21 import java.util.List; 22 23 /** 24 * Base class for Aware session events callbacks. Should be extended by 25 * applications wanting notifications. The callbacks are set when a 26 * publish or subscribe session is created using 27 * {@link WifiAwareSession#publish(PublishConfig, DiscoverySessionCallback, 28 * android.os.Handler)} or 29 * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback, 30 * android.os.Handler)}. 31 * <p> 32 * A single callback is set at session creation - it cannot be replaced. 33 */ 34 public class DiscoverySessionCallback { 35 /** 36 * Called when a publish operation is started successfully in response to a 37 * {@link WifiAwareSession#publish(PublishConfig, DiscoverySessionCallback, 38 * android.os.Handler)} operation. 39 * 40 * @param session The {@link PublishDiscoverySession} used to control the 41 * discovery session. 42 */ onPublishStarted(@onNull PublishDiscoverySession session)43 public void onPublishStarted(@NonNull PublishDiscoverySession session) { 44 /* empty */ 45 } 46 47 /** 48 * Called when a subscribe operation is started successfully in response to a 49 * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback, 50 * android.os.Handler)} operation. 51 * 52 * @param session The {@link SubscribeDiscoverySession} used to control the 53 * discovery session. 54 */ onSubscribeStarted(@onNull SubscribeDiscoverySession session)55 public void onSubscribeStarted(@NonNull SubscribeDiscoverySession session) { 56 /* empty */ 57 } 58 59 /** 60 * Called when a publish or subscribe discovery session configuration update request 61 * succeeds. Called in response to 62 * {@link PublishDiscoverySession#updatePublish(PublishConfig)} or 63 * {@link SubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}. 64 */ onSessionConfigUpdated()65 public void onSessionConfigUpdated() { 66 /* empty */ 67 } 68 69 /** 70 * Called when a publish or subscribe discovery session cannot be created: 71 * {@link WifiAwareSession#publish(PublishConfig, DiscoverySessionCallback, 72 * android.os.Handler)} or 73 * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback, 74 * android.os.Handler)}, or when a configuration update fails: 75 * {@link PublishDiscoverySession#updatePublish(PublishConfig)} or 76 * {@link SubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}. 77 * <p> 78 * For discovery session updates failure leaves the session running with its previous 79 * configuration - the discovery session is not terminated. 80 */ onSessionConfigFailed()81 public void onSessionConfigFailed() { 82 /* empty */ 83 } 84 85 /** 86 * Called when a discovery session (publish or subscribe) terminates. Termination may be due 87 * to user-request (either directly through {@link DiscoverySession#close()} or 88 * application-specified expiration, e.g. {@link PublishConfig.Builder#setTtlSec(int)} 89 * or {@link SubscribeConfig.Builder#setTtlSec(int)}). 90 */ onSessionTerminated()91 public void onSessionTerminated() { 92 /* empty */ 93 } 94 95 /** 96 * Called when a subscribe operation results in a service discovery. 97 * <p> 98 * Note that this method and 99 * {@link #onServiceDiscoveredWithinRange(PeerHandle, byte[], List, int)} may be called 100 * multiple times per service discovery. 101 * <p> 102 * Note: This method is superseded by {@link #onServiceDiscovered(ServiceDiscoveryInfo)} which 103 * returns more information. Note that both legacy and new callback will be triggered on 104 * discovery. 105 * 106 * @param peerHandle An opaque handle to the peer matching our discovery operation. 107 * @param serviceSpecificInfo The service specific information (arbitrary 108 * byte array) provided by the peer as part of its discovery 109 * configuration. 110 * @param matchFilter The filter which resulted in this service discovery. For 111 * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED}, 112 * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE} discovery sessions this is the publisher's 113 * match filter. For {@link PublishConfig#PUBLISH_TYPE_SOLICITED}, 114 * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} discovery sessions this 115 * is the subscriber's match filter. 116 */ onServiceDiscovered(PeerHandle peerHandle, byte[] serviceSpecificInfo, List<byte[]> matchFilter)117 public void onServiceDiscovered(PeerHandle peerHandle, 118 byte[] serviceSpecificInfo, List<byte[]> matchFilter) { 119 /* empty */ 120 } 121 122 /** 123 * Called when a subscribe operation results in a service discovery. 124 * <p> 125 * Note: This method supersedes {@link #onServiceDiscovered(PeerHandle, byte[], List)} and 126 * provides additional information - including cipher suite type and security context of the 127 * peer. Both the legacy and the new callback will be triggered on discovery. 128 * 129 * @param info A {@link ServiceDiscoveryInfo} structure containing information on the discovery 130 * session and the discovered peer. 131 */ onServiceDiscovered(@onNull ServiceDiscoveryInfo info)132 public void onServiceDiscovered(@NonNull ServiceDiscoveryInfo info) { 133 /* empty */ 134 } 135 136 /** 137 * Called when a subscribe operation results in a 138 * service discovery. Called when a Subscribe service was configured with a range requirement 139 * {@link SubscribeConfig.Builder#setMinDistanceMm(int)} and/or 140 * {@link SubscribeConfig.Builder#setMaxDistanceMm(int)} and the Publish service was configured 141 * with {@link PublishConfig.Builder#setRangingEnabled(boolean)}. 142 * <p> 143 * If either Publisher or Subscriber does not enable Ranging, or if Ranging is temporarily 144 * disabled by the underlying device, service discovery proceeds without ranging and the 145 * {@link #onServiceDiscovered(PeerHandle, byte[], List)} is called. 146 * <p> 147 * Note that this method and {@link #onServiceDiscovered(PeerHandle, byte[], List)} may be 148 * called multiple times per service discovery. 149 * <p> 150 * Note: This method is superseded by 151 * {@link #onServiceDiscoveredWithinRange(ServiceDiscoveryInfo, int)} which returns more 152 * information. Note that both legacy and new callback will be triggered on discovery. 153 * 154 * @param peerHandle An opaque handle to the peer matching our discovery operation. 155 * @param serviceSpecificInfo The service specific information (arbitrary 156 * byte array) provided by the peer as part of its discovery 157 * configuration. 158 * @param matchFilter The filter which resulted in this service discovery. For 159 * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED}, 160 * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE} discovery sessions this is the publisher's 161 * match filter. For {@link PublishConfig#PUBLISH_TYPE_SOLICITED}, 162 * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} discovery sessions this 163 * is the subscriber's match filter. 164 * @param distanceMm The measured distance to the Publisher in mm. Note: the measured distance 165 * may be negative for very close devices. 166 */ onServiceDiscoveredWithinRange(PeerHandle peerHandle, byte[] serviceSpecificInfo, List<byte[]> matchFilter, int distanceMm)167 public void onServiceDiscoveredWithinRange(PeerHandle peerHandle, 168 byte[] serviceSpecificInfo, List<byte[]> matchFilter, int distanceMm) { 169 /* empty */ 170 } 171 172 /** 173 * Called when a subscribe operation results in a 174 * service discovery. Called when a Subscribe service was configured with a range requirement 175 * {@link SubscribeConfig.Builder#setMinDistanceMm(int)} and/or 176 * {@link SubscribeConfig.Builder#setMaxDistanceMm(int)} and the Publish service was configured 177 * with {@link PublishConfig.Builder#setRangingEnabled(boolean)}. 178 * <p> 179 * If either Publisher or Subscriber does not enable Ranging, or if Ranging is temporarily 180 * disabled by the underlying device, service discovery proceeds without ranging and the 181 * {@link #onServiceDiscovered(PeerHandle, byte[], List)} is called. 182 * <p> 183 * Note: This method supersedes 184 * {@link #onServiceDiscoveredWithinRange(PeerHandle, byte[], List, int)} and provides 185 * additional information - including cipher suite type and security context of the peer. Both 186 * the legacy and the new callback will be triggered on discovery. 187 * 188 * @param info A {@link ServiceDiscoveryInfo} which indicate service config of the descovery 189 * sessions. 190 * @param distanceMm The measured distance to the Publisher in mm. Note: the measured distance 191 * may be negative for very close devices. 192 */ onServiceDiscoveredWithinRange(@onNull ServiceDiscoveryInfo info, int distanceMm)193 public void onServiceDiscoveredWithinRange(@NonNull ServiceDiscoveryInfo info, int distanceMm) { 194 /* empty */ 195 } 196 197 /** 198 * Called in response to 199 * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])} 200 * when a message is transmitted successfully - i.e. when it was received successfully by the 201 * peer (corresponds to an ACK being received). 202 * <p> 203 * Note that either this callback or 204 * {@link DiscoverySessionCallback#onMessageSendFailed(int)} will be 205 * received - never both. 206 * 207 * @param messageId The arbitrary message ID specified when sending the message. 208 */ onMessageSendSucceeded(@uppressWarnings"unused") int messageId)209 public void onMessageSendSucceeded(@SuppressWarnings("unused") int messageId) { 210 /* empty */ 211 } 212 213 /** 214 * Called when message transmission initiated with 215 * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])} fails. E.g. when no ACK is 216 * received from the peer. 217 * <p> 218 * Note that either this callback or 219 * {@link DiscoverySessionCallback#onMessageSendSucceeded(int)} will be received 220 * - never both. 221 * 222 * @param messageId The arbitrary message ID specified when sending the message. 223 */ onMessageSendFailed(@uppressWarnings"unused") int messageId)224 public void onMessageSendFailed(@SuppressWarnings("unused") int messageId) { 225 /* empty */ 226 } 227 228 /** 229 * Called when a message is received from a discovery session peer - in response to the 230 * peer's {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])}. 231 * 232 * @param peerHandle An opaque handle to the peer matching our discovery operation. 233 * @param message A byte array containing the message. 234 */ onMessageReceived(PeerHandle peerHandle, byte[] message)235 public void onMessageReceived(PeerHandle peerHandle, byte[] message) { 236 /* empty */ 237 } 238 239 /** 240 * Called when the discovered service is not available. All further operations on this 241 * discovery session will fail. If the service is available again, 242 * {@link #onServiceDiscovered(PeerHandle, byte[], List)} or 243 * {@link #onServiceDiscoveredWithinRange(PeerHandle, byte[], List, int)} will be called. 244 * 245 * @param peerHandle An opaque handle to the peer matching our discovery operation. 246 * @param reason Discovered service lost reason code. One of 247 * {@link WifiAwareManager#WIFI_AWARE_DISCOVERY_LOST_REASON_PEER_NOT_VISIBLE}, 248 * {@link WifiAwareManager#WIFI_AWARE_DISCOVERY_LOST_REASON_UNKNOWN 249 */ onServiceLost(@onNull PeerHandle peerHandle, @WifiAwareManager.DiscoveryLostReasonCode int reason)250 public void onServiceLost(@NonNull PeerHandle peerHandle, 251 @WifiAwareManager.DiscoveryLostReasonCode int reason) { 252 /* empty */ 253 } 254 } 255