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