1 /*
2  * Copyright (C) 2018 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;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 import android.annotation.Nullable;
22 import android.annotation.SystemApi;
23 import android.net.Uri;
24 import android.os.Build;
25 import android.util.SparseArray;
26 
27 import androidx.annotation.RequiresApi;
28 
29 import java.lang.annotation.Retention;
30 import java.lang.annotation.RetentionPolicy;
31 import java.util.concurrent.Executor;
32 
33 /**
34  * Easy Connect (DPP) Status Callback. Use this callback to get status updates (success, failure,
35  * progress) from the Easy Connect operations.
36  */
37 public abstract class EasyConnectStatusCallback {
38     /**
39      * Easy Connect R1 Success event: Configuration sent (Configurator mode). This is the last
40      * and final Easy Connect event when either the local device or remote device implement R1.
41      * If both devices implement R2, this event will never be received, and the
42      * {@link #EASY_CONNECT_EVENT_SUCCESS_CONFIGURATION_APPLIED} will be received.
43      * @hide
44      */
45     @SystemApi
46     public static final int EASY_CONNECT_EVENT_SUCCESS_CONFIGURATION_SENT = 0;
47 
48     /**
49      * Easy Connect R2 Success event: Configuration applied by Enrollee (Configurator mode).
50      * This is the last and final Easy Connect event when both the local device and remote device
51      * implement R2. If either the local device or remote device implement R1, this event will never
52      * be received, and the {@link #EASY_CONNECT_EVENT_SUCCESS_CONFIGURATION_SENT} will be received.
53      * @hide
54      */
55     @SystemApi
56     public static final int EASY_CONNECT_EVENT_SUCCESS_CONFIGURATION_APPLIED = 1;
57 
58     /** @hide */
59     @IntDef(prefix = {"EASY_CONNECT_EVENT_SUCCESS_"}, value = {
60             EASY_CONNECT_EVENT_SUCCESS_CONFIGURATION_SENT,
61             EASY_CONNECT_EVENT_SUCCESS_CONFIGURATION_APPLIED,
62     })
63     @Retention(RetentionPolicy.SOURCE)
64     public @interface EasyConnectSuccessStatusCode {
65     }
66 
67     /**
68      * Easy Connect Progress event: Initial authentication with peer succeeded.
69      * @hide
70      */
71     @SystemApi
72     public static final int EASY_CONNECT_EVENT_PROGRESS_AUTHENTICATION_SUCCESS = 0;
73 
74     /**
75      * Easy Connect Progress event: Peer requires more time to process bootstrapping.
76      * @hide
77      */
78     @SystemApi
79     public static final int EASY_CONNECT_EVENT_PROGRESS_RESPONSE_PENDING = 1;
80 
81     /**
82      * Easy Connect R2 Progress event: Configuration sent to Enrollee, waiting for response
83      * @hide
84      */
85     @SystemApi
86     public static final int EASY_CONNECT_EVENT_PROGRESS_CONFIGURATION_SENT_WAITING_RESPONSE = 2;
87 
88     /**
89      * Easy Connect R2 Progress event: Configuration accepted by Enrollee, waiting for response
90      * @hide
91      */
92     @SystemApi
93     public static final int EASY_CONNECT_EVENT_PROGRESS_CONFIGURATION_ACCEPTED = 3;
94 
95     /** @hide */
96     @IntDef(prefix = {"EASY_CONNECT_EVENT_PROGRESS_"}, value = {
97             EASY_CONNECT_EVENT_PROGRESS_AUTHENTICATION_SUCCESS,
98             EASY_CONNECT_EVENT_PROGRESS_RESPONSE_PENDING,
99             EASY_CONNECT_EVENT_PROGRESS_CONFIGURATION_SENT_WAITING_RESPONSE,
100             EASY_CONNECT_EVENT_PROGRESS_CONFIGURATION_ACCEPTED,
101     })
102     @Retention(RetentionPolicy.SOURCE)
103     public @interface EasyConnectProgressStatusCode {
104     }
105 
106     /**
107      * Easy Connect Failure event: Scanned QR code is either not a Easy Connect URI, or the Easy
108      * Connect URI has errors.
109      */
110     public static final int EASY_CONNECT_EVENT_FAILURE_INVALID_URI = -1;
111 
112     /**
113      * Easy Connect Failure event: Bootstrapping/Authentication initialization process failure.
114      */
115     public static final int EASY_CONNECT_EVENT_FAILURE_AUTHENTICATION = -2;
116 
117     /**
118      * Easy Connect Failure event: Both devices are implementing the same role and are incompatible.
119      */
120     public static final int EASY_CONNECT_EVENT_FAILURE_NOT_COMPATIBLE = -3;
121 
122     /**
123      * Easy Connect Failure event: Configuration process has failed due to malformed message.
124      */
125     public static final int EASY_CONNECT_EVENT_FAILURE_CONFIGURATION = -4;
126 
127     /**
128      * Easy Connect Failure event: Easy Connect request while in another Easy Connect exchange.
129      */
130     public static final int EASY_CONNECT_EVENT_FAILURE_BUSY = -5;
131 
132     /**
133      * Easy Connect Failure event: No response from the peer.
134      */
135     public static final int EASY_CONNECT_EVENT_FAILURE_TIMEOUT = -6;
136 
137     /**
138      * Easy Connect Failure event: General protocol failure.
139      */
140     public static final int EASY_CONNECT_EVENT_FAILURE_GENERIC = -7;
141 
142     /**
143      * Easy Connect Failure event: Feature or option is not supported.
144      */
145     public static final int EASY_CONNECT_EVENT_FAILURE_NOT_SUPPORTED = -8;
146 
147     /**
148      * Easy Connect Failure event: Invalid network provided to Easy Connect configurator.
149      * Network must either be WPA3-Personal (SAE) or WPA2-Personal (PSK).
150      */
151     public static final int EASY_CONNECT_EVENT_FAILURE_INVALID_NETWORK = -9;
152 
153     /**
154      * Easy Connect R2 Failure event: Enrollee cannot find the network.
155      */
156     public static final int EASY_CONNECT_EVENT_FAILURE_CANNOT_FIND_NETWORK = -10;
157 
158     /**
159      * Easy Connect R2 Failure event: Enrollee failed to authenticate with the network.
160      */
161     public static final int EASY_CONNECT_EVENT_FAILURE_ENROLLEE_AUTHENTICATION = -11;
162 
163     /**
164      * Easy Connect R2 Failure event: Enrollee rejected the configuration.
165      */
166     public static final int EASY_CONNECT_EVENT_FAILURE_ENROLLEE_REJECTED_CONFIGURATION = -12;
167 
168     /**
169      * Easy Connect Failure event: System failed to generate DPP URI.
170      */
171     public static final int EASY_CONNECT_EVENT_FAILURE_URI_GENERATION = -13;
172 
173     /**
174      * Easy Connect Failure event: Enrollee didn't scan the network's operating channel.
175      * This error is generated when framework finds that Network's operating channel
176      * is not included in the list of channels the Enrollee scanned in attempting to
177      * discover the network prior to connection.
178      */
179     public static final int EASY_CONNECT_EVENT_FAILURE_ENROLLEE_FAILED_TO_SCAN_NETWORK_CHANNEL =
180             -14;
181 
182     /** @hide */
183     @IntDef(prefix = {"EASY_CONNECT_EVENT_FAILURE_"}, value = {
184             EASY_CONNECT_EVENT_FAILURE_INVALID_URI,
185             EASY_CONNECT_EVENT_FAILURE_AUTHENTICATION,
186             EASY_CONNECT_EVENT_FAILURE_NOT_COMPATIBLE,
187             EASY_CONNECT_EVENT_FAILURE_CONFIGURATION,
188             EASY_CONNECT_EVENT_FAILURE_BUSY,
189             EASY_CONNECT_EVENT_FAILURE_TIMEOUT,
190             EASY_CONNECT_EVENT_FAILURE_GENERIC,
191             EASY_CONNECT_EVENT_FAILURE_NOT_SUPPORTED,
192             EASY_CONNECT_EVENT_FAILURE_INVALID_NETWORK,
193             EASY_CONNECT_EVENT_FAILURE_CANNOT_FIND_NETWORK,
194             EASY_CONNECT_EVENT_FAILURE_ENROLLEE_AUTHENTICATION,
195             EASY_CONNECT_EVENT_FAILURE_ENROLLEE_REJECTED_CONFIGURATION,
196             EASY_CONNECT_EVENT_FAILURE_URI_GENERATION,
197             EASY_CONNECT_EVENT_FAILURE_ENROLLEE_FAILED_TO_SCAN_NETWORK_CHANNEL,
198     })
199     @Retention(RetentionPolicy.SOURCE)
200     public @interface EasyConnectFailureStatusCode {
201     }
202 
203     /** @hide */
204     @SystemApi
EasyConnectStatusCallback()205     public EasyConnectStatusCallback() {
206         // Fully-static utility classes must not have constructor
207     }
208 
209     /**
210      * Called when local Easy Connect Enrollee successfully receives a new Wi-Fi configuration from
211      * the
212      * peer Easy Connect configurator. This callback marks the successful end of the Easy Connect
213      * current Easy Connect
214      * session, and no further callbacks will be called. This callback is the successful outcome
215      * of a Easy Connect flow starting with
216      * {@link WifiManager#startEasyConnectAsEnrolleeInitiator(String, Executor,
217      * EasyConnectStatusCallback)} .
218      *
219      * @param newNetworkId New Wi-Fi configuration with a network ID received from the configurator
220      * @hide
221      */
222     @SystemApi
onEnrolleeSuccess(int newNetworkId)223     public abstract void onEnrolleeSuccess(int newNetworkId);
224 
225     /**
226      * Called when a Easy Connect success event takes place, except for when configuration is
227      * received from an external Configurator. The callback onSuccessConfigReceived will be used in
228      * this case. This callback marks the successful end of the current Easy Connect session, and no
229      * further callbacks will be called. This callback is the successful outcome of a Easy Connect
230      * flow starting with {@link WifiManager#startEasyConnectAsConfiguratorInitiator(String, int,
231      * int, Executor,EasyConnectStatusCallback)}.
232      *
233      * @param code Easy Connect success status code.
234      * @hide
235      */
236     @SystemApi
onConfiguratorSuccess(@asyConnectSuccessStatusCode int code)237     public abstract void onConfiguratorSuccess(@EasyConnectSuccessStatusCode int code);
238 
239     /**
240      * Called when a Easy Connect Failure event takes place. This callback marks the unsuccessful
241      * end of the current Easy Connect session, and no further callbacks will be called.
242      *
243      * @param code Easy Connect failure status code.
244      * @hide
245      */
246     @SystemApi
onFailure(@asyConnectFailureStatusCode int code)247     public void onFailure(@EasyConnectFailureStatusCode int code) {}
248 
249     /**
250      * Called when a Easy Connect Failure event takes place. This callback marks the unsuccessful
251      * end of the current Easy Connect session, and no further callbacks will be called.
252      *
253      * Note: Easy Connect (DPP) R2, provides additional details for the Configurator when the
254      * remote Enrollee is unable to connect to a network. The ssid, channelList and bandList
255      * inputs are initialized only for the EASY_CONNECT_EVENT_FAILURE_CANNOT_FIND_NETWORK failure
256      * code, and the ssid and bandList are initialized for the
257      * EASY_CONNECT_EVENT_FAILURE_ENROLLEE_AUTHENTICATION failure code.
258      *
259      * @param code Easy Connect failure status code.
260      * @param ssid SSID of the network the Enrollee tried to connect to.
261      * @param channelListArray List of Global Operating classes and channel sets the Enrollee used
262      *                         to scan to find the network, see the "DPP Connection Status Object"
263      *                         section in the specification for the format, and Table E-4 in
264      *                         IEEE Std 802.11-2016 - Global operating classes for more details.
265      *                         The sparse array key is the Global Operating class, and the value
266      *                         is an integer array of Wi-Fi channels.
267      * @param operatingClassArray Array of bands the Enrollee supports as expressed as the Global
268      *                            Operating Class, see Table E-4 in IEEE Std 802.11-2016 - Global
269      *                            operating classes.
270      * @hide
271      */
272     @SystemApi
onFailure(@asyConnectFailureStatusCode int code, @Nullable String ssid, @NonNull SparseArray<int[]> channelListArray, @NonNull int[] operatingClassArray)273     public void onFailure(@EasyConnectFailureStatusCode int code, @Nullable String ssid,
274             @NonNull SparseArray<int[]> channelListArray, @NonNull int[] operatingClassArray) {
275         onFailure(code);
276     }
277 
278     /**
279      * Called when Easy Connect events that indicate progress take place. Can be used by UI elements
280      * to show progress.
281      *
282      * @param code Easy Connect progress status code.
283      * @hide
284      */
285     @SystemApi
onProgress(@asyConnectProgressStatusCode int code)286     public abstract void onProgress(@EasyConnectProgressStatusCode int code);
287 
288     /**
289      * Called when local Easy Connect Responder successfully generates a DPP URI from
290      * the supplicant. This callback is the first successful outcome
291      * of a Easy Connect Responder flow starting with
292      * {@link WifiManager#startEasyConnectAsEnrolleeResponder(String, int, Executor,
293      * EasyConnectStatusCallback)} .
294      *
295      * @param dppUri DPP URI from the supplicant.
296      * @hide
297      */
298     @SystemApi
299     @RequiresApi(Build.VERSION_CODES.S)
onBootstrapUriGenerated(@onNull Uri dppUri)300     public void onBootstrapUriGenerated(@NonNull Uri dppUri) {};
301 }
302