IT. Expert System.

Android Reference

LocationManager


android.location

Class LocationManager



  • public class LocationManager
    extends Object
    This class provides access to the system location services. These services allow applications to obtain periodic updates of the device's geographical location, or to fire an application-specified Intent when the device enters the proximity of a given geographical location.

    You do not instantiate this class directly; instead, retrieve it through Context.getSystemService(Context.LOCATION_SERVICE).

    Unless noted, all Location API methods require the android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION permissions. If your application only has the coarse permission then it will not have access to the GPS or passive location providers. Other providers will still return location results, but the update rate will be throttled and the exact location will be obfuscated to a coarse level of accuracy.

    • Field Detail

      • NETWORK_PROVIDER

        public static final String NETWORK_PROVIDER
        Name of the network location provider.

        This provider determines location based on availability of cell tower and WiFi access points. Results are retrieved by means of a network lookup.

        See Also:
        Constant Field Values
      • GPS_PROVIDER

        public static final String GPS_PROVIDER
        Name of the GPS location provider.

        This provider determines location using satellites. Depending on conditions, this provider may take a while to return a location fix. Requires the permission android.Manifest.permission#ACCESS_FINE_LOCATION.

        The extras Bundle for the GPS location provider can contain the following key/value pairs:

        • satellites - the number of satellites used to derive the fix
        See Also:
        Constant Field Values
      • PASSIVE_PROVIDER

        public static final String PASSIVE_PROVIDER
        A special location provider for receiving locations without actually initiating a location fix.

        This provider can be used to passively receive location updates when other applications or services request them without actually requesting the locations yourself. This provider will return locations generated by other providers. You can query the Location.getProvider() method to determine the origin of the location update. Requires the permission android.Manifest.permission#ACCESS_FINE_LOCATION, although if the GPS is not enabled this provider might only return coarse fixes.

        See Also:
        Constant Field Values
      • FUSED_PROVIDER

        public static final String FUSED_PROVIDER
        Name of the Fused location provider.

        This provider combines inputs for all possible location sources to provide the best possible Location fix. It is implicitly used for all API's that involve the LocationRequest object.

        See Also:
        Constant Field Values
      • KEY_PROXIMITY_ENTERING

        public static final String KEY_PROXIMITY_ENTERING
        Key used for the Bundle extra holding a boolean indicating whether a proximity alert is entering (true) or exiting (false)..
        See Also:
        Constant Field Values
      • KEY_STATUS_CHANGED

        public static final String KEY_STATUS_CHANGED
        Key used for a Bundle extra holding an Integer status value when a status change is broadcast using a PendingIntent.
        See Also:
        Constant Field Values
      • KEY_PROVIDER_ENABLED

        public static final String KEY_PROVIDER_ENABLED
        Key used for a Bundle extra holding an Boolean status value when a provider enabled/disabled event is broadcast using a PendingIntent.
        See Also:
        Constant Field Values
      • KEY_LOCATION_CHANGED

        public static final String KEY_LOCATION_CHANGED
        Key used for a Bundle extra holding a Location value when a location change is broadcast using a PendingIntent.
        See Also:
        Constant Field Values
      • GPS_ENABLED_CHANGE_ACTION

        public static final String GPS_ENABLED_CHANGE_ACTION
        Broadcast intent action indicating that the GPS has either been enabled or disabled. An intent extra provides this state as a boolean, where true means enabled.
        See Also:
        EXTRA_GPS_ENABLED, Constant Field Values
      • PROVIDERS_CHANGED_ACTION

        public static final String PROVIDERS_CHANGED_ACTION
        Broadcast intent action when the configured location providers change.
        See Also:
        Constant Field Values
      • GPS_FIX_CHANGE_ACTION

        public static final String GPS_FIX_CHANGE_ACTION
        Broadcast intent action indicating that the GPS has either started or stopped receiving GPS fixes. An intent extra provides this state as a boolean, where true means that the GPS is actively receiving fixes.
        See Also:
        EXTRA_GPS_ENABLED, Constant Field Values
    • Constructor Detail

      • LocationManager

        public LocationManager(Context context,
                       ILocationManager service)
    • Method Detail

      • getAllProviders

        public List<String> getAllProviders()
        Returns a list of the names of all known location providers.

        All providers are returned, including ones that are not permitted to be accessed by the calling activity or are currently disabled.

        Returns:
        list of Strings containing names of the provider
      • getProviders

        public List<String> getProviders(boolean enabledOnly)
        Returns a list of the names of location providers.
        Parameters:
        enabledOnly - if true then only the providers which are currently enabled are returned.
        Returns:
        list of Strings containing names of the providers
      • getProvider

        public LocationProvider getProvider(String name)
        Returns the information associated with the location provider of the given name, or null if no provider exists by that name.
        Parameters:
        name - the provider name
        Returns:
        a LocationProvider, or null
        Throws:
        IllegalArgumentException - if name is null or does not exist
        SecurityException - if the caller is not permitted to access the given provider.
      • getProviders

        public List<String> getProviders(Criteria criteria,
                                boolean enabledOnly)
        Returns a list of the names of LocationProviders that satisfy the given criteria, or null if none do. Only providers that are permitted to be accessed by the calling activity will be returned.
        Parameters:
        criteria - the criteria that the returned providers must match
        enabledOnly - if true then only the providers which are currently enabled are returned.
        Returns:
        list of Strings containing names of the providers
      • getBestProvider

        public String getBestProvider(Criteria criteria,
                             boolean enabledOnly)
        Returns the name of the provider that best meets the given criteria. Only providers that are permitted to be accessed by the calling activity will be returned. If several providers meet the criteria, the one with the best accuracy is returned. If no provider meets the criteria, the criteria are loosened in the following sequence:
        • power requirement
        • accuracy
        • bearing
        • speed
        • altitude

        Note that the requirement on monetary cost is not removed in this process.

        Parameters:
        criteria - the criteria that need to be matched
        enabledOnly - if true then only a provider that is currently enabled is returned
        Returns:
        name of the provider that best matches the requirements
      • requestLocationUpdates

        public void requestLocationUpdates(long minTime,
                                  float minDistance,
                                  Criteria criteria,
                                  PendingIntent intent)
        Register for location updates using a Criteria and pending intent.

        The requestLocationUpdates() and requestSingleUpdate() register the current activity to be updated periodically by the named provider, or by the provider matching the specified Criteria, with location and status updates.

        It may take a while to receive the first location update. If an immediate location is required, applications may use the getLastKnownLocation(String) method.

        Location updates are received either by LocationListener callbacks, or by broadcast intents to a supplied PendingIntent.

        If the caller supplied a pending intent, then location updates are sent with a key of KEY_LOCATION_CHANGED and a Location value.

        The location update interval can be controlled using the minTime parameter. The elapsed time between location updates will never be less than minTime, although it can be more depending on the Location Provider implementation and the update interval requested by other applications.

        Choosing a sensible value for minTime is important to conserve battery life. Each location update requires power from GPS, WIFI, Cell and other radios. Select a minTime value as high as possible while still providing a reasonable user experience. If your application is not in the foreground and showing location to the user then your application should avoid using an active provider (such as NETWORK_PROVIDER or GPS_PROVIDER), but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes) or greater. If your application is in the foreground and showing location to the user then it is appropriate to select a faster update interval.

        The minDistance parameter can also be used to control the frequency of location updates. If it is greater than 0 then the location provider will only send your application an update when the location has changed by at least minDistance meters, AND at least minTime milliseconds have passed. However it is more difficult for location providers to save power using the minDistance parameter, so minTime should be the primary tool to conserving battery life.

        If your application wants to passively observe location updates triggered by other applications, but not consume any additional power otherwise, then use the PASSIVE_PROVIDER This provider does not actively turn on or modify active location providers, so you do not need to be as careful about minTime and minDistance. However if your application performs heavy work on a location update (such as network activity) then you should select non-zero values for minTime and/or minDistance to rate-limit your update frequency in the case another application enables a location provider with extremely fast updates.

        In case the provider is disabled by the user, updates will stop, and a provider availability update will be sent. As soon as the provider is enabled again, location updates will immediately resume and a provider availability update sent. Providers can also send status updates, at any time, with extra's specific to the provider. If a callback was supplied then status and availability updates are via LocationListener.onProviderDisabled(java.lang.String), LocationListener.onProviderEnabled(java.lang.String) or LocationListener.onStatusChanged(java.lang.String, int, android.os.Bundle). Alternately, if a pending intent was supplied then status and availability updates are broadcast intents with extra keys of KEY_PROVIDER_ENABLED or KEY_STATUS_CHANGED.

        If a LocationListener is used but with no Looper specified then the calling thread must already be a Looper thread such as the main thread of the calling Activity. If a Looper is specified with a LocationListener then callbacks are made on the supplied Looper thread.

        Prior to Jellybean, the minTime parameter was only a hint, and some location provider implementations ignored it. From Jellybean and onwards it is mandatory for Android compatible devices to observe both the minTime and minDistance parameters.

        Parameters:
        minTime - minimum time interval between location updates, in milliseconds
        minDistance - minimum distance between location updates, in meters
        criteria - contains parameters for the location manager to choose the appropriate provider and parameters to compute the location
        intent - a PendingIntent to be sent for each location update
        Throws:
        IllegalArgumentException - if criteria is null
        IllegalArgumentException - if intent is null
        SecurityException - if no suitable permission is present
      • removeUpdates

        public void removeUpdates(LocationListener listener)
        Removes all location updates for the specified LocationListener.

        Following this call, updates will no longer occur for this listener.

        Parameters:
        listener - listener object that no longer needs location updates
        Throws:
        IllegalArgumentException - if listener is null
      • removeUpdates

        public void removeUpdates(PendingIntent intent)
        Removes all location updates for the specified pending intent.

        Following this call, updates will no longer for this pending intent.

        Parameters:
        intent - pending intent object that no longer needs location updates
        Throws:
        IllegalArgumentException - if intent is null
      • addProximityAlert

        public void addProximityAlert(double latitude,
                             double longitude,
                             float radius,
                             long expiration,
                             PendingIntent intent)
        Set a proximity alert for the location given by the position (latitude, longitude) and the given radius.

        When the device detects that it has entered or exited the area surrounding the location, the given PendingIntent will be used to create an Intent to be fired.

        The fired Intent will have a boolean extra added with key KEY_PROXIMITY_ENTERING. If the value is true, the device is entering the proximity region; if false, it is exiting.

        Due to the approximate nature of position estimation, if the device passes through the given area briefly, it is possible that no Intent will be fired. Similarly, an Intent could be fired if the device passes very close to the given area but does not actually enter it.

        After the number of milliseconds given by the expiration parameter, the location manager will delete this proximity alert and no longer monitor it. A value of -1 indicates that there should be no expiration time.

        Internally, this method uses both NETWORK_PROVIDER and GPS_PROVIDER.

        Before API version 17, this method could be used with android.Manifest.permission#ACCESS_FINE_LOCATION or android.Manifest.permission#ACCESS_COARSE_LOCATION. From API version 17 and onwards, this method requires android.Manifest.permission#ACCESS_FINE_LOCATION permission.

        Parameters:
        latitude - the latitude of the central point of the alert region
        longitude - the longitude of the central point of the alert region
        radius - the radius of the central point of the alert region, in meters
        expiration - time for this proximity alert, in milliseconds, or -1 to indicate no expiration
        intent - a PendingIntent that will be used to generate an Intent to fire when entry to or exit from the alert region is detected
        Throws:
        SecurityException - if android.Manifest.permission#ACCESS_FINE_LOCATION permission is not present
      • addGeofence

        public void addGeofence(LocationRequest request,
                       Geofence fence,
                       PendingIntent intent)
        Add a geofence with the specified LocationRequest quality of service.

        When the device detects that it has entered or exited the area surrounding the location, the given PendingIntent will be used to create an Intent to be fired.

        The fired Intent will have a boolean extra added with key KEY_PROXIMITY_ENTERING. If the value is true, the device is entering the proximity region; if false, it is exiting.

        The geofence engine fuses results from all location providers to provide the best balance between accuracy and power. Applications can choose the quality of service required using the LocationRequest object. If it is null then a default, low power geo-fencing implementation is used. It is possible to cross a geo-fence without notification, but the system will do its best to detect, using LocationRequest as a hint to trade-off accuracy and power.

        The power required by the geofence engine can depend on many factors, such as quality and interval requested in LocationRequest, distance to nearest geofence and current device velocity.

        Parameters:
        request - quality of service required, null for default low power
        fence - a geographical description of the geofence area
        intent - pending intent to receive geofence updates
        Throws:
        IllegalArgumentException - if fence is null
        IllegalArgumentException - if intent is null
        SecurityException - if android.Manifest.permission#ACCESS_FINE_LOCATION permission is not present
      • removeProximityAlert

        public void removeProximityAlert(PendingIntent intent)
        Removes the proximity alert with the given PendingIntent.

        Before API version 17, this method could be used with android.Manifest.permission#ACCESS_FINE_LOCATION or android.Manifest.permission#ACCESS_COARSE_LOCATION. From API version 17 and onwards, this method requires android.Manifest.permission#ACCESS_FINE_LOCATION permission.

        Parameters:
        intent - the PendingIntent that no longer needs to be notified of proximity alerts
        Throws:
        IllegalArgumentException - if intent is null
        SecurityException - if android.Manifest.permission#ACCESS_FINE_LOCATION permission is not present
      • isProviderEnabled

        public boolean isProviderEnabled(String provider)
        Returns the current enabled/disabled status of the given provider.

        If the user has enabled this provider in the Settings menu, true is returned otherwise false is returned

        Parameters:
        provider - the name of the provider
        Returns:
        true if the provider is enabled
        Throws:
        IllegalArgumentException - if provider is null
        SecurityException - if no suitable permission is present
      • getLastLocation

        public Location getLastLocation()
        Get the last known location.

        This location could be very old so use Location.getElapsedRealtimeNanos() to calculate its age. It can also return null if no previous location is available.

        Always returns immediately.

        Returns:
        The last known location, or null if not available
        Throws:
        SecurityException - if no suitable permission is present
      • getLastKnownLocation

        public Location getLastKnownLocation(String provider)
        Returns a Location indicating the data from the last known location fix obtained from the given provider.

        This can be done without starting the provider. Note that this location could be out-of-date, for example if the device was turned off and moved to another location.

        If the provider is currently disabled, null is returned.

        Parameters:
        provider - the name of the provider
        Returns:
        the last known location for the provider, or null
        Throws:
        SecurityException - if no suitable permission is present
        IllegalArgumentException - if provider is null or doesn't exist
      • addTestProvider

        public void addTestProvider(String name,
                           boolean requiresNetwork,
                           boolean requiresSatellite,
                           boolean requiresCell,
                           boolean hasMonetaryCost,
                           boolean supportsAltitude,
                           boolean supportsSpeed,
                           boolean supportsBearing,
                           int powerRequirement,
                           int accuracy)
        Creates a mock location provider and adds it to the set of active providers.
        Parameters:
        name - the provider name
        Throws:
        SecurityException - if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION system setting is not enabled
        IllegalArgumentException - if a provider with the given name already exists
      • setTestProviderLocation

        public void setTestProviderLocation(String provider,
                                   Location loc)
        Sets a mock location for the given provider.

        This location will be used in place of any actual location from the provider. The location object must have a minimum number of fields set to be considered a valid LocationProvider Location, as per documentation on Location class.

        Parameters:
        provider - the provider name
        loc - the mock location
        Throws:
        SecurityException - if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
        IllegalArgumentException - if no provider with the given name exists
        IllegalArgumentException - if the location is incomplete
      • setTestProviderEnabled

        public void setTestProviderEnabled(String provider,
                                  boolean enabled)
        Sets a mock enabled value for the given provider. This value will be used in place of any actual value from the provider.
        Parameters:
        provider - the provider name
        enabled - the mock enabled value
        Throws:
        SecurityException - if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
        IllegalArgumentException - if no provider with the given name exists
      • clearTestProviderEnabled

        public void clearTestProviderEnabled(String provider)
        Removes any mock enabled value associated with the given provider.
        Parameters:
        provider - the provider name
        Throws:
        SecurityException - if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
        IllegalArgumentException - if no provider with the given name exists
      • setTestProviderStatus

        public void setTestProviderStatus(String provider,
                                 int status,
                                 Bundle extras,
                                 long updateTime)
        Sets mock status values for the given provider. These values will be used in place of any actual values from the provider.
        Parameters:
        provider - the provider name
        status - the mock status
        extras - a Bundle containing mock extras
        updateTime - the mock update time
        Throws:
        SecurityException - if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
        IllegalArgumentException - if no provider with the given name exists
      • clearTestProviderStatus

        public void clearTestProviderStatus(String provider)
        Removes any mock status values associated with the given provider.
        Parameters:
        provider - the provider name
        Throws:
        SecurityException - if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
        IllegalArgumentException - if no provider with the given name exists
      • addGpsStatusListener

        public boolean addGpsStatusListener(GpsStatus.Listener listener)
        Adds a GPS status listener.
        Parameters:
        listener - GPS status listener object to register
        Returns:
        true if the listener was successfully added
        Throws:
        SecurityException - if the ACCESS_FINE_LOCATION permission is not present
      • removeGpsStatusListener

        public void removeGpsStatusListener(GpsStatus.Listener listener)
        Removes a GPS status listener.
        Parameters:
        listener - GPS status listener object to remove
      • getGpsStatus

        public GpsStatus getGpsStatus(GpsStatus status)
        Retrieves information about the current status of the GPS engine. This should only be called from the GpsStatus.Listener.onGpsStatusChanged(int) callback to ensure that the data is copied atomically. The caller may either pass in a GpsStatus object to set with the latest status information, or pass null to create a new GpsStatus object.
        Parameters:
        status - object containing GPS status details, or null.
        Returns:
        status object containing updated GPS status.
      • sendExtraCommand

        public boolean sendExtraCommand(String provider,
                               String command,
                               Bundle extras)
        Sends additional commands to a location provider. Can be used to support provider specific extensions to the Location Manager API
        Parameters:
        provider - name of the location provider.
        command - name of the command to send to the provider.
        extras - optional arguments for the command (or null). The provider may optionally fill the extras Bundle with results from the command.
        Returns:
        true if the command succeeds.
      • sendNiResponse

        public boolean sendNiResponse(int notifId,
                             int userResponse)
        Used by NetInitiatedActivity to report user response for network initiated GPS fix requests.


Content

Android Reference

Java basics

Java Enterprise Edition (EE)

Java Standard Edition (SE)

SQL

HTML

PHP

CSS

Java Script

MYSQL

JQUERY

VBS

REGEX

C

C++

C#

Design patterns

RFC (standard status)

RFC (proposed standard status)

RFC (draft standard status)

RFC (informational status)

RFC (experimental status)

RFC (best current practice status)

RFC (historic status)

RFC (unknown status)

IT dictionary

License.
All information of this service is derived from the free sources and is provided solely in the form of quotations. This service provides information and interfaces solely for the familiarization (not ownership) and under the "as is" condition.
Copyright 2016 © ELTASK.COM. All rights reserved.
Site is optimized for mobile devices.
Downloads: 1282 / . Delta: 0.04836 с