location/java/android/location/GnssMeasurementsEvent.java

   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     /** @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             throw new InvalidParameterException(
 102                     "Parameter 'measurements' must not be null or empty.");
 103         }
 104
 105         mClock = clock;
 106         Collection<GnssMeasurement> measurementCollection = Arrays.asList(measurements);
 107         mReadOnlyMeasurements = Collections.unmodifiableCollection(measurementCollection);
 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 }