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
17package android.net.wifi.aware;
18
19import android.annotation.NonNull;
20
21import 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 */
34public 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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
189    public void onMessageReceived(PeerHandle peerHandle, byte[] message) {
190        /* empty */
191    }
192}
193