LocationProvider.java revision 9066cfe9886ac131c34d59ed0e2d287b0e3c0087
1/* 2 * Copyright (C) 2007 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 19/** 20 * An abstract superclass for location providers. A location provider 21 * provides periodic reports on the geographical location of the 22 * device. 23 * 24 * <p> Each provider has a set of criteria under which it may be used; 25 * for example, some providers require GPS hardware and visibility to 26 * a number of satellites; others require the use of the cellular 27 * radio, or access to a specific carrier's network, or to the 28 * internet. They may also have different battery consumption 29 * characteristics or monetary costs to the user. The {@link 30 * Criteria} class allows providers to be selected based on 31 * user-specified criteria. 32 */ 33public abstract class LocationProvider { 34 private static final String TAG = "LocationProvider"; 35 // A regular expression matching characters that may not appear 36 // in the name of a LocationProvider. 37 static final String BAD_CHARS_REGEX = "[^a-zA-Z0-9]"; 38 39 private String mName; 40 41 public static final int OUT_OF_SERVICE = 0; 42 public static final int TEMPORARILY_UNAVAILABLE = 1; 43 public static final int AVAILABLE = 2; 44 45 /** 46 * Constructs a LocationProvider with the given name. Provider names must 47 * consist only of the characters [a-zA-Z0-9]. 48 * 49 * @throws IllegalArgumentException if name contains an illegal character 50 */ 51 LocationProvider(String name) { 52 if (name.matches(BAD_CHARS_REGEX)) { 53 throw new IllegalArgumentException("name " + name + 54 " contains an illegal character"); 55 } 56 // Log.d(TAG, "Constructor: name = " + name); 57 mName = name; 58 } 59 60 /** 61 * Returns the name of this provider. 62 */ 63 public String getName() { 64 return mName; 65 } 66 67 /** 68 * Returns true if this provider meets the given criteria, 69 * false otherwise. 70 */ 71 public boolean meetsCriteria(Criteria criteria) { 72 if ((criteria.getAccuracy() != Criteria.NO_REQUIREMENT) && 73 (criteria.getAccuracy() < getAccuracy())) { 74 return false; 75 } 76 int criteriaPower = criteria.getPowerRequirement(); 77 if ((criteriaPower != Criteria.NO_REQUIREMENT) && 78 (criteriaPower < getPowerRequirement())) { 79 return false; 80 } 81 if (criteria.isAltitudeRequired() && !supportsAltitude()) { 82 return false; 83 } 84 if (criteria.isSpeedRequired() && !supportsSpeed()) { 85 return false; 86 } 87 if (criteria.isBearingRequired() && !supportsBearing()) { 88 return false; 89 } 90 return true; 91 } 92 93 /** 94 * Returns true if the provider requires access to a 95 * data network (e.g., the Internet), false otherwise. 96 */ 97 public abstract boolean requiresNetwork(); 98 99 /** 100 * Returns true if the provider requires access to a 101 * satellite-based positioning system (e.g., GPS), false 102 * otherwise. 103 */ 104 public abstract boolean requiresSatellite(); 105 106 /** 107 * Returns true if the provider requires access to an appropriate 108 * cellular network (e.g., to make use of cell tower IDs), false 109 * otherwise. 110 */ 111 public abstract boolean requiresCell(); 112 113 /** 114 * Returns true if the use of this provider may result in a 115 * monetary charge to the user, false if use is free. It is up to 116 * each provider to give accurate information. 117 */ 118 public abstract boolean hasMonetaryCost(); 119 120 /** 121 * Returns true if the provider is able to provide altitude 122 * information, false otherwise. A provider that reports altitude 123 * under most circumstances but may occassionally not report it 124 * should return true. 125 */ 126 public abstract boolean supportsAltitude(); 127 128 /** 129 * Returns true if the provider is able to provide speed 130 * information, false otherwise. A provider that reports speed 131 * under most circumstances but may occassionally not report it 132 * should return true. 133 */ 134 public abstract boolean supportsSpeed(); 135 136 /** 137 * Returns true if the provider is able to provide bearing 138 * information, false otherwise. A provider that reports bearing 139 * under most circumstances but may occassionally not report it 140 * should return true. 141 */ 142 public abstract boolean supportsBearing(); 143 144 /** 145 * Returns the power requirement for this provider. 146 * 147 * @return the power requirement for this provider, as one of the 148 * constants Criteria.POWER_REQUIREMENT_*. 149 */ 150 public abstract int getPowerRequirement(); 151 152 /** 153 * Returns a constant describing horizontal accuracy of this provider. 154 * If the provider returns finer grain or exact location, 155 * {@link Criteria#ACCURACY_FINE} is returned, otherwise if the 156 * location is only approximate then {@link Criteria#ACCURACY_COARSE} 157 * is returned. 158 */ 159 public abstract int getAccuracy(); 160} 161