LocationProvider.java revision 03ca216ac19ea4e7afcb183c20c7c780f0d97756 
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
19import android.os.RemoteException;
20import android.util.Log;
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 */
36public abstract class LocationProvider {
37    private static final String TAG = "LocationProvider";
38    // A regular expression matching characters that may not appear
39    // in the name of a LocationProvider.
40    static final String BAD_CHARS_REGEX = "[^a-zA-Z0-9]";
41
42    private final String mName;
43    private final ILocationManager mService;
44
45    public static final int OUT_OF_SERVICE = 0;
46    public static final int TEMPORARILY_UNAVAILABLE = 1;
47    public static final int AVAILABLE = 2;
48
49    /**
50     * Constructs a LocationProvider with the given name.   Provider names must
51     * consist only of the characters [a-zA-Z0-9].
52     *
53     * @throws IllegalArgumentException if name contains an illegal character
54     *
55     * {@hide}
56     */
57    public LocationProvider(String name, ILocationManager service) {
58        if (name.matches(BAD_CHARS_REGEX)) {
59            throw new IllegalArgumentException("name " + name +
60                " contains an illegal character");
61        }
62        mName = name;
63        mService = service;
64    }
65
66    /**
67     * Returns the name of this provider.
68     */
69    public String getName() {
70        return mName;
71    }
72
73    /**
74     * Returns true if this provider meets the given criteria,
75     * false otherwise.
76     */
77    public boolean meetsCriteria(Criteria criteria) {
78        try {
79            return mService.providerMeetsCriteria(mName, criteria);
80        } catch (RemoteException e) {
81            Log.e(TAG, "meetsCriteria: RemoteException", e);
82            return false;
83        }
84    }
85
86    /**
87     * Returns true if the provider requires access to a
88     * data network (e.g., the Internet), false otherwise.
89     */
90    public abstract boolean requiresNetwork();
91
92    /**
93     * Returns true if the provider requires access to a
94     * satellite-based positioning system (e.g., GPS), false
95     * otherwise.
96     */
97    public abstract boolean requiresSatellite();
98
99    /**
100     * Returns true if the provider requires access to an appropriate
101     * cellular network (e.g., to make use of cell tower IDs), false
102     * otherwise.
103     */
104    public abstract boolean requiresCell();
105
106    /**
107     * Returns true if the use of this provider may result in a
108     * monetary charge to the user, false if use is free.  It is up to
109     * each provider to give accurate information.
110     */
111    public abstract boolean hasMonetaryCost();
112
113    /**
114     * Returns true if the provider is able to provide altitude
115     * information, false otherwise.  A provider that reports altitude
116     * under most circumstances but may occassionally not report it
117     * should return true.
118     */
119    public abstract boolean supportsAltitude();
120
121    /**
122     * Returns true if the provider is able to provide speed
123     * information, false otherwise.  A provider that reports speed
124     * under most circumstances but may occassionally not report it
125     * should return true.
126     */
127    public abstract boolean supportsSpeed();
128
129    /**
130     * Returns true if the provider is able to provide bearing
131     * information, false otherwise.  A provider that reports bearing
132     * under most circumstances but may occassionally not report it
133     * should return true.
134     */
135    public abstract boolean supportsBearing();
136
137    /**
138     * Returns the power requirement for this provider.
139     *
140     * @return the power requirement for this provider, as one of the
141     * constants Criteria.POWER_REQUIREMENT_*.
142     */
143    public abstract int getPowerRequirement();
144
145    /**
146     * Returns a constant describing horizontal accuracy of this provider.
147     * If the provider returns finer grain or exact location,
148     * {@link Criteria#ACCURACY_FINE} is returned, otherwise if the
149     * location is only approximate then {@link Criteria#ACCURACY_COARSE}
150     * is returned.
151     */
152    public abstract int getAccuracy();
153}
154