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 discovery (publish or subscribe) operation results in a 97 * service discovery. 98 * <p> 99 * Note that this method and 100 * {@link #onServiceDiscoveredWithinRange(PeerHandle, byte[], List, int)} may be called 101 * multiple times per service discovery. 102 * 103 * @param peerHandle An opaque handle to the peer matching our discovery operation. 104 * @param serviceSpecificInfo The service specific information (arbitrary 105 * byte array) provided by the peer as part of its discovery 106 * configuration. 107 * @param matchFilter The filter which resulted in this service discovery. For 108 * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED}, 109 * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE} discovery sessions this is the publisher's 110 * match filter. For {@link PublishConfig#PUBLISH_TYPE_SOLICITED}, 111 * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} discovery sessions this 112 * is the subscriber's match filter. 113 */ onServiceDiscovered(PeerHandle peerHandle, byte[] serviceSpecificInfo, List<byte[]> matchFilter)114 public void onServiceDiscovered(PeerHandle peerHandle, 115 byte[] serviceSpecificInfo, List<byte[]> matchFilter) { 116 /* empty */ 117 } 118 119 /** 120 * Called when a discovery (publish or subscribe) operation results in a 121 * service discovery. Called when a Subscribe service was configured with a range requirement 122 * {@link SubscribeConfig.Builder#setMinDistanceMm(int)} and/or 123 * {@link SubscribeConfig.Builder#setMaxDistanceMm(int)} and the Publish service was configured 124 * with {@link PublishConfig.Builder#setRangingEnabled(boolean)}. 125 * <p> 126 * If either Publisher or Subscriber does not enable Ranging, or if Ranging is temporarily 127 * disabled by the underlying device, service discovery proceeds without ranging and the 128 * {@link #onServiceDiscovered(PeerHandle, byte[], List)} is called. 129 * <p> 130 * Note that this method and {@link #onServiceDiscovered(PeerHandle, byte[], List)} may be 131 * called multiple times per service discovery. 132 * 133 * @param peerHandle An opaque handle to the peer matching our discovery operation. 134 * @param serviceSpecificInfo The service specific information (arbitrary 135 * byte array) provided by the peer as part of its discovery 136 * configuration. 137 * @param matchFilter The filter which resulted in this service discovery. For 138 * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED}, 139 * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE} discovery sessions this is the publisher's 140 * match filter. For {@link PublishConfig#PUBLISH_TYPE_SOLICITED}, 141 * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} discovery sessions this 142 * is the subscriber's match filter. 143 * @param distanceMm The measured distance to the Publisher in mm. Note: the measured distance 144 * may be negative for very close devices. 145 */ onServiceDiscoveredWithinRange(PeerHandle peerHandle, byte[] serviceSpecificInfo, List<byte[]> matchFilter, int distanceMm)146 public void onServiceDiscoveredWithinRange(PeerHandle peerHandle, 147 byte[] serviceSpecificInfo, List<byte[]> matchFilter, int distanceMm) { 148 /* empty */ 149 } 150 151 /** 152 * Called in response to 153 * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])} 154 * when a message is transmitted successfully - i.e. when it was received successfully by the 155 * peer (corresponds to an ACK being received). 156 * <p> 157 * Note that either this callback or 158 * {@link DiscoverySessionCallback#onMessageSendFailed(int)} will be 159 * received - never both. 160 * 161 * @param messageId The arbitrary message ID specified when sending the message. 162 */ onMessageSendSucceeded(@uppressWarnings"unused") int messageId)163 public void onMessageSendSucceeded(@SuppressWarnings("unused") int messageId) { 164 /* empty */ 165 } 166 167 /** 168 * Called when message transmission initiated with 169 * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])} fails. E.g. when no ACK is 170 * received from the peer. 171 * <p> 172 * Note that either this callback or 173 * {@link DiscoverySessionCallback#onMessageSendSucceeded(int)} will be received 174 * - never both. 175 * 176 * @param messageId The arbitrary message ID specified when sending the message. 177 */ onMessageSendFailed(@uppressWarnings"unused") int messageId)178 public void onMessageSendFailed(@SuppressWarnings("unused") int messageId) { 179 /* empty */ 180 } 181 182 /** 183 * Called when a message is received from a discovery session peer - in response to the 184 * peer's {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])}. 185 * 186 * @param peerHandle An opaque handle to the peer matching our discovery operation. 187 * @param message A byte array containing the message. 188 */ onMessageReceived(PeerHandle peerHandle, byte[] message)189 public void onMessageReceived(PeerHandle peerHandle, byte[] message) { 190 /* empty */ 191 } 192 } 193