/*
|
* Copyright (C) 2014 The Android Open Source Project
|
*
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
* you may not use this file except in compliance with the License.
|
* You may obtain a copy of the License at
|
*
|
* http://www.apache.org/licenses/LICENSE-2.0
|
*
|
* Unless required by applicable law or agreed to in writing, software
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
* See the License for the specific language governing permissions and
|
* limitations under the License
|
*/
|
|
package android.net;
|
|
import android.annotation.Nullable;
|
import android.annotation.SystemApi;
|
import android.os.Bundle;
|
import android.os.Parcel;
|
import android.os.Parcelable;
|
|
import java.util.Objects;
|
import java.util.Set;
|
|
/**
|
* A network identifier along with a score for the quality of that network.
|
*
|
* @hide
|
*/
|
@SystemApi
|
public class ScoredNetwork implements Parcelable {
|
|
/**
|
* Key used with the {@link #attributes} bundle to define the badging curve.
|
*
|
* <p>The badging curve is a {@link RssiCurve} used to map different RSSI values to {@link
|
* NetworkBadging.Badging} enums.
|
*/
|
public static final String ATTRIBUTES_KEY_BADGING_CURVE =
|
"android.net.attributes.key.BADGING_CURVE";
|
/**
|
* Extra used with {@link #attributes} to specify whether the
|
* network is believed to have a captive portal.
|
* <p>
|
* This data may be used, for example, to display a visual indicator
|
* in a network selection list.
|
* <p>
|
* Note that the this extra conveys the possible presence of a
|
* captive portal, not its state or the user's ability to open
|
* the portal.
|
* <p>
|
* If no value is associated with this key then it's unknown.
|
*/
|
public static final String ATTRIBUTES_KEY_HAS_CAPTIVE_PORTAL =
|
"android.net.attributes.key.HAS_CAPTIVE_PORTAL";
|
|
/**
|
* Key used with the {@link #attributes} bundle to define the rankingScoreOffset int value.
|
*
|
* <p>The rankingScoreOffset is used when calculating the ranking score used to rank networks
|
* against one another. See {@link #calculateRankingScore} for more information.
|
*/
|
public static final String ATTRIBUTES_KEY_RANKING_SCORE_OFFSET =
|
"android.net.attributes.key.RANKING_SCORE_OFFSET";
|
|
/** A {@link NetworkKey} uniquely identifying this network. */
|
public final NetworkKey networkKey;
|
|
/**
|
* The {@link RssiCurve} representing the scores for this network based on the RSSI.
|
*
|
* <p>This field is optional and may be set to null to indicate that no score is available for
|
* this network at this time. Such networks, along with networks for which the scorer has not
|
* responded, are always prioritized below scored networks, regardless of the score.
|
*/
|
public final RssiCurve rssiCurve;
|
|
/**
|
* A boolean value that indicates whether or not the network is believed to be metered.
|
*
|
* <p>A network can be classified as metered if the user would be
|
* sensitive to heavy data usage on that connection due to monetary costs,
|
* data limitations or battery/performance issues. A typical example would
|
* be a wifi connection where the user would be charged for usage.
|
*/
|
public final boolean meteredHint;
|
|
/**
|
* An additional collection of optional attributes set by
|
* the Network Recommendation Provider.
|
*
|
* @see #ATTRIBUTES_KEY_HAS_CAPTIVE_PORTAL
|
* @see #ATTRIBUTES_KEY_RANKING_SCORE_OFFSET
|
*/
|
@Nullable
|
public final Bundle attributes;
|
|
/**
|
* Construct a new {@link ScoredNetwork}.
|
*
|
* @param networkKey the {@link NetworkKey} uniquely identifying this network.
|
* @param rssiCurve the {@link RssiCurve} representing the scores for this network based on the
|
* RSSI. This field is optional, and may be skipped to represent a network which the scorer
|
* has opted not to score at this time. Passing a null value here is strongly preferred to
|
* not returning any {@link ScoredNetwork} for a given {@link NetworkKey} because it
|
* indicates to the system not to request scores for this network in the future, although
|
* the scorer may choose to issue an out-of-band update at any time.
|
*/
|
public ScoredNetwork(NetworkKey networkKey, RssiCurve rssiCurve) {
|
this(networkKey, rssiCurve, false /* meteredHint */);
|
}
|
|
/**
|
* Construct a new {@link ScoredNetwork}.
|
*
|
* @param networkKey the {@link NetworkKey} uniquely identifying this network.
|
* @param rssiCurve the {@link RssiCurve} representing the scores for this network based on the
|
* RSSI. This field is optional, and may be skipped to represent a network which the scorer
|
* has opted not to score at this time. Passing a null value here is strongly preferred to
|
* not returning any {@link ScoredNetwork} for a given {@link NetworkKey} because it
|
* indicates to the system not to request scores for this network in the future, although
|
* the scorer may choose to issue an out-of-band update at any time.
|
* @param meteredHint A boolean value indicating whether or not the network is believed to be
|
* metered.
|
*/
|
public ScoredNetwork(NetworkKey networkKey, RssiCurve rssiCurve, boolean meteredHint) {
|
this(networkKey, rssiCurve, meteredHint, null /* attributes */);
|
}
|
|
/**
|
* Construct a new {@link ScoredNetwork}.
|
*
|
* @param networkKey the {@link NetworkKey} uniquely identifying this network
|
* @param rssiCurve the {@link RssiCurve} representing the scores for this network based on the
|
* RSSI. This field is optional, and may be skipped to represent a network which the scorer
|
* has opted not to score at this time. Passing a null value here is strongly preferred to
|
* not returning any {@link ScoredNetwork} for a given {@link NetworkKey} because it
|
* indicates to the system not to request scores for this network in the future, although
|
* the scorer may choose to issue an out-of-band update at any time.
|
* @param meteredHint a boolean value indicating whether or not the network is believed to be
|
* metered
|
* @param attributes optional provider specific attributes
|
*/
|
public ScoredNetwork(NetworkKey networkKey, RssiCurve rssiCurve, boolean meteredHint,
|
@Nullable Bundle attributes) {
|
this.networkKey = networkKey;
|
this.rssiCurve = rssiCurve;
|
this.meteredHint = meteredHint;
|
this.attributes = attributes;
|
}
|
|
private ScoredNetwork(Parcel in) {
|
networkKey = NetworkKey.CREATOR.createFromParcel(in);
|
if (in.readByte() == 1) {
|
rssiCurve = RssiCurve.CREATOR.createFromParcel(in);
|
} else {
|
rssiCurve = null;
|
}
|
meteredHint = (in.readByte() == 1);
|
attributes = in.readBundle();
|
}
|
|
@Override
|
public int describeContents() {
|
return 0;
|
}
|
|
@Override
|
public void writeToParcel(Parcel out, int flags) {
|
networkKey.writeToParcel(out, flags);
|
if (rssiCurve != null) {
|
out.writeByte((byte) 1);
|
rssiCurve.writeToParcel(out, flags);
|
} else {
|
out.writeByte((byte) 0);
|
}
|
out.writeByte((byte) (meteredHint ? 1 : 0));
|
out.writeBundle(attributes);
|
}
|
|
@Override
|
public boolean equals(Object o) {
|
if (this == o) return true;
|
if (o == null || getClass() != o.getClass()) return false;
|
|
ScoredNetwork that = (ScoredNetwork) o;
|
|
return Objects.equals(networkKey, that.networkKey)
|
&& Objects.equals(rssiCurve, that.rssiCurve)
|
&& Objects.equals(meteredHint, that.meteredHint)
|
&& bundleEquals(attributes, that.attributes);
|
}
|
|
private boolean bundleEquals(Bundle bundle1, Bundle bundle2) {
|
if (bundle1 == bundle2) {
|
return true;
|
}
|
if (bundle1 == null || bundle2 == null) {
|
return false;
|
}
|
if (bundle1.size() != bundle2.size()) {
|
return false;
|
}
|
Set<String> keys = bundle1.keySet();
|
for (String key : keys) {
|
Object value1 = bundle1.get(key);
|
Object value2 = bundle2.get(key);
|
if (!Objects.equals(value1, value2)) {
|
return false;
|
}
|
}
|
return true;
|
}
|
|
@Override
|
public int hashCode() {
|
return Objects.hash(networkKey, rssiCurve, meteredHint, attributes);
|
}
|
|
@Override
|
public String toString() {
|
StringBuilder out = new StringBuilder(
|
"ScoredNetwork{" +
|
"networkKey=" + networkKey +
|
", rssiCurve=" + rssiCurve +
|
", meteredHint=" + meteredHint);
|
// calling isEmpty will unparcel the bundle so its contents can be converted to a string
|
if (attributes != null && !attributes.isEmpty()) {
|
out.append(", attributes=" + attributes);
|
}
|
out.append('}');
|
return out.toString();
|
}
|
|
/**
|
* Returns true if a ranking score can be calculated for this network.
|
*
|
* @hide
|
*/
|
public boolean hasRankingScore() {
|
return (rssiCurve != null)
|
|| (attributes != null
|
&& attributes.containsKey(ATTRIBUTES_KEY_RANKING_SCORE_OFFSET));
|
}
|
|
/**
|
* Returns a ranking score for a given RSSI which can be used to comparatively
|
* rank networks.
|
*
|
* <p>The score obtained by the rssiCurve is bitshifted left by 8 bits to expand it to an
|
* integer and then the offset is added. If the addition operation overflows or underflows,
|
* Integer.MAX_VALUE and Integer.MIN_VALUE will be returned respectively.
|
*
|
* <p>{@link #hasRankingScore} should be called first to ensure this network is capable
|
* of returning a ranking score.
|
*
|
* @throws UnsupportedOperationException if there is no RssiCurve and no rankingScoreOffset
|
* for this network (hasRankingScore returns false).
|
*
|
* @hide
|
*/
|
public int calculateRankingScore(int rssi) throws UnsupportedOperationException {
|
if (!hasRankingScore()) {
|
throw new UnsupportedOperationException(
|
"Either rssiCurve or rankingScoreOffset is required to calculate the "
|
+ "ranking score");
|
}
|
|
int offset = 0;
|
if (attributes != null) {
|
offset += attributes.getInt(ATTRIBUTES_KEY_RANKING_SCORE_OFFSET, 0 /* default */);
|
}
|
|
int score = (rssiCurve == null) ? 0 : rssiCurve.lookupScore(rssi) << Byte.SIZE;
|
|
try {
|
return Math.addExact(score, offset);
|
} catch (ArithmeticException e) {
|
return (score < 0) ? Integer.MIN_VALUE : Integer.MAX_VALUE;
|
}
|
}
|
|
/**
|
* Return the {@link NetworkBadging.Badging} enum for this network for the given RSSI, derived from the
|
* badging curve.
|
*
|
* <p>If no badging curve is present, {@link #BADGE_NONE} will be returned.
|
*
|
* @param rssi The rssi level for which the badge should be calculated
|
*/
|
@NetworkBadging.Badging
|
public int calculateBadge(int rssi) {
|
if (attributes != null && attributes.containsKey(ATTRIBUTES_KEY_BADGING_CURVE)) {
|
RssiCurve badgingCurve =
|
attributes.getParcelable(ATTRIBUTES_KEY_BADGING_CURVE);
|
return badgingCurve.lookupScore(rssi);
|
}
|
|
return NetworkBadging.BADGING_NONE;
|
}
|
|
public static final @android.annotation.NonNull Parcelable.Creator<ScoredNetwork> CREATOR =
|
new Parcelable.Creator<ScoredNetwork>() {
|
@Override
|
public ScoredNetwork createFromParcel(Parcel in) {
|
return new ScoredNetwork(in);
|
}
|
|
@Override
|
public ScoredNetwork[] newArray(int size) {
|
return new ScoredNetwork[size];
|
}
|
};
|
}
|
