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     *
99     * @param peerHandle An opaque handle to the peer matching our discovery operation.
100     * @param serviceSpecificInfo The service specific information (arbitrary
101     *            byte array) provided by the peer as part of its discovery
102     *            configuration.
103     * @param matchFilter The filter which resulted in this service discovery.
104     */
105    public void onServiceDiscovered(PeerHandle peerHandle,
106            byte[] serviceSpecificInfo, List<byte[]> matchFilter) {
107        /* empty */
108    }
109
110    /**
111     * Called in response to
112     * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])}
113     * when a message is transmitted successfully - i.e. when it was received successfully by the
114     * peer (corresponds to an ACK being received).
115     * <p>
116     * Note that either this callback or
117     * {@link DiscoverySessionCallback#onMessageSendFailed(int)} will be
118     * received - never both.
119     *
120     * @param messageId The arbitrary message ID specified when sending the message.
121     */
122    public void onMessageSendSucceeded(@SuppressWarnings("unused") int messageId) {
123        /* empty */
124    }
125
126    /**
127     * Called when message transmission initiated with
128     * {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])} fails. E.g. when no ACK is
129     * received from the peer.
130     * <p>
131     * Note that either this callback or
132     * {@link DiscoverySessionCallback#onMessageSendSucceeded(int)} will be received
133     * - never both.
134     *
135     * @param messageId The arbitrary message ID specified when sending the message.
136     */
137    public void onMessageSendFailed(@SuppressWarnings("unused") int messageId) {
138        /* empty */
139    }
140
141    /**
142     * Called when a message is received from a discovery session peer - in response to the
143     * peer's {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])}.
144     *
145     * @param peerHandle An opaque handle to the peer matching our discovery operation.
146     * @param message A byte array containing the message.
147     */
148    public void onMessageReceived(PeerHandle peerHandle, byte[] message) {
149        /* empty */
150    }
151}
152