1 /*
2  * Copyright (C) 2020 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.location;
18 
19 import android.annotation.NonNull;
20 import android.annotation.SystemApi;
21 import android.os.Parcel;
22 import android.os.Parcelable;
23 
24 /**
25  * This class contains extra parameters to pass to a GNSS provider implementation.
26  * @hide
27  */
28 @SystemApi
29 public final class GnssRequest implements Parcelable {
30     private final boolean mFullTracking;
31 
32     /**
33      * Creates a {@link GnssRequest} with a full list of parameters.
34      */
GnssRequest(boolean fullTracking)35     private GnssRequest(boolean fullTracking) {
36         mFullTracking = fullTracking;
37     }
38 
39     /**
40      * Represents whether to enable full GNSS tracking.
41      *
42      * <p>If true, GNSS chipset switches off duty cycling. In such a mode, no clock
43      * discontinuities are expected, and when supported, carrier phase should be continuous in
44      * good signal conditions. All non-denylisted, healthy constellations, satellites and
45      * frequency bands that the chipset supports must be reported in this mode. The GNSS chipset
46      * is allowed to consume more power in this mode. If false, GNSS chipset optimizes power via
47      * duty cycling, constellations and frequency limits, etc.
48      *
49      * <p>Full GNSS tracking mode affects GnssMeasurement and other GNSS functionalities
50      * including GNSS location.
51      */
isFullTracking()52     public boolean isFullTracking() {
53         return mFullTracking;
54     }
55 
56     /**
57      * Converts the {@link GnssRequest} into a {@link GnssMeasurementRequest}.
58      * @hide
59      */
60     @NonNull
toGnssMeasurementRequest()61     public GnssMeasurementRequest toGnssMeasurementRequest() {
62         return new GnssMeasurementRequest.Builder().setFullTracking(isFullTracking()).build();
63     }
64 
65     @NonNull
66     public static final Creator<GnssRequest> CREATOR =
67             new Creator<GnssRequest>() {
68                 @Override
69                 @NonNull
70                 public GnssRequest createFromParcel(@NonNull Parcel parcel) {
71                     return new GnssRequest(parcel.readBoolean());
72                 }
73 
74                 @Override
75                 public GnssRequest[] newArray(int i) {
76                     return new GnssRequest[i];
77                 }
78             };
79 
80     @NonNull
81     @Override
toString()82     public String toString() {
83         StringBuilder s = new StringBuilder();
84         s.append("GnssRequest[");
85         if (mFullTracking) {
86             s.append("FullTracking");
87         }
88         s.append(']');
89         return s.toString();
90     }
91 
92     @Override
equals(Object obj)93     public boolean equals(Object obj) {
94         if (this == obj) return true;
95         if (obj == null) return false;
96         if (!(obj instanceof GnssRequest)) return false;
97 
98         GnssRequest other = (GnssRequest) obj;
99         if (mFullTracking != other.mFullTracking) return false;
100 
101         return true;
102     }
103 
104     @Override
hashCode()105     public int hashCode() {
106         return mFullTracking ? 1 : 0;
107     }
108 
109     @Override
describeContents()110     public int describeContents() {
111         return 0;
112     }
113 
114     @Override
writeToParcel(@onNull Parcel parcel, int flags)115     public void writeToParcel(@NonNull Parcel parcel, int flags) {
116         parcel.writeBoolean(mFullTracking);
117     }
118 
119     /** Builder for {@link GnssRequest} */
120     public static final class Builder {
121         private boolean mFullTracking;
122 
123         /**
124          * Constructs a {@link Builder} instance.
125          */
Builder()126         public Builder() {
127         }
128 
129         /**
130          * Constructs a {@link Builder} instance by copying a {@link GnssRequest}.
131          */
Builder(@onNull GnssRequest request)132         public Builder(@NonNull GnssRequest request) {
133             mFullTracking = request.isFullTracking();
134         }
135 
136         /**
137          * Set the value of whether to enable full GNSS tracking, which is false by default.
138          *
139          * <p>If true, GNSS chipset switches off duty cycling. In such a mode, no clock
140          * discontinuities are expected, and when supported, carrier phase should be continuous in
141          * good signal conditions. All non-denylisted, healthy constellations, satellites and
142          * frequency bands that the chipset supports must be reported in this mode. The GNSS chipset
143          * is allowed to consume more power in this mode. If false, GNSS chipset optimizes power via
144          * duty cycling, constellations and frequency limits, etc.
145          *
146          * <p>Full GNSS tracking mode affects GnssMeasurement and other GNSS functionalities
147          * including GNSS location.
148          *
149          * <p>Full tracking requests always override non-full tracking requests. If any full
150          * tracking request occurs, all listeners on the device will receive full tracking GNSS
151          * measurements.
152          */
setFullTracking(boolean value)153         @NonNull public Builder setFullTracking(boolean value) {
154             mFullTracking = value;
155             return this;
156         }
157 
158         /** Builds a {@link GnssRequest} instance as specified by this builder. */
159         @NonNull
build()160         public GnssRequest build() {
161             return new GnssRequest(mFullTracking);
162         }
163     }
164 }
165