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 17 package android.location; 18 19 20 import com.android.internal.location.ProviderProperties; 21 22 /** 23 * An abstract superclass for location providers. A location provider 24 * provides periodic reports on the geographical location of the 25 * device. 26 * 27 * <p> Each provider has a set of criteria under which it may be used; 28 * for example, some providers require GPS hardware and visibility to 29 * a number of satellites; others require the use of the cellular 30 * radio, or access to a specific carrier's network, or to the 31 * internet. They may also have different battery consumption 32 * characteristics or monetary costs to the user. The {@link 33 * Criteria} class allows providers to be selected based on 34 * user-specified criteria. 35 */ 36 public class LocationProvider { 37 public static final int OUT_OF_SERVICE = 0; 38 public static final int TEMPORARILY_UNAVAILABLE = 1; 39 public static final int AVAILABLE = 2; 40 41 /** 42 * A regular expression matching characters that may not appear 43 * in the name of a LocationProvider 44 * @hide 45 */ 46 public static final String BAD_CHARS_REGEX = "[^a-zA-Z0-9]"; 47 48 private final String mName; 49 private final ProviderProperties mProperties; 50 51 /** 52 * Constructs a LocationProvider with the given name. Provider names must 53 * consist only of the characters [a-zA-Z0-9]. 54 * 55 * @throws IllegalArgumentException if name contains an illegal character 56 * 57 * @hide 58 */ LocationProvider(String name, ProviderProperties properties)59 public LocationProvider(String name, ProviderProperties properties) { 60 if (name.matches(BAD_CHARS_REGEX)) { 61 throw new IllegalArgumentException("provider name contains illegal character: " + name); 62 } 63 mName = name; 64 mProperties = properties; 65 } 66 67 /** 68 * Returns the name of this provider. 69 */ getName()70 public String getName() { 71 return mName; 72 } 73 74 /** 75 * Returns true if this provider meets the given criteria, 76 * false otherwise. 77 */ meetsCriteria(Criteria criteria)78 public boolean meetsCriteria(Criteria criteria) { 79 return propertiesMeetCriteria(mName, mProperties, criteria); 80 } 81 82 /** 83 * @hide 84 */ propertiesMeetCriteria(String name, ProviderProperties properties, Criteria criteria)85 public static boolean propertiesMeetCriteria(String name, ProviderProperties properties, 86 Criteria criteria) { 87 if (LocationManager.PASSIVE_PROVIDER.equals(name)) { 88 // passive provider never matches 89 return false; 90 } 91 if (properties == null) { 92 // unfortunately this can happen for provider in remote services 93 // that have not finished binding yet 94 return false; 95 } 96 97 if (criteria.getAccuracy() != Criteria.NO_REQUIREMENT && 98 criteria.getAccuracy() < properties.mAccuracy) { 99 return false; 100 } 101 if (criteria.getPowerRequirement() != Criteria.NO_REQUIREMENT && 102 criteria.getPowerRequirement() < properties.mPowerRequirement) { 103 return false; 104 } 105 if (criteria.isAltitudeRequired() && !properties.mSupportsAltitude) { 106 return false; 107 } 108 if (criteria.isSpeedRequired() && !properties.mSupportsSpeed) { 109 return false; 110 } 111 if (criteria.isBearingRequired() && !properties.mSupportsBearing) { 112 return false; 113 } 114 if (!criteria.isCostAllowed() && properties.mHasMonetaryCost) { 115 return false; 116 } 117 return true; 118 } 119 120 /** 121 * Returns true if the provider requires access to a 122 * data network (e.g., the Internet), false otherwise. 123 */ requiresNetwork()124 public boolean requiresNetwork() { 125 return mProperties.mRequiresNetwork; 126 } 127 128 /** 129 * Returns true if the provider requires access to a 130 * satellite-based positioning system (e.g., GPS), false 131 * otherwise. 132 */ requiresSatellite()133 public boolean requiresSatellite() { 134 return mProperties.mRequiresSatellite; 135 } 136 137 /** 138 * Returns true if the provider requires access to an appropriate 139 * cellular network (e.g., to make use of cell tower IDs), false 140 * otherwise. 141 */ requiresCell()142 public boolean requiresCell() { 143 return mProperties.mRequiresCell; 144 } 145 146 /** 147 * Returns true if the use of this provider may result in a 148 * monetary charge to the user, false if use is free. It is up to 149 * each provider to give accurate information. 150 */ hasMonetaryCost()151 public boolean hasMonetaryCost() { 152 return mProperties.mHasMonetaryCost; 153 } 154 155 /** 156 * Returns true if the provider is able to provide altitude 157 * information, false otherwise. A provider that reports altitude 158 * under most circumstances but may occassionally not report it 159 * should return true. 160 */ supportsAltitude()161 public boolean supportsAltitude() { 162 return mProperties.mSupportsAltitude; 163 } 164 165 /** 166 * Returns true if the provider is able to provide speed 167 * information, false otherwise. A provider that reports speed 168 * under most circumstances but may occassionally not report it 169 * should return true. 170 */ supportsSpeed()171 public boolean supportsSpeed() { 172 return mProperties.mSupportsSpeed; 173 } 174 175 /** 176 * Returns true if the provider is able to provide bearing 177 * information, false otherwise. A provider that reports bearing 178 * under most circumstances but may occassionally not report it 179 * should return true. 180 */ supportsBearing()181 public boolean supportsBearing() { 182 return mProperties.mSupportsBearing; 183 } 184 185 /** 186 * Returns the power requirement for this provider. 187 * 188 * @return the power requirement for this provider, as one of the 189 * constants Criteria.POWER_REQUIREMENT_*. 190 */ getPowerRequirement()191 public int getPowerRequirement() { 192 return mProperties.mPowerRequirement; 193 } 194 195 /** 196 * Returns a constant describing horizontal accuracy of this provider. 197 * If the provider returns finer grain or exact location, 198 * {@link Criteria#ACCURACY_FINE} is returned, otherwise if the 199 * location is only approximate then {@link Criteria#ACCURACY_COARSE} 200 * is returned. 201 */ getAccuracy()202 public int getAccuracy() { 203 return mProperties.mAccuracy; 204 } 205 } 206