Java tutorial
/* * Copyright (C) 2007 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.location; import com.android.internal.location.ProviderProperties; /** * An abstract superclass for location providers. A location provider * provides periodic reports on the geographical location of the * device. * * <p> Each provider has a set of criteria under which it may be used; * for example, some providers require GPS hardware and visibility to * a number of satellites; others require the use of the cellular * radio, or access to a specific carrier's network, or to the * internet. They may also have different battery consumption * characteristics or monetary costs to the user. The {@link * Criteria} class allows providers to be selected based on * user-specified criteria. */ public class LocationProvider { public static final int OUT_OF_SERVICE = 0; public static final int TEMPORARILY_UNAVAILABLE = 1; public static final int AVAILABLE = 2; /** * A regular expression matching characters that may not appear * in the name of a LocationProvider * @hide */ public static final String BAD_CHARS_REGEX = "[^a-zA-Z0-9]"; private final String mName; private final ProviderProperties mProperties; /** * Constructs a LocationProvider with the given name. Provider names must * consist only of the characters [a-zA-Z0-9]. * * @throws IllegalArgumentException if name contains an illegal character * * @hide */ public LocationProvider(String name, ProviderProperties properties) { if (name.matches(BAD_CHARS_REGEX)) { throw new IllegalArgumentException("provider name contains illegal character: " + name); } mName = name; mProperties = properties; } /** * Returns the name of this provider. */ public String getName() { return mName; } /** * Returns true if this provider meets the given criteria, * false otherwise. */ public boolean meetsCriteria(Criteria criteria) { return propertiesMeetCriteria(mName, mProperties, criteria); } /** * @hide */ public static boolean propertiesMeetCriteria(String name, ProviderProperties properties, Criteria criteria) { if (LocationManager.PASSIVE_PROVIDER.equals(name)) { // passive provider never matches return false; } if (properties == null) { // unfortunately this can happen for provider in remote services // that have not finished binding yet return false; } if (criteria.getAccuracy() != Criteria.NO_REQUIREMENT && criteria.getAccuracy() < properties.mAccuracy) { return false; } if (criteria.getPowerRequirement() != Criteria.NO_REQUIREMENT && criteria.getPowerRequirement() < properties.mPowerRequirement) { return false; } if (criteria.isAltitudeRequired() && !properties.mSupportsAltitude) { return false; } if (criteria.isSpeedRequired() && !properties.mSupportsSpeed) { return false; } if (criteria.isBearingRequired() && !properties.mSupportsBearing) { return false; } if (!criteria.isCostAllowed() && properties.mHasMonetaryCost) { return false; } return true; } /** * Returns true if the provider requires access to a * data network (e.g., the Internet), false otherwise. */ public boolean requiresNetwork() { return mProperties.mRequiresNetwork; } /** * Returns true if the provider requires access to a * satellite-based positioning system (e.g., GPS), false * otherwise. */ public boolean requiresSatellite() { return mProperties.mRequiresSatellite; } /** * Returns true if the provider requires access to an appropriate * cellular network (e.g., to make use of cell tower IDs), false * otherwise. */ public boolean requiresCell() { return mProperties.mRequiresCell; } /** * Returns true if the use of this provider may result in a * monetary charge to the user, false if use is free. It is up to * each provider to give accurate information. */ public boolean hasMonetaryCost() { return mProperties.mHasMonetaryCost; } /** * Returns true if the provider is able to provide altitude * information, false otherwise. A provider that reports altitude * under most circumstances but may occassionally not report it * should return true. */ public boolean supportsAltitude() { return mProperties.mSupportsAltitude; } /** * Returns true if the provider is able to provide speed * information, false otherwise. A provider that reports speed * under most circumstances but may occassionally not report it * should return true. */ public boolean supportsSpeed() { return mProperties.mSupportsSpeed; } /** * Returns true if the provider is able to provide bearing * information, false otherwise. A provider that reports bearing * under most circumstances but may occassionally not report it * should return true. */ public boolean supportsBearing() { return mProperties.mSupportsBearing; } /** * Returns the power requirement for this provider. * * @return the power requirement for this provider, as one of the * constants Criteria.POWER_REQUIREMENT_*. */ public int getPowerRequirement() { return mProperties.mPowerRequirement; } /** * Returns a constant describing horizontal accuracy of this provider. * If the provider returns finer grain or exact location, * {@link Criteria#ACCURACY_FINE} is returned, otherwise if the * location is only approximate then {@link Criteria#ACCURACY_COARSE} * is returned. */ public int getAccuracy() { return mProperties.mAccuracy; } }