19066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/* 29066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Copyright (C) 2007 The Android Open Source Project 39066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); 59066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * you may not use this file except in compliance with the License. 69066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * You may obtain a copy of the License at 79066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 89066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 99066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Unless required by applicable law or agreed to in writing, software 119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * See the License for the specific language governing permissions and 149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * limitations under the License. 159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpackage android.location; 189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 196fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 206fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pellyimport com.android.internal.location.ProviderProperties; 2103ca216ac19ea4e7afcb183c20c7c780f0d97756Mike Lockwood 229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/** 239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * An abstract superclass for location providers. A location provider 249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * provides periodic reports on the geographical location of the 259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * device. 269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * <p> Each provider has a set of criteria under which it may be used; 289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * for example, some providers require GPS hardware and visibility to 299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * a number of satellites; others require the use of the cellular 309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * radio, or access to a specific carrier's network, or to the 319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * internet. They may also have different battery consumption 329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * characteristics or monetary costs to the user. The {@link 339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Criteria} class allows providers to be selected based on 349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * user-specified criteria. 359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 366fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pellypublic class LocationProvider { 379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public static final int OUT_OF_SERVICE = 0; 389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public static final int TEMPORARILY_UNAVAILABLE = 1; 399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public static final int AVAILABLE = 2; 409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 426fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * A regular expression matching characters that may not appear 436fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * in the name of a LocationProvider 446fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * @hide 456fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly */ 466fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static final String BAD_CHARS_REGEX = "[^a-zA-Z0-9]"; 476fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 486fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private final String mName; 496fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private final ProviderProperties mProperties; 506fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 516fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** 529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Constructs a LocationProvider with the given name. Provider names must 539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * consist only of the characters [a-zA-Z0-9]. 549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @throws IllegalArgumentException if name contains an illegal character 5679762a3ee34eb8be5549bcb183af844b6f19c266Mike Lockwood * 576fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * @hide 589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 596fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationProvider(String name, ProviderProperties properties) { 609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project if (name.matches(BAD_CHARS_REGEX)) { 616fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly throw new IllegalArgumentException("provider name contains illegal character: " + name); 629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mName = name; 646fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly mProperties = properties; 659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns the name of this provider. 699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public String getName() { 719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mName; 729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns true if this provider meets the given criteria, 769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * false otherwise. 779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean meetsCriteria(Criteria criteria) { 796fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return propertiesMeetCriteria(mName, mProperties, criteria); 806fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 816fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 826fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** 836fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * @hide 846fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly */ 856fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static boolean propertiesMeetCriteria(String name, ProviderProperties properties, 866fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly Criteria criteria) { 876fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (LocationManager.PASSIVE_PROVIDER.equals(name)) { 886fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly // passive provider never matches 896fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return false; 906fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 916fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (properties == null) { 926fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly // unfortunately this can happen for provider in remote services 936fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly // that have not finished binding yet 946fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return false; 956fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 966fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 976fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (criteria.getAccuracy() != Criteria.NO_REQUIREMENT && 986fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly criteria.getAccuracy() < properties.mAccuracy) { 999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return false; 1009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1016fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (criteria.getPowerRequirement() != Criteria.NO_REQUIREMENT && 1026fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly criteria.getPowerRequirement() < properties.mPowerRequirement) { 1036fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return false; 1046fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1056fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (criteria.isAltitudeRequired() && !properties.mSupportsAltitude) { 1066fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return false; 1076fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1086fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (criteria.isSpeedRequired() && !properties.mSupportsSpeed) { 1096fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return false; 1106fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1116fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (criteria.isBearingRequired() && !properties.mSupportsBearing) { 1126fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return false; 1136fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1146fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (!criteria.isCostAllowed() && properties.mHasMonetaryCost) { 1156fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return false; 1166fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1176fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return true; 1189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns true if the provider requires access to a 1229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * data network (e.g., the Internet), false otherwise. 1239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1246fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public boolean requiresNetwork() { 1256fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProperties.mRequiresNetwork; 1266fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns true if the provider requires access to a 1309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * satellite-based positioning system (e.g., GPS), false 1319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * otherwise. 1329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1336fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public boolean requiresSatellite() { 1346fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProperties.mRequiresSatellite; 1356fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns true if the provider requires access to an appropriate 1399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * cellular network (e.g., to make use of cell tower IDs), false 1409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * otherwise. 1419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1426fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public boolean requiresCell() { 1436fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProperties.mRequiresCell; 1446fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns true if the use of this provider may result in a 1489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * monetary charge to the user, false if use is free. It is up to 1499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * each provider to give accurate information. 1509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1516fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public boolean hasMonetaryCost() { 1526fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProperties.mHasMonetaryCost; 1536fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns true if the provider is able to provide altitude 1579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * information, false otherwise. A provider that reports altitude 1589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * under most circumstances but may occassionally not report it 1599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * should return true. 1609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1616fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public boolean supportsAltitude() { 1626fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProperties.mSupportsAltitude; 1636fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns true if the provider is able to provide speed 1679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * information, false otherwise. A provider that reports speed 1689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * under most circumstances but may occassionally not report it 1699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * should return true. 1709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1716fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public boolean supportsSpeed() { 1726fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProperties.mSupportsSpeed; 1736fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns true if the provider is able to provide bearing 1779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * information, false otherwise. A provider that reports bearing 1789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * under most circumstances but may occassionally not report it 1799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * should return true. 1809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1816fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public boolean supportsBearing() { 1826fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProperties.mSupportsBearing; 1836fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns the power requirement for this provider. 1879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 1889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @return the power requirement for this provider, as one of the 1899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * constants Criteria.POWER_REQUIREMENT_*. 1909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1916fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public int getPowerRequirement() { 1926fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProperties.mPowerRequirement; 1936fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Returns a constant describing horizontal accuracy of this provider. 1979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * If the provider returns finer grain or exact location, 1989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link Criteria#ACCURACY_FINE} is returned, otherwise if the 1999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * location is only approximate then {@link Criteria#ACCURACY_COARSE} 2009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * is returned. 2019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2026fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public int getAccuracy() { 2036fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProperties.mAccuracy; 2046fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 2059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 206