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