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