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 
17 package android.location;
18 
19 import android.annotation.TestApi;
20 import android.annotation.IntDef;
21 import android.annotation.NonNull;
22 import android.os.Parcel;
23 import android.os.Parcelable;
24 
25 import java.lang.annotation.Retention;
26 import java.lang.annotation.RetentionPolicy;
27 import java.security.InvalidParameterException;
28 import java.util.Arrays;
29 import java.util.Collection;
30 import java.util.Collections;
31 
32 /**
33  * A class implementing a container for data associated with a measurement event.
34  * Events are delivered to registered instances of {@link Callback}.
35  */
36 public final class GnssMeasurementsEvent implements Parcelable {
37     private final GnssClock mClock;
38     private final Collection<GnssMeasurement> mReadOnlyMeasurements;
39 
40     /**
41      * Used for receiving GNSS satellite measurements from the GNSS engine.
42      * Each measurement contains raw and computed data identifying a satellite.
43      * You can implement this interface and call
44      * {@link LocationManager#registerGnssMeasurementsCallback}.
45      */
46     public static abstract class Callback {
47         /**
48          * The status of the GNSS measurements event.
49          * @hide
50          */
51         @Retention(RetentionPolicy.SOURCE)
52         @IntDef({STATUS_NOT_SUPPORTED, STATUS_READY, STATUS_LOCATION_DISABLED, STATUS_NOT_ALLOWED})
53         public @interface GnssMeasurementsStatus {}
54 
55         /**
56          * The system does not support tracking of GNSS Measurements.
57          *
58          * <p>This status will not change in the future.
59          */
60         public static final int STATUS_NOT_SUPPORTED = 0;
61 
62         /**
63          * GNSS Measurements are successfully being tracked, it will receive updates once they are
64          * available.
65          */
66         public static final int STATUS_READY = 1;
67 
68         /**
69          * GPS provider or Location is disabled, updates will not be received until they are
70          * enabled.
71          */
72         public static final int STATUS_LOCATION_DISABLED = 2;
73 
74         /**
75          * The client is not allowed to register for GNSS Measurements in general or in the
76          * requested mode.
77          *
78          * <p>Such a status is returned when a client tries to request a functionality from the GNSS
79          * chipset while another client has an ongoing request that does not allow such
80          * functionality to be performed.
81          *
82          * <p>If such a status is received, one would try again at a later time point where no
83          * other client is having a conflicting request.
84          */
85         public static final int STATUS_NOT_ALLOWED = 3;
86 
87         /**
88          * Reports the latest collected GNSS Measurements.
89          */
onGnssMeasurementsReceived(GnssMeasurementsEvent eventArgs)90         public void onGnssMeasurementsReceived(GnssMeasurementsEvent eventArgs) {}
91 
92         /**
93          * Reports the latest status of the GNSS Measurements sub-system.
94          */
onStatusChanged(@nssMeasurementsStatus int status)95         public void onStatusChanged(@GnssMeasurementsStatus int status) {}
96     }
97 
98     /**
99      * @hide
100      */
101     @TestApi
GnssMeasurementsEvent(GnssClock clock, GnssMeasurement[] measurements)102     public GnssMeasurementsEvent(GnssClock clock, GnssMeasurement[] measurements) {
103         if (clock == null) {
104             throw new InvalidParameterException("Parameter 'clock' must not be null.");
105         }
106         if (measurements == null || measurements.length == 0) {
107             mReadOnlyMeasurements = Collections.emptyList();
108         } else {
109             Collection<GnssMeasurement> measurementCollection = Arrays.asList(measurements);
110             mReadOnlyMeasurements = Collections.unmodifiableCollection(measurementCollection);
111         }
112 
113         mClock = clock;
114     }
115 
116     /**
117      * Gets the GNSS receiver clock information associated with the measurements for the current
118      * event.
119      */
120     @NonNull
getClock()121     public GnssClock getClock() {
122         return mClock;
123     }
124 
125     /**
126      * Gets a read-only collection of measurements associated with the current event.
127      */
128     @NonNull
getMeasurements()129     public Collection<GnssMeasurement> getMeasurements() {
130         return mReadOnlyMeasurements;
131     }
132 
133     public static final @android.annotation.NonNull Creator<GnssMeasurementsEvent> CREATOR =
134             new Creator<GnssMeasurementsEvent>() {
135         @Override
136         public GnssMeasurementsEvent createFromParcel(Parcel in) {
137             ClassLoader classLoader = getClass().getClassLoader();
138 
139             GnssClock clock = in.readParcelable(classLoader);
140 
141             int measurementsLength = in.readInt();
142             GnssMeasurement[] measurementsArray = new GnssMeasurement[measurementsLength];
143             in.readTypedArray(measurementsArray, GnssMeasurement.CREATOR);
144 
145             return new GnssMeasurementsEvent(clock, measurementsArray);
146         }
147 
148         @Override
149         public GnssMeasurementsEvent[] newArray(int size) {
150             return new GnssMeasurementsEvent[size];
151         }
152     };
153 
154     @Override
describeContents()155     public int describeContents() {
156         return 0;
157     }
158 
159     @Override
writeToParcel(Parcel parcel, int flags)160     public void writeToParcel(Parcel parcel, int flags) {
161         parcel.writeParcelable(mClock, flags);
162 
163         int measurementsCount = mReadOnlyMeasurements.size();
164         GnssMeasurement[] measurementsArray =
165                 mReadOnlyMeasurements.toArray(new GnssMeasurement[measurementsCount]);
166         parcel.writeInt(measurementsArray.length);
167         parcel.writeTypedArray(measurementsArray, flags);
168     }
169 
170     @Override
toString()171     public String toString() {
172         StringBuilder builder = new StringBuilder("[ GnssMeasurementsEvent:\n\n");
173 
174         builder.append(mClock.toString());
175         builder.append("\n");
176 
177         for (GnssMeasurement measurement : mReadOnlyMeasurements) {
178             builder.append(measurement.toString());
179             builder.append("\n");
180         }
181 
182         builder.append("]");
183 
184         return builder.toString();
185     }
186 }
187