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