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.NonNull;
20 import android.annotation.SystemApi;
21 import android.os.Parcel;
22 import android.os.Parcelable;
23 
24 import java.security.InvalidParameterException;
25 import java.util.Arrays;
26 import java.util.Collection;
27 import java.util.Collections;
28 
29 /**
30  * A class implementing a container for data associated with a measurement event.
31  * Events are delivered to registered instances of {@link Listener}.
32  *
33  * @deprecated use {@link GnssMeasurementsEvent} instead.
34  *
35  * @hide
36  */
37 @Deprecated
38 @SystemApi
39 public class GpsMeasurementsEvent implements Parcelable {
40 
41     /**
42      * The system does not support tracking of GPS Measurements. This status will not change in the
43      * future.
44      */
45     public static final int STATUS_NOT_SUPPORTED = 0;
46 
47     /**
48      * GPS Measurements are successfully being tracked, it will receive updates once they are
49      * available.
50      */
51     public static final int STATUS_READY = 1;
52 
53     /**
54      * GPS provider or Location is disabled, updates will not be received until they are enabled.
55      */
56     public static final int STATUS_GPS_LOCATION_DISABLED = 2;
57 
58     private final GpsClock mClock;
59     private final Collection<GpsMeasurement> mReadOnlyMeasurements;
60 
61     /**
62      * Used for receiving GPS satellite measurements from the GPS engine.
63      * Each measurement contains raw and computed data identifying a satellite.
64      * You can implement this interface and call {@link LocationManager#addGpsMeasurementListener}.
65      *
66      * @hide
67      */
68     @SystemApi
69     public interface Listener {
70 
71         /**
72          * Returns the latest collected GPS Measurements.
73          */
onGpsMeasurementsReceived(GpsMeasurementsEvent eventArgs)74         void onGpsMeasurementsReceived(GpsMeasurementsEvent eventArgs);
75 
76         /**
77          * Returns the latest status of the GPS Measurements sub-system.
78          */
onStatusChanged(int status)79         void onStatusChanged(int status);
80     }
81 
GpsMeasurementsEvent(GpsClock clock, GpsMeasurement[] measurements)82     public GpsMeasurementsEvent(GpsClock clock, GpsMeasurement[] measurements) {
83         if (clock == null) {
84             throw new InvalidParameterException("Parameter 'clock' must not be null.");
85         }
86         if (measurements == null || measurements.length == 0) {
87             throw new InvalidParameterException(
88                     "Parameter 'measurements' must not be null or empty.");
89         }
90 
91         mClock = clock;
92         Collection<GpsMeasurement> measurementCollection = Arrays.asList(measurements);
93         mReadOnlyMeasurements = Collections.unmodifiableCollection(measurementCollection);
94     }
95 
96     @NonNull
getClock()97     public GpsClock getClock() {
98         return mClock;
99     }
100 
101     /**
102      * Gets a read-only collection of measurements associated with the current event.
103      */
104     @NonNull
getMeasurements()105     public Collection<GpsMeasurement> getMeasurements() {
106         return mReadOnlyMeasurements;
107     }
108 
109     public static final @android.annotation.NonNull Creator<GpsMeasurementsEvent> CREATOR =
110             new Creator<GpsMeasurementsEvent>() {
111         @Override
112         public GpsMeasurementsEvent createFromParcel(Parcel in) {
113             ClassLoader classLoader = getClass().getClassLoader();
114 
115             GpsClock clock = in.readParcelable(classLoader, android.location.GpsClock.class);
116 
117             int measurementsLength = in.readInt();
118             GpsMeasurement[] measurementsArray = new GpsMeasurement[measurementsLength];
119             in.readTypedArray(measurementsArray, GpsMeasurement.CREATOR);
120 
121             return new GpsMeasurementsEvent(clock, measurementsArray);
122         }
123 
124         @Override
125         public GpsMeasurementsEvent[] newArray(int size) {
126             return new GpsMeasurementsEvent[size];
127         }
128     };
129 
130     @Override
describeContents()131     public int describeContents() {
132         return 0;
133     }
134 
135     @Override
writeToParcel(Parcel parcel, int flags)136     public void writeToParcel(Parcel parcel, int flags) {
137         parcel.writeParcelable(mClock, flags);
138 
139         int measurementsCount = mReadOnlyMeasurements.size();
140         GpsMeasurement[] measurementsArray =
141                 mReadOnlyMeasurements.toArray(new GpsMeasurement[measurementsCount]);
142         parcel.writeInt(measurementsArray.length);
143         parcel.writeTypedArray(measurementsArray, flags);
144     }
145 
146     @NonNull
147     @Override
toString()148     public String toString() {
149         StringBuilder builder = new StringBuilder("[ GpsMeasurementsEvent:\n\n");
150 
151         builder.append(mClock.toString());
152         builder.append("\n");
153 
154         for (GpsMeasurement measurement : mReadOnlyMeasurements) {
155             builder.append(measurement.toString());
156             builder.append("\n");
157         }
158 
159         builder.append("]");
160 
161         return builder.toString();
162     }
163 }
164