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 import android.annotation.SystemApi; 21 22 import java.util.List; 23 24 /** 25 * Base class for Aware session events callbacks. Should be extended by 26 * applications wanting notifications. The callbacks are set when a 27 * publish or subscribe session is created using 28 * {@link WifiAwareSession#publish(PublishConfig, DiscoverySessionCallback, 29 * android.os.Handler)} or 30 * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback, 31 * android.os.Handler)}. 32 * <p> 33 * A single callback is set at session creation - it cannot be replaced. 34 */ 35 public class DiscoverySessionCallback { 36 /** 37 * Called when a publish operation is started successfully in response to a 38 * {@link WifiAwareSession#publish(PublishConfig, DiscoverySessionCallback, 39 * android.os.Handler)} operation. 40 * 41 * @param session The {@link PublishDiscoverySession} used to control the 42 * discovery session. 43 */ onPublishStarted(@onNull PublishDiscoverySession session)44 public void onPublishStarted(@NonNull PublishDiscoverySession session) { 45 /* empty */ 46 } 47 48 /** 49 * Called when a subscribe operation is started successfully in response to a 50 * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback, 51 * android.os.Handler)} operation. 52 * 53 * @param session The {@link SubscribeDiscoverySession} used to control the 54 * discovery session. 55 */ onSubscribeStarted(@onNull SubscribeDiscoverySession session)56 public void onSubscribeStarted(@NonNull SubscribeDiscoverySession session) { 57 /* empty */ 58 } 59 60 /** 61 * Called when a publish or subscribe discovery session configuration update request 62 * succeeds. Called in response to 63 * {@link PublishDiscoverySession#updatePublish(PublishConfig)} or 64 * {@link SubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}. 65 */ onSessionConfigUpdated()66 public void onSessionConfigUpdated() { 67 /* empty */ 68 } 69 70 /** 71 * Called when a publish or subscribe discovery session cannot be created: 72 * {@link WifiAwareSession#publish(PublishConfig, DiscoverySessionCallback, 73 * android.os.Handler)} or 74 * {@link WifiAwareSession#subscribe(SubscribeConfig, DiscoverySessionCallback, 75 * android.os.Handler)}, or when a configuration update fails: 76 * {@link PublishDiscoverySession#updatePublish(PublishConfig)} or 77 * {@link SubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}. 78 * <p> 79 * For discovery session updates failure leaves the session running with its previous 80 * configuration - the discovery session is not terminated. 81 */ onSessionConfigFailed()82 public void onSessionConfigFailed() { 83 /* empty */ 84 } 85 86 /** 87 * Called when a discovery session (publish or subscribe) terminates. Termination may be due 88 * to user-request (either directly through {@link DiscoverySession#close()} or 89 * application-specified expiration, e.g. {@link PublishConfig.Builder#setTtlSec(int)} 90 * or {@link SubscribeConfig.Builder#setTtlSec(int)}). 91 */ onSessionTerminated()92 public void onSessionTerminated() { 93 /* empty */ 94 } 95 96 /** 97 * Called when a discovery session (publish or subscribe) has been suspended successfully. 98 * Suspension is triggered by {@link DiscoverySession#suspend()}. 99 * @hide 100 */ 101 @SystemApi onSessionSuspendSucceeded()102 public void onSessionSuspendSucceeded() { 103 /* empty */ 104 } 105 106 /** 107 * Called when a discovery session (publish or subscribe) has failed to be suspended 108 * successfully. Suspension is triggered by {@link DiscoverySession#suspend()}. 109 * 110 * @param reason One of: 111 * {@link WifiAwareManager#WIFI_AWARE_SUSPEND_REDUNDANT_REQUEST}, 112 * {@link WifiAwareManager#WIFI_AWARE_SUSPEND_INVALID_SESSION}, 113 * {@link WifiAwareManager#WIFI_AWARE_SUSPEND_CANNOT_SUSPEND}, 114 * {@link WifiAwareManager#WIFI_AWARE_SUSPEND_INTERNAL_ERROR} 115 * @hide 116 */ 117 @SystemApi onSessionSuspendFailed( @ifiAwareManager.SessionSuspensionFailedReasonCode int reason)118 public void onSessionSuspendFailed( 119 @WifiAwareManager.SessionSuspensionFailedReasonCode int reason) { 120 /* empty */ 121 } 122 123 /** 124 * Called when a discovery session (publish or subscribe) has been resumed from suspension 125 * successfully. Resumption is triggered by {@link DiscoverySession#resume()}. 126 * @hide 127 */ 128 @SystemApi onSessionResumeSucceeded()129 public void onSessionResumeSucceeded() { 130 /* empty */ 131 } 132 133 /** 134 * Called when a discovery session (publish or subscribe) has failed to be resumed from 135 * suspension successfully. Resumption is triggered by {@link DiscoverySession#resume()}. 136 * 137 * @param reason One of: 138 * {@link WifiAwareManager#WIFI_AWARE_RESUME_REDUNDANT_REQUEST}, 139 * {@link WifiAwareManager#WIFI_AWARE_RESUME_INVALID_SESSION}, 140 * {@link WifiAwareManager#WIFI_AWARE_RESUME_INTERNAL_ERROR} 141 * @hide 142 */ 143 @SystemApi onSessionResumeFailed( @ifiAwareManager.SessionResumptionFailedReasonCode int reason)144 public void onSessionResumeFailed( 145 @WifiAwareManager.SessionResumptionFailedReasonCode int reason) { 146 /* empty */ 147 } 148 149 /** 150 * Called when a subscribe operation results in a service discovery. 151 * <p> 152 * Note that this method and 153 * {@link #onServiceDiscoveredWithinRange(PeerHandle, byte[], List, int)} may be called 154 * multiple times per service discovery. 155 * <p> 156 * Note: This method is superseded by {@link #onServiceDiscovered(ServiceDiscoveryInfo)} which 157 * returns more information. Note that both legacy and new callback will be triggered on 158 * discovery. 159 * 160 * @param peerHandle An opaque handle to the peer matching our discovery operation. 161 * @param serviceSpecificInfo The service specific information (arbitrary 162 * byte array) provided by the peer as part of its discovery 163 * configuration. 164 * @param matchFilter The filter which resulted in this service discovery. For 165 * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED}, 166 * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE} discovery sessions this is the publisher's 167 * match filter. For {@link PublishConfig#PUBLISH_TYPE_SOLICITED}, 168 * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} discovery sessions this 169 * is the subscriber's match filter. 170 */ onServiceDiscovered(PeerHandle peerHandle, byte[] serviceSpecificInfo, List<byte[]> matchFilter)171 public void onServiceDiscovered(PeerHandle peerHandle, 172 byte[] serviceSpecificInfo, List<byte[]> matchFilter) { 173 /* empty */ 174 } 175 176 /** 177 * Called when a subscribe operation results in a service discovery. 178 * <p> 179 * Note: This method supersedes {@link #onServiceDiscovered(PeerHandle, byte[], List)} and 180 * provides additional information - including cipher suite type and security context of the 181 * peer. Both the legacy and the new callback will be triggered on discovery. 182 * 183 * @param info A {@link ServiceDiscoveryInfo} structure containing information on the discovery 184 * session and the discovered peer. 185 */ onServiceDiscovered(@onNull ServiceDiscoveryInfo info)186 public void onServiceDiscovered(@NonNull ServiceDiscoveryInfo info) { 187 /* empty */ 188 } 189 190 /** 191 * Called when a subscribe operation results in a 192 * service discovery. Called when a Subscribe service was configured with a range requirement 193 * {@link SubscribeConfig.Builder#setMinDistanceMm(int)} and/or 194 * {@link SubscribeConfig.Builder#setMaxDistanceMm(int)} and the Publish service was configured 195 * with {@link PublishConfig.Builder#setRangingEnabled(boolean)}. 196 * <p> 197 * If either Publisher or Subscriber does not enable Ranging, or if Ranging is temporarily 198 * disabled by the underlying device, service discovery proceeds without ranging and the 199 * {@link #onServiceDiscovered(PeerHandle, byte[], List)} is called. 200 * <p> 201 * Note that this method and {@link #onServiceDiscovered(PeerHandle, byte[], List)} may be 202 * called multiple times per service discovery. 203 * <p> 204 * Note: This method is superseded by 205 * {@link #onServiceDiscoveredWithinRange(ServiceDiscoveryInfo, int)} which returns more 206 * information. Note that both legacy and new callback will be triggered on discovery. 207 * 208 * @param peerHandle An opaque handle to the peer matching our discovery operation. 209 * @param serviceSpecificInfo The service specific information (arbitrary 210 * byte array) provided by the peer as part of its discovery 211 * configuration. 212 * @param matchFilter The filter which resulted in this service discovery. For 213 * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED}, 214 * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE} discovery sessions this is the publisher's 215 * match filter. For {@link PublishConfig#PUBLISH_TYPE_SOLICITED}, 216 * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} discovery sessions this 217 * is the subscriber's match filter. 218 * @param distanceMm The measured distance to the Publisher in mm. Note: the measured distance 219 * may be negative for very close devices. 220 */ onServiceDiscoveredWithinRange(PeerHandle peerHandle, byte[] serviceSpecificInfo, List<byte[]> matchFilter, int distanceMm)221 public void onServiceDiscoveredWithinRange(PeerHandle peerHandle, 222 byte[] serviceSpecificInfo, List<byte[]> matchFilter, int distanceMm) { 223 /* empty */ 224 } 225 226 /** 227 * Called when a subscribe operation results in a 228 * service discovery. Called when a Subscribe service was configured with a range requirement 229 * {@link SubscribeConfig.Builder#setMinDistanceMm(int)} and/or 230 * {@link SubscribeConfig.Builder#setMaxDistanceMm(int)} and the Publish service was configured 231 * with {@link PublishConfig.Builder#setRangingEnabled(boolean)}. 232 * <p> 233 * If either Publisher or Subscriber does not enable Ranging, or if Ranging is temporarily 234 * disabled by the underlying device, service discovery proceeds without ranging and the 235 * {@link #onServiceDiscovered(PeerHandle, byte[], List)} is called. 236 * <p> 237 * Note: This method supersedes 238 * {@link #onServiceDiscoveredWithinRange(PeerHandle, byte[], List, int)} and provides 239 * additional information - including cipher suite type and security context of the peer. Both 240 * the legacy and the new callback will be triggered on discovery. 241 * 242 * @param info A {@link ServiceDiscoveryInfo} which indicate service config of the descovery 243 * sessions. 244 * @param distanceMm The measured distance to the Publisher in mm. Note: the measured distance 245 * may be negative for very close devices. 246 */ onServiceDiscoveredWithinRange(@onNull ServiceDiscoveryInfo info, int distanceMm)247 public void onServiceDiscoveredWithinRange(@NonNull ServiceDiscoveryInfo info, int distanceMm) { 248 /* empty */ 249 } 250 251 /** 252 * Called in response to 253 * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])} 254 * when a message is transmitted successfully - i.e. when it was received successfully by the 255 * peer (corresponds to an ACK being received). 256 * <p> 257 * Note that either this callback or 258 * {@link DiscoverySessionCallback#onMessageSendFailed(int)} will be 259 * received - never both. 260 * 261 * @param messageId The arbitrary message ID specified when sending the message. 262 */ onMessageSendSucceeded(@uppressWarnings"unused") int messageId)263 public void onMessageSendSucceeded(@SuppressWarnings("unused") int messageId) { 264 /* empty */ 265 } 266 267 /** 268 * Called when message transmission initiated with 269 * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])} fails. E.g. when no ACK is 270 * received from the peer. 271 * <p> 272 * Note that either this callback or 273 * {@link DiscoverySessionCallback#onMessageSendSucceeded(int)} will be received 274 * - never both. 275 * 276 * @param messageId The arbitrary message ID specified when sending the message. 277 */ onMessageSendFailed(@uppressWarnings"unused") int messageId)278 public void onMessageSendFailed(@SuppressWarnings("unused") int messageId) { 279 /* empty */ 280 } 281 282 /** 283 * Called when a message is received from a discovery session peer - in response to the 284 * peer's {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])}. 285 * 286 * @param peerHandle An opaque handle to the peer matching our discovery operation. 287 * @param message A byte array containing the message. 288 */ onMessageReceived(PeerHandle peerHandle, byte[] message)289 public void onMessageReceived(PeerHandle peerHandle, byte[] message) { 290 /* empty */ 291 } 292 293 /** 294 * Called when the discovered service is not available. All further operations on this 295 * discovery session will fail. If the service is available again, 296 * {@link #onServiceDiscovered(PeerHandle, byte[], List)} or 297 * {@link #onServiceDiscoveredWithinRange(PeerHandle, byte[], List, int)} will be called. 298 * 299 * @param peerHandle An opaque handle to the peer matching our discovery operation. 300 * @param reason Discovered service lost reason code. One of 301 * {@link WifiAwareManager#WIFI_AWARE_DISCOVERY_LOST_REASON_PEER_NOT_VISIBLE}, 302 * {@link WifiAwareManager#WIFI_AWARE_DISCOVERY_LOST_REASON_UNKNOWN 303 */ onServiceLost(@onNull PeerHandle peerHandle, @WifiAwareManager.DiscoveryLostReasonCode int reason)304 public void onServiceLost(@NonNull PeerHandle peerHandle, 305 @WifiAwareManager.DiscoveryLostReasonCode int reason) { 306 /* empty */ 307 } 308 309 /** 310 * Callback indicating that a pairing request is received from peer. 311 * 312 * @param peerHandle The peer's handle where the request is from 313 * @param requestId The ID of the Aware pairing session 314 */ onPairingSetupRequestReceived(@onNull PeerHandle peerHandle, int requestId)315 public void onPairingSetupRequestReceived(@NonNull PeerHandle peerHandle, int requestId) { 316 317 } 318 319 /** 320 * Callback indicating that a pairing setup process succeeded. 321 * 322 * @param peerHandle The pairing peer handle. 323 * @param alias This is the paired device alias set by the caller. 324 * {@link DiscoverySession#initiatePairingRequest(PeerHandle, String, int, String)} 325 * or 326 * {@link DiscoverySession#acceptPairingRequest(int, PeerHandle, String, int, String)} 327 */ onPairingSetupSucceeded(@onNull PeerHandle peerHandle, @NonNull String alias)328 public void onPairingSetupSucceeded(@NonNull PeerHandle peerHandle, 329 @NonNull String alias) { 330 331 } 332 333 /** 334 * Callback indicating that a pairing setup process failed. 335 * 336 * @param peerHandle The pairing peer handle. 337 */ onPairingSetupFailed(@onNull PeerHandle peerHandle)338 public void onPairingSetupFailed(@NonNull PeerHandle peerHandle) { 339 340 } 341 342 /** 343 * Callback indicating that a pairing verification process succeeded. 344 * 345 * @param peerHandle The pairing peer handle 346 * @param alias This is the paired device alias set by the caller. 347 * {@link DiscoverySession#initiatePairingRequest(PeerHandle, String, int, String)} 348 * or 349 * {@link DiscoverySession#acceptPairingRequest(int, PeerHandle, String, int, String)} 350 */ onPairingVerificationSucceed(@onNull PeerHandle peerHandle, @NonNull String alias)351 public void onPairingVerificationSucceed(@NonNull PeerHandle peerHandle, 352 @NonNull String alias){ 353 354 } 355 356 /** 357 * Callback indicating that a pairing verification process failed. 358 * 359 * @param peerHandle The pairing peer handle 360 */ onPairingVerificationFailed(@onNull PeerHandle peerHandle)361 public void onPairingVerificationFailed(@NonNull PeerHandle peerHandle) { 362 363 } 364 365 /** 366 * Callback indicating that a Bootstrapping method negotiation succeeded. 367 * The follow-up out-of-band bootstrapping can start 368 * 369 * @param peerHandle The bootstrapping peer handle 370 * @param method The bootstrapping method accept by the peer 371 */ onBootstrappingSucceeded(@onNull PeerHandle peerHandle, @AwarePairingConfig.BootstrappingMethod int method)372 public void onBootstrappingSucceeded(@NonNull PeerHandle peerHandle, 373 @AwarePairingConfig.BootstrappingMethod int method){ 374 375 } 376 377 /** 378 * Callback indicating that a Bootstrapping method negotiation failed. 379 * 380 * @param peerHandle The bootstrapping peer handle 381 */ onBootstrappingFailed(@onNull PeerHandle peerHandle)382 public void onBootstrappingFailed(@NonNull PeerHandle peerHandle) { 383 384 } 385 } 386