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