LocationProvider.java revision a4903f254b4711c8fc0ac5f7e3d605f4dce34f35 
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        // We do not want to match the special passive provider based on criteria.
75        if (LocationManager.PASSIVE_PROVIDER.equals(mName)) {
76            return false;
77        }
78        if ((criteria.getAccuracy() != Criteria.NO_REQUIREMENT) &&
79            (criteria.getAccuracy() < getAccuracy())) {
80            return false;
81        }
82        int criteriaPower = criteria.getPowerRequirement();
83        if ((criteriaPower != Criteria.NO_REQUIREMENT) &&
84            (criteriaPower < getPowerRequirement())) {
85            return false;
86        }
87        if (criteria.isAltitudeRequired() && !supportsAltitude()) {
88            return false;
89        }
90        if (criteria.isSpeedRequired() && !supportsSpeed()) {
91            return false;
92        }
93        if (criteria.isBearingRequired() && !supportsBearing()) {
94            return false;
95        }
96        return true;
97    }
98
99    /**
100     * Returns true if the provider requires access to a
101     * data network (e.g., the Internet), false otherwise.
102     */
103    public abstract boolean requiresNetwork();
104
105    /**
106     * Returns true if the provider requires access to a
107     * satellite-based positioning system (e.g., GPS), false
108     * otherwise.
109     */
110    public abstract boolean requiresSatellite();
111
112    /**
113     * Returns true if the provider requires access to an appropriate
114     * cellular network (e.g., to make use of cell tower IDs), false
115     * otherwise.
116     */
117    public abstract boolean requiresCell();
118
119    /**
120     * Returns true if the use of this provider may result in a
121     * monetary charge to the user, false if use is free.  It is up to
122     * each provider to give accurate information.
123     */
124    public abstract boolean hasMonetaryCost();
125
126    /**
127     * Returns true if the provider is able to provide altitude
128     * information, false otherwise.  A provider that reports altitude
129     * under most circumstances but may occassionally not report it
130     * should return true.
131     */
132    public abstract boolean supportsAltitude();
133
134    /**
135     * Returns true if the provider is able to provide speed
136     * information, false otherwise.  A provider that reports speed
137     * under most circumstances but may occassionally not report it
138     * should return true.
139     */
140    public abstract boolean supportsSpeed();
141
142    /**
143     * Returns true if the provider is able to provide bearing
144     * information, false otherwise.  A provider that reports bearing
145     * under most circumstances but may occassionally not report it
146     * should return true.
147     */
148    public abstract boolean supportsBearing();
149
150    /**
151     * Returns the power requirement for this provider.
152     *
153     * @return the power requirement for this provider, as one of the
154     * constants Criteria.POWER_REQUIREMENT_*.
155     */
156    public abstract int getPowerRequirement();
157
158    /**
159     * Returns a constant describing horizontal accuracy of this provider.
160     * If the provider returns finer grain or exact location,
161     * {@link Criteria#ACCURACY_FINE} is returned, otherwise if the
162     * location is only approximate then {@link Criteria#ACCURACY_COARSE}
163     * is returned.
164     */
165    public abstract int getAccuracy();
166}
167