GpsStatus.java revision b16e7800be4f879135f239f1f8f586f3712df01e
1/* 2 * Copyright (C) 2008 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 java.util.Iterator; 20import java.util.NoSuchElementException; 21 22 23/** 24 * This class represents the current state of the GPS engine. 25 * This class is used in conjunction with the {@link Listener} interface. 26 */ 27public final class GpsStatus { 28 private static final int NUM_SATELLITES = 255; 29 30 /* These package private values are modified by the LocationManager class */ 31 private int mTimeToFirstFix; 32 private GpsSatellite mSatellites[] = new GpsSatellite[NUM_SATELLITES]; 33 34 private final class SatelliteIterator implements Iterator<GpsSatellite> { 35 36 private GpsSatellite[] mSatellites; 37 int mIndex = 0; 38 39 SatelliteIterator(GpsSatellite[] satellites) { 40 mSatellites = satellites; 41 } 42 43 public boolean hasNext() { 44 for (int i = mIndex; i < mSatellites.length; i++) { 45 if (mSatellites[i].mValid) { 46 return true; 47 } 48 } 49 return false; 50 } 51 52 public GpsSatellite next() { 53 while (mIndex < mSatellites.length) { 54 GpsSatellite satellite = mSatellites[mIndex++]; 55 if (satellite.mValid) { 56 return satellite; 57 } 58 } 59 throw new NoSuchElementException(); 60 } 61 62 public void remove() { 63 throw new UnsupportedOperationException(); 64 } 65 } 66 67 private Iterable<GpsSatellite> mSatelliteList = new Iterable<GpsSatellite>() { 68 public Iterator<GpsSatellite> iterator() { 69 return new SatelliteIterator(mSatellites); 70 } 71 }; 72 73 /** 74 * Event sent when the GPS system has started. 75 */ 76 public static final int GPS_EVENT_STARTED = 1; 77 78 /** 79 * Event sent when the GPS system has stopped. 80 */ 81 public static final int GPS_EVENT_STOPPED = 2; 82 83 /** 84 * Event sent when the GPS system has received its first fix since starting. 85 * Call {@link #getTimeToFirstFix()} to find the time from start to first fix. 86 */ 87 public static final int GPS_EVENT_FIRST_FIX = 3; 88 89 /** 90 * Event sent periodically to report GPS satellite status. 91 * Call {@link #getSatellites()} to retrieve the status for each satellite. 92 */ 93 public static final int GPS_EVENT_SATELLITE_STATUS = 4; 94 95 /** 96 * Used for receiving notifications when GPS status has changed. 97 */ 98 public interface Listener { 99 /** 100 * Called to report changes in the GPS status. 101 * The event number is one of: 102 * <ul> 103 * <li> {@link GpsStatus#GPS_EVENT_STARTED} 104 * <li> {@link GpsStatus#GPS_EVENT_STOPPED} 105 * <li> {@link GpsStatus#GPS_EVENT_FIRST_FIX} 106 * <li> {@link GpsStatus#GPS_EVENT_SATELLITE_STATUS} 107 * </ul> 108 * 109 * When this method is called, the client should call 110 * {@link LocationManager#getGpsStatus} to get additional 111 * status information. 112 * 113 * @param event event number for this notification 114 */ 115 void onGpsStatusChanged(int event); 116 } 117 118 /** 119 * Used for receiving NMEA data from the GPS. 120 * 121 * {@hide} 122 */ 123 public interface NmeaListener { 124 void onNmeaReceived(long timestamp, String nmea); 125 } 126 127 GpsStatus() { 128 for (int i = 0; i < mSatellites.length; i++) { 129 mSatellites[i] = new GpsSatellite(i + 1); 130 } 131 } 132 133 /** 134 * Used internally within {@link LocationManager} to copy GPS status 135 * data from the Location Manager Service to its cached GpsStatus instance. 136 * Is synchronized to ensure that GPS status updates are atomic. 137 */ 138 synchronized void setStatus(int svCount, int[] prns, float[] snrs, 139 float[] elevations, float[] azimuths, int ephemerisMask, 140 int almanacMask, int usedInFixMask) { 141 int i; 142 143 for (i = 0; i < mSatellites.length; i++) { 144 mSatellites[i].mValid = false; 145 } 146 147 for (i = 0; i < svCount; i++) { 148 int prn = prns[i] - 1; 149 int prnShift = (1 << prn); 150 GpsSatellite satellite = mSatellites[prn]; 151 152 satellite.mValid = true; 153 satellite.mSnr = snrs[i]; 154 satellite.mElevation = elevations[i]; 155 satellite.mAzimuth = azimuths[i]; 156 satellite.mHasEphemeris = ((ephemerisMask & prnShift) != 0); 157 satellite.mHasAlmanac = ((almanacMask & prnShift) != 0); 158 satellite.mUsedInFix = ((usedInFixMask & prnShift) != 0); 159 } 160 } 161 162 /** 163 * Used by {@link LocationManager#getGpsStatus} to copy LocationManager's 164 * cached GpsStatus instance to the client's copy. 165 * Since this method is only used within {@link LocationManager#getGpsStatus}, 166 * it does not need to be synchronized. 167 */ 168 void setStatus(GpsStatus status) { 169 mTimeToFirstFix = status.getTimeToFirstFix(); 170 171 for (int i = 0; i < mSatellites.length; i++) { 172 mSatellites[i].setStatus(status.mSatellites[i]); 173 } 174 } 175 176 void setTimeToFirstFix(int ttff) { 177 mTimeToFirstFix = ttff; 178 } 179 180 /** 181 * Returns the time required to receive the first fix since the most recent 182 * restart of the GPS engine. 183 * 184 * @return time to first fix in milliseconds 185 */ 186 public int getTimeToFirstFix() { 187 return mTimeToFirstFix; 188 } 189 190 /** 191 * Returns an array of {@link GpsSatellite} objects, which represent the 192 * current state of the GPS engine. 193 * 194 * @return the list of satellites 195 */ 196 public Iterable<GpsSatellite> getSatellites() { 197 return mSatelliteList; 198 } 199 200 /** 201 * Returns the maximum number of satellites that can be in the satellite 202 * list that can be returned by {@link #getSatellites()}. 203 * 204 * @return the maximum number of satellites 205 */ 206 public int getMaxSatellites() { 207 return NUM_SATELLITES; 208 } 209} 210