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.nl80211;
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.MacAddress;
24 import android.os.Parcel;
25 import android.os.Parcelable;
26 import android.util.Log;
27 
28 import com.android.internal.annotations.VisibleForTesting;
29 
30 import java.lang.annotation.Retention;
31 import java.lang.annotation.RetentionPolicy;
32 import java.util.ArrayList;
33 import java.util.Arrays;
34 import java.util.List;
35 
36 /**
37  * Raw scan result data from the wificond daemon.
38  *
39  * @hide
40  */
41 @SystemApi
42 public final class NativeScanResult implements Parcelable {
43     private static final String TAG = "NativeScanResult";
44 
45     /** @hide */
46     @VisibleForTesting
47     public byte[] ssid;
48     /** @hide */
49     @VisibleForTesting
50     public byte[] bssid;
51     /** @hide */
52     @VisibleForTesting
53     public byte[] infoElement;
54     /** @hide */
55     @VisibleForTesting
56     public int frequency;
57     /** @hide */
58     @VisibleForTesting
59     public int signalMbm;
60     /** @hide */
61     @VisibleForTesting
62     public long tsf;
63     /** @hide */
64     @VisibleForTesting
65     @BssCapabilityBits public int capability;
66     /** @hide */
67     @VisibleForTesting
68     public boolean associated;
69     /** @hide */
70     @VisibleForTesting
71     public List<RadioChainInfo> radioChainInfos;
72 
73     /**
74      * Returns the SSID raw byte array of the AP represented by this scan result.
75      *
76      * @return A byte array.
77      */
getSsid()78     @NonNull public byte[] getSsid() {
79         return ssid;
80     }
81 
82     /**
83      * Returns the MAC address (BSSID) of the AP represented by this scan result.
84      *
85      * @return a MacAddress or null on error.
86      */
getBssid()87     @Nullable public MacAddress getBssid() {
88         try {
89             return MacAddress.fromBytes(bssid);
90         } catch (IllegalArgumentException e) {
91             Log.e(TAG, "Illegal argument " + Arrays.toString(bssid), e);
92             return null;
93         }
94     }
95 
96     /**
97      * Returns the raw bytes of the information element advertised by the AP represented by this
98      * scan result.
99      *
100      * @return A byte array, possibly null or containing an invalid TLV configuration.
101      */
getInformationElements()102     @NonNull public byte[] getInformationElements() {
103         return infoElement;
104     }
105 
106     /**
107      * Returns the frequency (in MHz) on which the AP represented by this scan result was observed.
108      *
109      * @return The frequency in MHz.
110      */
getFrequencyMhz()111     public int getFrequencyMhz() {
112         return frequency;
113     }
114 
115     /**
116      * Return the signal strength of probe response/beacon in (100 * dBm).
117      *
118      * @return Signal strenght in (100 * dBm).
119      */
getSignalMbm()120     public int getSignalMbm() {
121         return signalMbm;
122     }
123 
124     /**
125      * Return the TSF (Timing Synchronization Function) of the received probe response/beacon.
126      * @return
127      */
getTsf()128     public long getTsf() {
129         return tsf;
130     }
131 
132     /**
133      * Return a boolean indicating whether or not we're associated to the AP represented by this
134      * scan result.
135      *
136      * @return A boolean indicating association.
137      */
isAssociated()138     public boolean isAssociated() {
139         return associated;
140     }
141 
142     /** @hide */
143     @Retention(RetentionPolicy.SOURCE)
144     @IntDef(flag = true, prefix = {"BSS_CAPABILITY_"},
145             value = {BSS_CAPABILITY_ESS,
146                     BSS_CAPABILITY_IBSS,
147                     BSS_CAPABILITY_CF_POLLABLE,
148                     BSS_CAPABILITY_CF_POLL_REQUEST,
149                     BSS_CAPABILITY_PRIVACY,
150                     BSS_CAPABILITY_SHORT_PREAMBLE,
151                     BSS_CAPABILITY_PBCC,
152                     BSS_CAPABILITY_CHANNEL_AGILITY,
153                     BSS_CAPABILITY_SPECTRUM_MANAGEMENT,
154                     BSS_CAPABILITY_QOS,
155                     BSS_CAPABILITY_SHORT_SLOT_TIME,
156                     BSS_CAPABILITY_APSD,
157                     BSS_CAPABILITY_RADIO_MANAGEMENT,
158                     BSS_CAPABILITY_DSSS_OFDM,
159                     BSS_CAPABILITY_DELAYED_BLOCK_ACK,
160                     BSS_CAPABILITY_IMMEDIATE_BLOCK_ACK
161             })
162     public @interface BssCapabilityBits { }
163 
164     /**
165      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): ESS.
166      */
167     public static final int BSS_CAPABILITY_ESS = 0x1 << 0;
168     /**
169      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): IBSS.
170      */
171     public static final int BSS_CAPABILITY_IBSS = 0x1 << 1;
172     /**
173      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): CF Pollable.
174      */
175     public static final int BSS_CAPABILITY_CF_POLLABLE = 0x1 << 2;
176     /**
177      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): CF-Poll Request.
178      */
179     public static final int BSS_CAPABILITY_CF_POLL_REQUEST = 0x1 << 3;
180     /**
181      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): Privacy.
182      */
183     public static final int BSS_CAPABILITY_PRIVACY = 0x1 << 4;
184     /**
185      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): Short Preamble.
186      */
187     public static final int BSS_CAPABILITY_SHORT_PREAMBLE = 0x1 << 5;
188     /**
189      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): PBCC.
190      */
191     public static final int BSS_CAPABILITY_PBCC = 0x1 << 6;
192     /**
193      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): Channel Agility.
194      */
195     public static final int BSS_CAPABILITY_CHANNEL_AGILITY = 0x1 << 7;
196     /**
197      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): Spectrum Management.
198      */
199     public static final int BSS_CAPABILITY_SPECTRUM_MANAGEMENT = 0x1 << 8;
200     /**
201      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): QoS.
202      */
203     public static final int BSS_CAPABILITY_QOS = 0x1 << 9;
204     /**
205      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): Short Slot Time.
206      */
207     public static final int BSS_CAPABILITY_SHORT_SLOT_TIME = 0x1 << 10;
208     /**
209      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): APSD.
210      */
211     public static final int BSS_CAPABILITY_APSD = 0x1 << 11;
212     /**
213      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): Radio Management.
214      */
215     public static final int BSS_CAPABILITY_RADIO_MANAGEMENT = 0x1 << 12;
216     /**
217      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): DSSS-OFDM.
218      */
219     public static final int BSS_CAPABILITY_DSSS_OFDM = 0x1 << 13;
220     /**
221      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): Delayed Block Ack.
222      */
223     public static final int BSS_CAPABILITY_DELAYED_BLOCK_ACK = 0x1 << 14;
224     /**
225      * BSS capability bit (see IEEE Std 802.11: 9.4.1.4): Immediate Block Ack.
226      */
227     public static final int BSS_CAPABILITY_IMMEDIATE_BLOCK_ACK = 0x1 << 15;
228 
229     /**
230      *  Returns the capabilities of the AP repseresented by this scan result as advertised in the
231      *  received probe response or beacon.
232      *
233      *  This is a bit mask describing the capabilities of a BSS. See IEEE Std 802.11: 9.4.1.4: one
234      *  of the {@code BSS_CAPABILITY_*} flags.
235      *
236      * @return a bit mask of capabilities.
237      */
getCapabilities()238     @BssCapabilityBits public int getCapabilities() {
239         return capability;
240     }
241 
242     /**
243      * Returns details of the signal received on each radio chain for the AP represented by this
244      * scan result in a list of {@link RadioChainInfo} elements.
245      *
246      * @return A list of {@link RadioChainInfo} - possibly empty in case of error.
247      */
getRadioChainInfos()248     @NonNull public List<RadioChainInfo> getRadioChainInfos() {
249         return radioChainInfos;
250     }
251 
252     /**
253      * Construct an empty native scan result.
254      */
NativeScanResult()255     public NativeScanResult() { }
256 
257     /** implement Parcelable interface */
258     @Override
describeContents()259     public int describeContents() {
260         return 0;
261     }
262 
263     /** implement Parcelable interface */
264     @Override
writeToParcel(@onNull Parcel out, int flags)265     public void writeToParcel(@NonNull Parcel out, int flags) {
266         out.writeByteArray(ssid);
267         out.writeByteArray(bssid);
268         out.writeByteArray(infoElement);
269         out.writeInt(frequency);
270         out.writeInt(signalMbm);
271         out.writeLong(tsf);
272         out.writeInt(capability);
273         out.writeInt(associated ? 1 : 0);
274         out.writeTypedList(radioChainInfos);
275     }
276 
277     /** implement Parcelable interface */
278     @NonNull public static final Parcelable.Creator<NativeScanResult> CREATOR =
279             new Parcelable.Creator<NativeScanResult>() {
280         @Override
281         public NativeScanResult createFromParcel(Parcel in) {
282             NativeScanResult result = new NativeScanResult();
283             result.ssid = in.createByteArray();
284             if (result.ssid == null) {
285                 result.ssid = new byte[0];
286             }
287             result.bssid = in.createByteArray();
288             if (result.bssid == null) {
289                 result.bssid = new byte[0];
290             }
291             result.infoElement = in.createByteArray();
292             if (result.infoElement == null) {
293                 result.infoElement = new byte[0];
294             }
295             result.frequency = in.readInt();
296             result.signalMbm = in.readInt();
297             result.tsf = in.readLong();
298             result.capability = in.readInt();
299             result.associated = (in.readInt() != 0);
300             result.radioChainInfos = new ArrayList<>();
301             in.readTypedList(result.radioChainInfos, RadioChainInfo.CREATOR);
302             return result;
303         }
304 
305         @Override
306         public NativeScanResult[] newArray(int size) {
307             return new NativeScanResult[size];
308         }
309     };
310 }
311