LocationProvider.java revision 79762a3ee34eb8be5549bcb183af844b6f19c266
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 * {@hide} 52 */ 53 public LocationProvider(String name) { 54 if (name.matches(BAD_CHARS_REGEX)) { 55 throw new IllegalArgumentException("name " + name + 56 " contains an illegal character"); 57 } 58 // Log.d(TAG, "Constructor: name = " + name); 59 mName = name; 60 } 61 62 /** 63 * Returns the name of this provider. 64 */ 65 public String getName() { 66 return mName; 67 } 68 69 /** 70 * Returns true if this provider meets the given criteria, 71 * false otherwise. 72 */ 73 public boolean meetsCriteria(Criteria criteria) { 74 if ((criteria.getAccuracy() != Criteria.NO_REQUIREMENT) && 75 (criteria.getAccuracy() < getAccuracy())) { 76 return false; 77 } 78 int criteriaPower = criteria.getPowerRequirement(); 79 if ((criteriaPower != Criteria.NO_REQUIREMENT) && 80 (criteriaPower < getPowerRequirement())) { 81 return false; 82 } 83 if (criteria.isAltitudeRequired() && !supportsAltitude()) { 84 return false; 85 } 86 if (criteria.isSpeedRequired() && !supportsSpeed()) { 87 return false; 88 } 89 if (criteria.isBearingRequired() && !supportsBearing()) { 90 return false; 91 } 92 return true; 93 } 94 95 /** 96 * Returns true if the provider requires access to a 97 * data network (e.g., the Internet), false otherwise. 98 */ 99 public abstract boolean requiresNetwork(); 100 101 /** 102 * Returns true if the provider requires access to a 103 * satellite-based positioning system (e.g., GPS), false 104 * otherwise. 105 */ 106 public abstract boolean requiresSatellite(); 107 108 /** 109 * Returns true if the provider requires access to an appropriate 110 * cellular network (e.g., to make use of cell tower IDs), false 111 * otherwise. 112 */ 113 public abstract boolean requiresCell(); 114 115 /** 116 * Returns true if the use of this provider may result in a 117 * monetary charge to the user, false if use is free. It is up to 118 * each provider to give accurate information. 119 */ 120 public abstract boolean hasMonetaryCost(); 121 122 /** 123 * Returns true if the provider is able to provide altitude 124 * information, false otherwise. A provider that reports altitude 125 * under most circumstances but may occassionally not report it 126 * should return true. 127 */ 128 public abstract boolean supportsAltitude(); 129 130 /** 131 * Returns true if the provider is able to provide speed 132 * information, false otherwise. A provider that reports speed 133 * under most circumstances but may occassionally not report it 134 * should return true. 135 */ 136 public abstract boolean supportsSpeed(); 137 138 /** 139 * Returns true if the provider is able to provide bearing 140 * information, false otherwise. A provider that reports bearing 141 * under most circumstances but may occassionally not report it 142 * should return true. 143 */ 144 public abstract boolean supportsBearing(); 145 146 /** 147 * Returns the power requirement for this provider. 148 * 149 * @return the power requirement for this provider, as one of the 150 * constants Criteria.POWER_REQUIREMENT_*. 151 */ 152 public abstract int getPowerRequirement(); 153 154 /** 155 * Returns a constant describing horizontal accuracy of this provider. 156 * If the provider returns finer grain or exact location, 157 * {@link Criteria#ACCURACY_FINE} is returned, otherwise if the 158 * location is only approximate then {@link Criteria#ACCURACY_COARSE} 159 * is returned. 160 */ 161 public abstract int getAccuracy(); 162} 163