1/*
2 * Copyright (C) 2014 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
17package android.net;
18
19import android.annotation.SystemApi;
20import android.os.Parcel;
21import android.os.Parcelable;
22
23import java.util.Objects;
24
25/**
26 * A network identifier along with a score for the quality of that network.
27 *
28 * @hide
29 */
30@SystemApi
31public class ScoredNetwork implements Parcelable {
32
33    /** A {@link NetworkKey} uniquely identifying this network. */
34    public final NetworkKey networkKey;
35
36    /**
37     * The {@link RssiCurve} representing the scores for this network based on the RSSI.
38     *
39     * <p>This field is optional and may be set to null to indicate that no score is available for
40     * this network at this time. Such networks, along with networks for which the scorer has not
41     * responded, are always prioritized below scored networks, regardless of the score.
42     */
43    public final RssiCurve rssiCurve;
44
45    /**
46     * A boolean value that indicates whether or not the network is believed to be metered.
47     *
48     * <p>A network can be classified as metered if the user would be
49     * sensitive to heavy data usage on that connection due to monetary costs,
50     * data limitations or battery/performance issues. A typical example would
51     * be a wifi connection where the user would be charged for usage.
52     */
53    public final boolean meteredHint;
54
55    /**
56     * Construct a new {@link ScoredNetwork}.
57     *
58     * @param networkKey the {@link NetworkKey} uniquely identifying this network.
59     * @param rssiCurve the {@link RssiCurve} representing the scores for this network based on the
60     *     RSSI. This field is optional, and may be skipped to represent a network which the scorer
61     *     has opted not to score at this time. Passing a null value here is strongly preferred to
62     *     not returning any {@link ScoredNetwork} for a given {@link NetworkKey} because it
63     *     indicates to the system not to request scores for this network in the future, although
64     *     the scorer may choose to issue an out-of-band update at any time.
65     */
66    public ScoredNetwork(NetworkKey networkKey, RssiCurve rssiCurve) {
67        this(networkKey, rssiCurve, false /* meteredHint */);
68    }
69
70    /**
71     * Construct a new {@link ScoredNetwork}.
72     *
73     * @param networkKey the {@link NetworkKey} uniquely identifying this network.
74     * @param rssiCurve the {@link RssiCurve} representing the scores for this network based on the
75     *     RSSI. This field is optional, and may be skipped to represent a network which the scorer
76     *     has opted not to score at this time. Passing a null value here is strongly preferred to
77     *     not returning any {@link ScoredNetwork} for a given {@link NetworkKey} because it
78     *     indicates to the system not to request scores for this network in the future, although
79     *     the scorer may choose to issue an out-of-band update at any time.
80     * @param meteredHint A boolean value indicating whether or not the network is believed to be
81     *     metered.
82     */
83    public ScoredNetwork(NetworkKey networkKey, RssiCurve rssiCurve, boolean meteredHint) {
84        this.networkKey = networkKey;
85        this.rssiCurve = rssiCurve;
86        this.meteredHint = meteredHint;
87    }
88
89    private ScoredNetwork(Parcel in) {
90        networkKey = NetworkKey.CREATOR.createFromParcel(in);
91        if (in.readByte() == 1) {
92            rssiCurve = RssiCurve.CREATOR.createFromParcel(in);
93        } else {
94            rssiCurve = null;
95        }
96        meteredHint = in.readByte() != 0;
97    }
98
99    @Override
100    public int describeContents() {
101        return 0;
102    }
103
104    @Override
105    public void writeToParcel(Parcel out, int flags) {
106        networkKey.writeToParcel(out, flags);
107        if (rssiCurve != null) {
108            out.writeByte((byte) 1);
109            rssiCurve.writeToParcel(out, flags);
110        } else {
111            out.writeByte((byte) 0);
112        }
113        out.writeByte((byte) (meteredHint ? 1 : 0));
114    }
115
116    @Override
117    public boolean equals(Object o) {
118        if (this == o) return true;
119        if (o == null || getClass() != o.getClass()) return false;
120
121        ScoredNetwork that = (ScoredNetwork) o;
122
123        return Objects.equals(networkKey, that.networkKey)
124            && Objects.equals(rssiCurve, that.rssiCurve)
125            && Objects.equals(meteredHint, that.meteredHint);
126    }
127
128    @Override
129    public int hashCode() {
130        return Objects.hash(networkKey, rssiCurve, meteredHint);
131    }
132
133    @Override
134    public String toString() {
135        return "ScoredNetwork[key=" + networkKey + ",score=" + rssiCurve
136            + ",meteredHint=" + meteredHint + "]";
137    }
138
139    public static final Parcelable.Creator<ScoredNetwork> CREATOR =
140            new Parcelable.Creator<ScoredNetwork>() {
141                @Override
142                public ScoredNetwork createFromParcel(Parcel in) {
143                    return new ScoredNetwork(in);
144                }
145
146                @Override
147                public ScoredNetwork[] newArray(int size) {
148                    return new ScoredNetwork[size];
149                }
150            };
151}
152