1 /*
2  * Copyright (C) 2022 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.aware;
18 
19 import android.annotation.IntRange;
20 import android.annotation.NonNull;
21 import android.annotation.SystemApi;
22 import android.os.Parcel;
23 import android.os.Parcelable;
24 
25 /**
26  * An object to use with {@link WifiAwareManager#setAwareParams(AwareParams)} specifying
27  * configuration of the Wi-Fi Aware protocol implementation.
28  * @hide
29  */
30 @SystemApi
31 public final class AwareParams implements Parcelable {
32 
33     /**
34      *  An integer representing the parameter is never set.
35      */
36     public static final int UNSET_PARAMETER = -1;
37 
38     private int mDw24Ghz = UNSET_PARAMETER;
39     private int mDw5Ghz = UNSET_PARAMETER;
40     private int mDw6Ghz = UNSET_PARAMETER;
41     private int mDiscoveryBeaconIntervalMs = UNSET_PARAMETER;
42     private int mNumSpatialStreamsInDiscovery = UNSET_PARAMETER;
43     private boolean mIsDwEarlyTerminationEnabled = false;
44     private int mMacRandomIntervalSec = UNSET_PARAMETER;
45 
46     /**
47      * Construct an empty {@link AwareParams}.
48      */
AwareParams()49     public AwareParams() {
50     }
51 
AwareParams(Parcel in)52     private AwareParams(Parcel in) {
53         mDw24Ghz = in.readInt();
54         mDw5Ghz = in.readInt();
55         mDw6Ghz = in.readInt();
56         mDiscoveryBeaconIntervalMs = in.readInt();
57         mNumSpatialStreamsInDiscovery = in.readInt();
58         mIsDwEarlyTerminationEnabled = in.readBoolean();
59         mMacRandomIntervalSec = in.readInt();
60     }
61 
62     public static final @NonNull Creator<AwareParams> CREATOR = new Creator<AwareParams>() {
63         @Override
64         public AwareParams createFromParcel(Parcel in) {
65             return new AwareParams(in);
66         }
67 
68         @Override
69         public AwareParams[] newArray(int size) {
70             return new AwareParams[size];
71         }
72     };
73 
74     /**
75      * Specifies the discovery window (DW) interval for Sync beacons and SDF frames for 2.4Ghz.
76      * Defined as per Wi-Fi Alliance (WFA) Wi-Fi Aware specifications version 3.1 Section 4.1.1.1
77      * Valid values of DW Interval are: 1, 2, 3, 4 and 5 corresponding to waking up every  1, 2, 4,
78      * 8, and 16 DWs.
79      * @param dw A positive number specifying the discovery window (DW) interval
80      */
setDiscoveryWindowWakeInterval24Ghz(@ntRangefrom = 1, to = 5) int dw)81     public void setDiscoveryWindowWakeInterval24Ghz(@IntRange(from = 1, to = 5) int dw) {
82         if (dw > 5 || dw < 1) {
83             throw new IllegalArgumentException("DW value for 2.4Ghz must be 1 to 5");
84         }
85         mDw24Ghz = dw;
86     }
87 
88     /**
89      * Specifies the discovery window (DW) interval for Sync beacons and SDF frames for 5Ghz.
90      * Defined as per Wi-Fi Alliance (WFA) Wi-Fi Aware specifications version 3.1 Section 4.1.1.1
91      * <ul>
92      *     <li>0: indicating no discovery in the 5GHz band</li>
93      * <li>1, 2, 3, 4, or 5: corresponding to waking up every 1, 2, 4, 8, and 16 DWs.</li>
94      * </ul>
95      * @param dw An integer specifying the discovery window (DW) interval
96      */
setDiscoveryWindowWakeInterval5Ghz(@ntRangefrom = 0, to = 5) int dw)97     public void setDiscoveryWindowWakeInterval5Ghz(@IntRange(from = 0, to = 5) int dw) {
98         if (dw > 5 || dw < 0) {
99             throw new IllegalArgumentException("DW value for 5Ghz must be 0 to 5");
100         }
101         mDw5Ghz = dw;
102     }
103 
104     /**
105      * Set the discovery windows (DW) for 6Ghz reserved.
106      * @param dw An integer specifying the discovery window (DW) interval
107      * @hide
108      */
setDiscoveryWindow6Ghz(@ntRangefrom = 0) int dw)109     public void setDiscoveryWindow6Ghz(@IntRange(from = 0) int dw) {
110         mDw6Ghz = dw;
111     }
112 
113     /**
114      * Specify the Discovery Beacon interval in ms. Specification only applicable if the device
115      * transmits Discovery Beacons (based on the Wi-Fi Aware protocol selection criteria). The value
116      * can be increased to reduce power consumption (on devices which would transmit Discovery
117      * Beacons), however - cluster synchronization time will likely increase.
118      * @param intervalInMs An integer specifying the interval in millisecond
119      */
setDiscoveryBeaconIntervalMillis(@ntRangefrom = 1) int intervalInMs)120     public void setDiscoveryBeaconIntervalMillis(@IntRange(from = 1) int intervalInMs) {
121         if (intervalInMs < 1) {
122             throw new IllegalArgumentException("Discovery Beacon interval must >= 1");
123         }
124         mDiscoveryBeaconIntervalMs = intervalInMs;
125     }
126 
127     /**
128      * The number of spatial streams to be used for transmitting Wi-Fi Aware management frames (does
129      * NOT apply to data-path packets). A small value may reduce power consumption for small
130      * discovery packets.
131      * @param spatialStreamsNum A positive number specifying the number of spatial streams
132      */
setNumSpatialStreamsInDiscovery(@ntRangefrom = 1) int spatialStreamsNum)133     public void setNumSpatialStreamsInDiscovery(@IntRange(from = 1) int spatialStreamsNum) {
134         if (spatialStreamsNum < 1) {
135             throw new IllegalArgumentException("Number Spatial streams must >= 1");
136         }
137         mNumSpatialStreamsInDiscovery = spatialStreamsNum;
138     }
139 
140     /**
141      * Specifies the interval in seconds that the Wi-Fi Aware management interface MAC address is
142      * re-randomized.
143      * @param intervalSec A positive number indicating the interval for the MAC address to
144      *                    re-randomize, must not exceed 1800 second (30 mins).
145      */
setMacRandomizationIntervalSeconds(@ntRangefrom = 1, to = 1800) int intervalSec)146     public void setMacRandomizationIntervalSeconds(@IntRange(from = 1, to = 1800) int intervalSec) {
147         if (intervalSec > 1800 || intervalSec < 1) {
148             throw new IllegalArgumentException("Mac Randomization Interval must be between 1 to "
149                     + "1800 seconds");
150         }
151         mMacRandomIntervalSec = intervalSec;
152     }
153 
154     /**
155      * Controls whether the device may terminate listening on a Discovery Window (DW) earlier than
156      * the DW termination (16ms) if no information is received. Enabling the feature will result in
157      * lower power consumption, but may result in some missed messages and hence increased latency.
158      *
159      * @param enable true to enable, false otherwise
160      */
setDwEarlyTerminationEnabled(boolean enable)161     public void setDwEarlyTerminationEnabled(boolean enable) {
162         mIsDwEarlyTerminationEnabled = enable;
163     }
164 
165     /**
166      * Get the discovery window (DW) interval for 2.4Ghz.
167      * @see #setDiscoveryWindowWakeInterval24Ghz(int)
168      * @return an integer represents discovery window interval, {@link #UNSET_PARAMETER} represent
169      * this parameter is not set
170      */
getDiscoveryWindowWakeInterval24Ghz()171     public int getDiscoveryWindowWakeInterval24Ghz() {
172         return mDw24Ghz;
173     }
174 
175     /**
176      * Get the discovery window (DW) interval for 5Ghz.
177      * @see #setDiscoveryWindowWakeInterval5Ghz(int)
178      * @return an integer represents discovery window interval, {@link #UNSET_PARAMETER} represent
179      * this parameter is not set
180      */
getDiscoveryWindowWakeInterval5Ghz()181     public int getDiscoveryWindowWakeInterval5Ghz() {
182         return mDw5Ghz;
183     }
184 
185     /**
186      * Get the discovery window (DW) interval for 6ghz.
187      * @see #setDiscoveryWindowWakeInterval5Ghz(int)
188      * @return an integer represents discovery window interval, {@link #UNSET_PARAMETER} represent
189      * this parameter is not
190      * set
191      * @hide
192      */
getDiscoveryWindowWakeInterval6Ghz()193     public int getDiscoveryWindowWakeInterval6Ghz() {
194         return mDw24Ghz;
195     }
196 
197     /**
198      * Get the discovery beacon interval in milliseconds
199      * @see #setDiscoveryBeaconIntervalMillis(int)
200      * @return an integer represents discovery beacon interval in milliseconds,
201      * {@link #UNSET_PARAMETER} represent this parameter is not set
202      */
getDiscoveryBeaconIntervalMillis()203     public int getDiscoveryBeaconIntervalMillis() {
204         return mDiscoveryBeaconIntervalMs;
205     }
206 
207     /**
208      * Get the number of the spatial streams used in discovery
209      * @see #setNumSpatialStreamsInDiscovery(int)
210      * @return an integer represents number of the spatial streams, {@link #UNSET_PARAMETER}
211      * represent this parameter is not set
212      */
getNumSpatialStreamsInDiscovery()213     public int getNumSpatialStreamsInDiscovery() {
214         return mNumSpatialStreamsInDiscovery;
215     }
216 
217     /**
218      * Check if discovery window early termination is enabled.
219      * @see #setDwEarlyTerminationEnabled(boolean)
220      * @return true if enabled, false otherwise.
221      */
isDwEarlyTerminationEnabled()222     public boolean isDwEarlyTerminationEnabled() {
223         return mIsDwEarlyTerminationEnabled;
224     }
225 
226     /**
227      * Get the interval of the MAC address randomization.
228      * @return An integer represents the interval in seconds, {@link #UNSET_PARAMETER} represent
229      * this parameter is not set
230      */
getMacRandomizationIntervalSeconds()231     public int getMacRandomizationIntervalSeconds() {
232         return mMacRandomIntervalSec;
233     }
234 
235 
236     @Override
describeContents()237     public int describeContents() {
238         return 0;
239     }
240 
241     @Override
writeToParcel(@onNull Parcel dest, int flags)242     public void writeToParcel(@NonNull Parcel dest, int flags) {
243         dest.writeInt(mDw24Ghz);
244         dest.writeInt(mDw5Ghz);
245         dest.writeInt(mDw6Ghz);
246         dest.writeInt(mDiscoveryBeaconIntervalMs);
247         dest.writeInt(mNumSpatialStreamsInDiscovery);
248         dest.writeBoolean((mIsDwEarlyTerminationEnabled));
249         dest.writeInt(mMacRandomIntervalSec);
250     }
251 
252     /** @hide */
253     @Override
toString()254     public String toString() {
255         StringBuffer sbf = new StringBuffer();
256         sbf.append("AwareParams [")
257                 .append("mDw24Ghz=").append(mDw24Ghz)
258                 .append(", mDw5Ghz=").append(mDw5Ghz)
259                 .append(", mDw6Ghz=").append(mDw6Ghz)
260                 .append(", mDiscoveryBeaconIntervalMs=").append(mDiscoveryBeaconIntervalMs)
261                 .append(", mNumSpatialStreamsInDiscovery=").append(mNumSpatialStreamsInDiscovery)
262                 .append(", mIsDwEarlyTerminationEnabled=").append(mIsDwEarlyTerminationEnabled)
263                 .append(", mMacRandomIntervalSec=").append(mMacRandomIntervalSec)
264                 .append("]");
265         return sbf.toString();
266     }
267 }
268