1 /*
2  * Copyright (C) 2013 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;
18 
19 import android.compat.annotation.UnsupportedAppUsage;
20 import android.os.Parcel;
21 import android.os.Parcelable;
22 
23 /**
24  *  Class that represents useful attributes of generic network links
25  *  such as the upload/download throughput or packet error rate.
26  *  Generally speaking, you should be dealing with instances of
27  *  LinkQualityInfo subclasses, such as {@link android.net.WifiLinkQualityInfo}
28  *  or {@link android.net.MobileLinkQualityInfo} which provide additional
29  *  information.
30  *  @hide
31  */
32 public class LinkQualityInfo implements Parcelable {
33 
34     /**
35      * Represents a value that you can use to test if an integer field is set to a good value
36      */
37     public static final int UNKNOWN_INT = Integer.MAX_VALUE;
38 
39     /**
40      * Represents a value that you can use to test if a long field is set to a good value
41      */
42     public static final long UNKNOWN_LONG = Long.MAX_VALUE;
43 
44     public static final int NORMALIZED_MIN_SIGNAL_STRENGTH = 0;
45 
46     public static final int NORMALIZED_MAX_SIGNAL_STRENGTH = 99;
47 
48     public static final int NORMALIZED_SIGNAL_STRENGTH_RANGE =
49             NORMALIZED_MAX_SIGNAL_STRENGTH - NORMALIZED_MIN_SIGNAL_STRENGTH + 1;
50 
51     /* Network type as defined by ConnectivityManager */
52     private int mNetworkType = ConnectivityManager.TYPE_NONE;
53 
54     private int mNormalizedSignalStrength = UNKNOWN_INT;
55 
56     private long mPacketCount = UNKNOWN_LONG;
57     private long mPacketErrorCount = UNKNOWN_LONG;
58     private int mTheoreticalTxBandwidth = UNKNOWN_INT;
59     private int mTheoreticalRxBandwidth = UNKNOWN_INT;
60     private int mTheoreticalLatency = UNKNOWN_INT;
61 
62     /* Timestamp when last sample was made available */
63     private long mLastDataSampleTime = UNKNOWN_LONG;
64 
65     /* Sample duration in millisecond */
66     private int mDataSampleDuration = UNKNOWN_INT;
67 
LinkQualityInfo()68     public LinkQualityInfo() {
69 
70     }
71 
72     /**
73      * Implement the Parcelable interface
74      * @hide
75      */
describeContents()76     public int describeContents() {
77         return 0;
78     }
79 
80     /**
81      * Implement the Parcelable interface.
82      */
83 
84     protected static final int OBJECT_TYPE_LINK_QUALITY_INFO = 1;
85     protected static final int OBJECT_TYPE_WIFI_LINK_QUALITY_INFO = 2;
86     protected static final int OBJECT_TYPE_MOBILE_LINK_QUALITY_INFO = 3;
87 
88     /**
89      * @hide
90      */
writeToParcel(Parcel dest, int flags)91     public void writeToParcel(Parcel dest, int flags) {
92         writeToParcel(dest, flags, OBJECT_TYPE_LINK_QUALITY_INFO);
93     }
94 
95     /**
96      * @hide
97      */
writeToParcel(Parcel dest, int flags, int objectType)98     public void writeToParcel(Parcel dest, int flags, int objectType) {
99         dest.writeInt(objectType);
100         dest.writeInt(mNetworkType);
101         dest.writeInt(mNormalizedSignalStrength);
102         dest.writeLong(mPacketCount);
103         dest.writeLong(mPacketErrorCount);
104         dest.writeInt(mTheoreticalTxBandwidth);
105         dest.writeInt(mTheoreticalRxBandwidth);
106         dest.writeInt(mTheoreticalLatency);
107         dest.writeLong(mLastDataSampleTime);
108         dest.writeInt(mDataSampleDuration);
109     }
110 
111     /**
112      * @hide
113      */
114     public static final @android.annotation.NonNull Creator<LinkQualityInfo> CREATOR =
115             new Creator<LinkQualityInfo>() {
116                 public LinkQualityInfo createFromParcel(Parcel in) {
117                     int objectType = in.readInt();
118                     if (objectType == OBJECT_TYPE_LINK_QUALITY_INFO) {
119                         LinkQualityInfo li = new LinkQualityInfo();
120                         li.initializeFromParcel(in);
121                         return li;
122                     } else if (objectType == OBJECT_TYPE_WIFI_LINK_QUALITY_INFO) {
123                         return WifiLinkQualityInfo.createFromParcelBody(in);
124                     } else if (objectType == OBJECT_TYPE_MOBILE_LINK_QUALITY_INFO) {
125                         return MobileLinkQualityInfo.createFromParcelBody(in);
126                     } else {
127                         return null;
128                     }
129                 }
130 
131                 public LinkQualityInfo[] newArray(int size) {
132                     return new LinkQualityInfo[size];
133                 }
134             };
135 
136     /**
137      * @hide
138      */
initializeFromParcel(Parcel in)139     protected void initializeFromParcel(Parcel in) {
140         mNetworkType = in.readInt();
141         mNormalizedSignalStrength = in.readInt();
142         mPacketCount = in.readLong();
143         mPacketErrorCount = in.readLong();
144         mTheoreticalTxBandwidth = in.readInt();
145         mTheoreticalRxBandwidth = in.readInt();
146         mTheoreticalLatency = in.readInt();
147         mLastDataSampleTime = in.readLong();
148         mDataSampleDuration = in.readInt();
149     }
150 
151     /**
152      * returns the type of network this link is connected to
153      * @return network type as defined by {@link android.net.ConnectivityManager} or
154      * {@link android.net.LinkQualityInfo#UNKNOWN_INT}
155      */
getNetworkType()156     public int getNetworkType() {
157         return mNetworkType;
158     }
159 
160     /**
161      * @hide
162      */
setNetworkType(int networkType)163     public void setNetworkType(int networkType) {
164         mNetworkType = networkType;
165     }
166 
167     /**
168      * returns the signal strength normalized across multiple types of networks
169      * @return an integer value from 0 - 99 or {@link android.net.LinkQualityInfo#UNKNOWN_INT}
170      */
getNormalizedSignalStrength()171     public int getNormalizedSignalStrength() {
172         return mNormalizedSignalStrength;
173     }
174 
175     /**
176      * @hide
177      */
setNormalizedSignalStrength(int normalizedSignalStrength)178     public void setNormalizedSignalStrength(int normalizedSignalStrength) {
179         mNormalizedSignalStrength = normalizedSignalStrength;
180     }
181 
182     /**
183      * returns the total number of packets sent or received in sample duration
184      * @return number of packets or {@link android.net.LinkQualityInfo#UNKNOWN_LONG}
185      */
getPacketCount()186     public long getPacketCount() {
187         return mPacketCount;
188     }
189 
190     /**
191      * @hide
192      */
193     @UnsupportedAppUsage
setPacketCount(long packetCount)194     public void setPacketCount(long packetCount) {
195         mPacketCount = packetCount;
196     }
197 
198     /**
199      * returns the total number of packets errors encountered in sample duration
200      * @return number of errors or {@link android.net.LinkQualityInfo#UNKNOWN_LONG}
201      */
getPacketErrorCount()202     public long getPacketErrorCount() {
203         return mPacketErrorCount;
204     }
205 
206     /**
207      * @hide
208      */
209     @UnsupportedAppUsage
setPacketErrorCount(long packetErrorCount)210     public void setPacketErrorCount(long packetErrorCount) {
211         mPacketErrorCount = packetErrorCount;
212     }
213 
214     /**
215      * returns the theoretical upload bandwidth of this network
216      * @return bandwidth in Kbps or {@link android.net.LinkQualityInfo#UNKNOWN_INT}
217      */
getTheoreticalTxBandwidth()218     public int getTheoreticalTxBandwidth() {
219         return mTheoreticalTxBandwidth;
220     }
221 
222     /**
223      * @hide
224      */
setTheoreticalTxBandwidth(int theoreticalTxBandwidth)225     public void setTheoreticalTxBandwidth(int theoreticalTxBandwidth) {
226         mTheoreticalTxBandwidth = theoreticalTxBandwidth;
227     }
228 
229     /**
230      * returns the theoretical download bandwidth of this network
231      * @return bandwidth in Kbps or {@link android.net.LinkQualityInfo#UNKNOWN_INT}
232      */
getTheoreticalRxBandwidth()233     public int getTheoreticalRxBandwidth() {
234         return mTheoreticalRxBandwidth;
235     }
236 
237     /**
238      * @hide
239      */
setTheoreticalRxBandwidth(int theoreticalRxBandwidth)240     public void setTheoreticalRxBandwidth(int theoreticalRxBandwidth) {
241         mTheoreticalRxBandwidth = theoreticalRxBandwidth;
242     }
243 
244     /**
245      * returns the theoretical latency of this network
246      * @return latency in milliseconds or {@link android.net.LinkQualityInfo#UNKNOWN_INT}
247      */
getTheoreticalLatency()248     public int getTheoreticalLatency() {
249         return mTheoreticalLatency;
250     }
251 
252     /**
253      * @hide
254      */
setTheoreticalLatency(int theoreticalLatency)255     public void setTheoreticalLatency(int theoreticalLatency) {
256         mTheoreticalLatency = theoreticalLatency;
257     }
258 
259     /**
260      * returns the time stamp of the last sample
261      * @return milliseconds elapsed since start and sample time or
262      * {@link android.net.LinkQualityInfo#UNKNOWN_LONG}
263      */
getLastDataSampleTime()264     public long getLastDataSampleTime() {
265         return mLastDataSampleTime;
266     }
267 
268     /**
269      * @hide
270      */
271     @UnsupportedAppUsage
setLastDataSampleTime(long lastDataSampleTime)272     public void setLastDataSampleTime(long lastDataSampleTime) {
273         mLastDataSampleTime = lastDataSampleTime;
274     }
275 
276     /**
277      * returns the sample duration used
278      * @return duration in milliseconds or {@link android.net.LinkQualityInfo#UNKNOWN_INT}
279      */
getDataSampleDuration()280     public int getDataSampleDuration() {
281         return mDataSampleDuration;
282     }
283 
284     /**
285      * @hide
286      */
287     @UnsupportedAppUsage
setDataSampleDuration(int dataSampleDuration)288     public void setDataSampleDuration(int dataSampleDuration) {
289         mDataSampleDuration = dataSampleDuration;
290     }
291 }
292