LocationProvider.java revision 843ef36f7b96cc19ea7d2996b7c8661b41ec3452 
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