16fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly/* 26fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * Copyright (C) 2012 The Android Open Source Project 36fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * 46fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * Licensed under the Apache License, Version 2.0 (the "License"); 56fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * you may not use this file except in compliance with the License. 66fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * You may obtain a copy of the License at 76fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * 86fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * http://www.apache.org/licenses/LICENSE-2.0 96fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * 106fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * Unless required by applicable law or agreed to in writing, software 116fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * distributed under the License is distributed on an "AS IS" BASIS, 126fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 136fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * See the License for the specific language governing permissions and 146fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly * limitations under the License. 156fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly */ 166fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 176fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pellypackage android.location; 186fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 196fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pellyimport android.os.Parcel; 206fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pellyimport android.os.Parcelable; 216fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pellyimport android.os.SystemClock; 226fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pellyimport android.util.TimeUtils; 236fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 244e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 254e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly/** 264e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * A data object that contains quality of service parameters for requests 274e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * to the {@link LocationManager}. 284e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 294e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>LocationRequest objects are used to request a quality of service 304e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * for location updates from the Location Manager. 314e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 324e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>For example, if your application wants high accuracy location 334e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * it should create a location request with {@link #setQuality} set to 344e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * {@link #ACCURACY_FINE} or {@link #POWER_HIGH}, and it should set 354e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * {@link #setInterval} to less than one second. This would be 364e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * appropriate for mapping applications that are showing your location 374e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * in real-time. 384e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 394e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>At the other extreme, if you want negligible power 404e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * impact, but to still receive location updates when available, then use 414e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * {@link #setQuality} with {@link #POWER_NONE}. With this request your 424e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * application will not trigger (and therefore will not receive any 434e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * power blame) any location updates, but will receive locations 444e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * triggered by other applications. This would be appropriate for 454e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * applications that have no firm requirement for location, but can 464e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * take advantage when available. 474e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 484e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>In between these two extremes is a very common use-case, where 494e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * applications definitely want to receive 504e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * updates at a specified interval, and can receive them faster when 514e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * available, but still want a low power impact. These applications 524e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * should consider {@link #POWER_LOW} combined with a faster 534e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * {@link #setFastestInterval} (such as 1 minute) and a slower 544e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * {@link #setInterval} (such as 60 minutes). They will only be assigned 554e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * power blame for the interval set by {@link #setInterval}, but can 564e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * still receive locations triggered by other applications at a rate up 574e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * to {@link #setFastestInterval}. This style of request is appropriate for 584e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * many location aware applications, including background usage. Do be 594e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * careful to also throttle {@link #setFastestInterval} if you perform 604e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * heavy-weight work after receiving an update - such as using the network. 614e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 624e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>Activities should strongly consider removing all location 634e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * request when entering the background 644e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * (for example at {@link android.app.Activity#onPause}), or 654e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * at least swap the request to a larger interval and lower quality. 664e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Future version of the location manager may automatically perform background 674e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * throttling on behalf of applications. 684e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 694e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>Applications cannot specify the exact location sources that are 704e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * used by Android's <em>Fusion Engine</em>. In fact, the system 714e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * may have multiple location sources (providers) running and may 724e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * fuse the results from several sources into a single Location object. 734e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 744e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>Location requests from applications with 754e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} and not 764e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * {@link android.Manifest.permission#ACCESS_FINE_LOCATION} will 774e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * be automatically throttled to a slower interval, and the location 784e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * object will be obfuscated to only show a coarse level of accuracy. 794e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 804e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>All location requests are considered hints, and you may receive 814e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * locations that are more accurate, less accurate, and slower 824e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * than requested. 837ab7f538924371a9dd4be7a27a6ae3b4c04b301cLaurent Tu * 847ab7f538924371a9dd4be7a27a6ae3b4c04b301cLaurent Tu * @hide 854e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 866fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pellypublic final class LocationRequest implements Parcelable { 874e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 884e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Used with {@link #setQuality} to request the most accurate locations available. 894e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 904e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>This may be up to 1 meter accuracy, although this is implementation dependent. 914e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 924e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly public static final int ACCURACY_FINE = 100; 934e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 944e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 954e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Used with {@link #setQuality} to request "block" level accuracy. 964e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 974e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>Block level accuracy is considered to be about 100 meter accuracy, 984e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * although this is implementation dependent. Using a coarse accuracy 994e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * such as this often consumes less power. 1004e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 1014e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly public static final int ACCURACY_BLOCK = 102; 1024e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 1034e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 1044e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Used with {@link #setQuality} to request "city" level accuracy. 1054e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 1064e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>City level accuracy is considered to be about 10km accuracy, 1074e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * although this is implementation dependent. Using a coarse accuracy 1084e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * such as this often consumes less power. 1094e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 1104e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly public static final int ACCURACY_CITY = 104; 1114e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 1124e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 1134e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Used with {@link #setQuality} to require no direct power impact (passive locations). 1144e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 1154e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>This location request will not trigger any active location requests, 1164e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * but will receive locations triggered by other applications. Your application 1174e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * will not receive any direct power blame for location work. 1184e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 1196fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static final int POWER_NONE = 200; 1204e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 1214e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 1224e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Used with {@link #setQuality} to request low power impact. 1234e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 1244e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>This location request will avoid high power location work where 1254e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * possible. 1264e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 1276fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static final int POWER_LOW = 201; 1284e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 1294e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 1304e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Used with {@link #setQuality} to allow high power consumption for location. 1314e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 1324e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>This location request will allow high power location work. 1334e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 1346fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static final int POWER_HIGH = 203; 1356fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 1364e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 1374e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * By default, mFastestInterval = FASTEST_INTERVAL_MULTIPLE * mInterval 1384e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 1394e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly private static final double FASTEST_INTERVAL_FACTOR = 6.0; // 6x 1404e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 1416fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private int mQuality = POWER_LOW; 1424e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly private long mInterval = 60 * 60 * 1000; // 60 minutes 1434e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly private long mFastestInterval = (long)(mInterval / FASTEST_INTERVAL_FACTOR); // 10 minutes 1444e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly private boolean mExplicitFastestInterval = false; 1456fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private long mExpireAt = Long.MAX_VALUE; // no expiry 1466fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private int mNumUpdates = Integer.MAX_VALUE; // no expiry 1476fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private float mSmallestDisplacement = 0.0f; // meters 1486fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 14909016ab4dd056a16809419d612cb865a14980880Victoria Lease private String mProvider = LocationManager.FUSED_PROVIDER; // for deprecated APIs that explicitly request a provider 1506fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 1514e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 1524e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Create a location request with default parameters. 1534e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 1544e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>Default parameters are for a low power, slowly updated location. 1554e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * It can then be adjusted as required by the applications before passing 1564e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * to the {@link LocationManager} 1574e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 1584e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return a new location request 1594e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 1606fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static LocationRequest create() { 1616fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly LocationRequest request = new LocationRequest(); 1626fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return request; 1636fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1646fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 1656fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** @hide */ 1666fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static LocationRequest createFromDeprecatedProvider(String provider, long minTime, 1676fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly float minDistance, boolean singleShot) { 1686fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (minTime < 0) minTime = 0; 1696fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (minDistance < 0) minDistance = 0; 1706fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 1716fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly int quality; 1726fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (LocationManager.PASSIVE_PROVIDER.equals(provider)) { 1736fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly quality = POWER_NONE; 1746fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } else if (LocationManager.GPS_PROVIDER.equals(provider)) { 1756fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly quality = ACCURACY_FINE; 1766fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } else { 1776fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly quality = POWER_LOW; 1786fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1796fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 1806fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly LocationRequest request = new LocationRequest() 1816fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly .setProvider(provider) 1826fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly .setQuality(quality) 1836fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly .setInterval(minTime) 1846fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly .setFastestInterval(minTime) 1856fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly .setSmallestDisplacement(minDistance); 1866fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (singleShot) request.setNumUpdates(1); 1876fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return request; 1886fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 1896fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 1906fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** @hide */ 1916fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static LocationRequest createFromDeprecatedCriteria(Criteria criteria, long minTime, 1926fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly float minDistance, boolean singleShot) { 1936fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (minTime < 0) minTime = 0; 1946fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (minDistance < 0) minDistance = 0; 1956fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 1966fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly int quality; 1976fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly switch (criteria.getAccuracy()) { 1986fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case Criteria.ACCURACY_COARSE: 1996fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly quality = ACCURACY_BLOCK; 2006fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly break; 2016fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case Criteria.ACCURACY_FINE: 2026fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly quality = ACCURACY_FINE; 2036fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly break; 2046fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly default: { 2056fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly switch (criteria.getPowerRequirement()) { 2066fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case Criteria.POWER_HIGH: 2076fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly quality = POWER_HIGH; 2086fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly default: 2096fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly quality = POWER_LOW; 2106fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 2116fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 2126fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 2136fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 2146fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly LocationRequest request = new LocationRequest() 2156fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly .setQuality(quality) 2166fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly .setInterval(minTime) 2176fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly .setFastestInterval(minTime) 2186fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly .setSmallestDisplacement(minDistance); 2196fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (singleShot) request.setNumUpdates(1); 2206fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return request; 2216fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 2226fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 2236fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** @hide */ 2246fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest() { } 2256fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 22637425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease /** @hide */ 22737425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease public LocationRequest(LocationRequest src) { 22837425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease mQuality = src.mQuality; 22937425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease mInterval = src.mInterval; 23037425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease mFastestInterval = src.mFastestInterval; 23137425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease mExplicitFastestInterval = src.mExplicitFastestInterval; 23237425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease mExpireAt = src.mExpireAt; 23337425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease mNumUpdates = src.mNumUpdates; 23437425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease mSmallestDisplacement = src.mSmallestDisplacement; 23537425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease mProvider = src.mProvider; 23637425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease } 23737425c3475877f2fdadb78f669ec57fecf82dca7Victoria Lease 2384e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 2394e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Set the quality of the request. 2404e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2414e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>Use with a accuracy constant such as {@link #ACCURACY_FINE}, or a power 2424e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * constant such as {@link #POWER_LOW}. You cannot request both and accuracy and 2434e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * power, only one or the other can be specified. The system will then 2444e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * maximize accuracy or minimize power as appropriate. 2454e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2464e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>The quality of the request is a strong hint to the system for which 2474e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * location sources to use. For example, {@link #ACCURACY_FINE} is more likely 2484e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * to use GPS, and {@link #POWER_LOW} is more likely to use WIFI & Cell tower 2494e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * positioning, but it also depends on many other factors (such as which sources 2504e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * are available) and is implementation dependent. 2514e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2524e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>{@link #setQuality} and {@link #setInterval} are the most important parameters 2534e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * on a location request. 2544e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2554e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @param quality an accuracy or power constant 2564e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @throws InvalidArgumentException if the quality constant is not valid 2574e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return the same object, so that setters can be chained 2584e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 2596fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest setQuality(int quality) { 2606fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly checkQuality(quality); 2616fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly mQuality = quality; 2626fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return this; 2636fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 2646fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 2654e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 2664e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Get the quality of the request. 2674e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2684e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return an accuracy or power constant 2694e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 2706fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public int getQuality() { 2716fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mQuality; 2726fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 2736fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 2744e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 2754e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Set the desired interval for active location updates, in milliseconds. 2764e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2774e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>The location manager will actively try to obtain location updates 2784e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * for your application at this interval, so it has a 2794e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * direct influence on the amount of power used by your application. 2804e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Choose your interval wisely. 2814e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2824e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>This interval is inexact. You may not receive updates at all (if 2834e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * no location sources are available), or you may receive them 2844e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * slower than requested. You may also receive them faster than 2854e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * requested (if other applications are requesting location at a 2864e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * faster interval). The fastest rate that that you will receive 2874e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * updates can be controlled with {@link #setFastestInterval}. 2884e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2894e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>Applications with only the coarse location permission may have their 2904e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * interval silently throttled. 2914e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2924e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>An interval of 0 is allowed, but not recommended, since 2934e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * location updates may be extremely fast on future implementations. 2944e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2954e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>{@link #setQuality} and {@link #setInterval} are the most important parameters 2964e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * on a location request. 2974e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 2984e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @param millis desired interval in millisecond, inexact 2994e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @throws InvalidArgumentException if the interval is less than zero 3004e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return the same object, so that setters can be chained 3014e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 3026fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest setInterval(long millis) { 3036fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly checkInterval(millis); 3046fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly mInterval = millis; 3054e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly if (!mExplicitFastestInterval) { 3064e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly mFastestInterval = (long)(mInterval / FASTEST_INTERVAL_FACTOR); 3074e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly } 3086fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return this; 3096fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 3106fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 3114e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 3124e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Get the desired interval of this request, in milliseconds. 3134e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3144e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return desired interval in milliseconds, inexact 3154e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 3166fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public long getInterval() { 3176fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mInterval; 3186fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 3196fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 3204e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 3214e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Explicitly set the fastest interval for location updates, in 3224e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * milliseconds. 3234e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3244e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>This controls the fastest rate at which your application will 3254e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * receive location updates, which might be faster than 3264e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * {@link #setInterval} in some situations (for example, if other 3274e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * applications are triggering location updates). 3284e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3294e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>This allows your application to passively acquire locations 3304e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * at a rate faster than it actively acquires locations, saving power. 3314e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3324e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>Unlike {@link #setInterval}, this parameter is exact. Your 3334e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * application will never receive updates faster than this value. 3344e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3354e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>If you don't call this method, a fastest interval 3364e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * will be selected for you. It will be a value faster than your 3374e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * active interval ({@link #setInterval}). 3384e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3394e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>An interval of 0 is allowed, but not recommended, since 3404e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * location updates may be extremely fast on future implementations. 3414e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3424e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>If {@link #setFastestInterval} is set slower than {@link #setInterval}, 3434e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * then your effective fastest interval is {@link #setInterval}. 3444e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3454e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @param millis fastest interval for updates in milliseconds, exact 3464e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @throws InvalidArgumentException if the interval is less than zero 3474e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return the same object, so that setters can be chained 3484e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 3496fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest setFastestInterval(long millis) { 3506fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly checkInterval(millis); 3514e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly mExplicitFastestInterval = true; 3526fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly mFastestInterval = millis; 3536fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return this; 3546fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 3556fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 3564e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 3574e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Get the fastest interval of this request, in milliseconds. 3584e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3594e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>The system will never provide location updates faster 3604e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * than the minimum of {@link #getFastestInterval} and 3614e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * {@link #getInterval}. 3624e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3634e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return fastest interval in milliseconds, exact 3644e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 3656fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public long getFastestInterval() { 3666fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mFastestInterval; 3676fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 3686fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 3694e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 3704e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Set the duration of this request, in milliseconds. 3714e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3724e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>The duration begins immediately (and not when the request 3734e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * is passed to the location manager), so call this method again 3744e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * if the request is re-used at a later time. 3754e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3764e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>The location manager will automatically stop updates after 3774e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * the request expires. 3784e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3794e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>The duration includes suspend time. Values less than 0 3804e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * are allowed, but indicate that the request has already expired. 3814e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 3824e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @param millis duration of request in milliseconds 3834e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return the same object, so that setters can be chained 3844e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 3856fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest setExpireIn(long millis) { 386e72fe16146dd33cb218bf8c16b069f68f331fdf8Laurent Tu long elapsedRealtime = SystemClock.elapsedRealtime(); 387e72fe16146dd33cb218bf8c16b069f68f331fdf8Laurent Tu 388e72fe16146dd33cb218bf8c16b069f68f331fdf8Laurent Tu // Check for > Long.MAX_VALUE overflow (elapsedRealtime > 0): 389e72fe16146dd33cb218bf8c16b069f68f331fdf8Laurent Tu if (millis > Long.MAX_VALUE - elapsedRealtime) { 390e72fe16146dd33cb218bf8c16b069f68f331fdf8Laurent Tu mExpireAt = Long.MAX_VALUE; 391e72fe16146dd33cb218bf8c16b069f68f331fdf8Laurent Tu } else { 392e72fe16146dd33cb218bf8c16b069f68f331fdf8Laurent Tu mExpireAt = millis + elapsedRealtime; 393e72fe16146dd33cb218bf8c16b069f68f331fdf8Laurent Tu } 394e72fe16146dd33cb218bf8c16b069f68f331fdf8Laurent Tu 3956fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (mExpireAt < 0) mExpireAt = 0; 3966fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return this; 3976fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 3986fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 3994e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 4004e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Set the request expiration time, in millisecond since boot. 4014e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 4024e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>This expiration time uses the same time base as {@link SystemClock#elapsedRealtime}. 4034e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 4044e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>The location manager will automatically stop updates after 4054e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * the request expires. 4064e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 4074e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>The duration includes suspend time. Values before {@link SystemClock#elapsedRealtime} 4084e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * are allowed, but indicate that the request has already expired. 4094e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 4104e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @param millis expiration time of request, in milliseconds since boot including suspend 4114e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return the same object, so that setters can be chained 4124e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 4136fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest setExpireAt(long millis) { 4146fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly mExpireAt = millis; 4156fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (mExpireAt < 0) mExpireAt = 0; 4166fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return this; 4176fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4186fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 4194e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 4204e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Get the request expiration time, in milliseconds since boot. 4214e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 4224e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>This value can be compared to {@link SystemClock#elapsedRealtime} to determine 4234e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * the time until expiration. 4244e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 4254e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return expiration time of request, in milliseconds since boot including suspend 4264e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 4276fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public long getExpireAt() { 4286fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mExpireAt; 4296fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4306fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 4314e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 4324e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Set the number of location updates. 4334e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 4344e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>By default locations are continuously updated until the request is explicitly 4354e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * removed, however you can optionally request a set number of updates. 4364e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * For example, if your application only needs a single fresh location, 4374e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * then call this method with a value of 1 before passing the request 4384e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * to the location manager. 4394e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 4404e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @param numUpdates the number of location updates requested 4414e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @throws InvalidArgumentException if numUpdates is 0 or less 4424e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return the same object, so that setters can be chained 4434e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 4444e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly public LocationRequest setNumUpdates(int numUpdates) { 4454e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly if (numUpdates <= 0) throw new IllegalArgumentException("invalid numUpdates: " + numUpdates); 4464e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly mNumUpdates = numUpdates; 4474e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly return this; 4484e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly } 4494e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 4504e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly /** 4514e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * Get the number of updates requested. 4524e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * 4534e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * <p>By default this is {@link Integer#MAX_VALUE}, which indicates that 4544e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * locations are updated until the request is explicitly removed. 4554e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly * @return number of updates 4564e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly */ 4576fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public int getNumUpdates() { 4586fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mNumUpdates; 4596fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4606fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 4616fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** @hide */ 4626fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public void decrementNumUpdates() { 4636fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (mNumUpdates != Integer.MAX_VALUE) { 4646fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly mNumUpdates--; 4656fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4666fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (mNumUpdates < 0) { 4676fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly mNumUpdates = 0; 4686fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4696fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4706fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 4716fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 4726fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** @hide */ 4736fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest setProvider(String provider) { 4746fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly checkProvider(provider); 4756fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly mProvider = provider; 4766fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return this; 4776fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4786fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 4796fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** @hide */ 4806fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public String getProvider() { 4816fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mProvider; 4826fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4836fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 4846fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** @hide */ 4856fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest setSmallestDisplacement(float meters) { 4866fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly checkDisplacement(meters); 4876fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly mSmallestDisplacement = meters; 4886fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return this; 4896fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4906fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 4916fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** @hide */ 4926fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public float getSmallestDisplacement() { 4936fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return mSmallestDisplacement; 4946fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 4956fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 4966fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private static void checkInterval(long millis) { 4976fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (millis < 0) { 4986fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly throw new IllegalArgumentException("invalid interval: " + millis); 4996fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5006fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5016fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 5026fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private static void checkQuality(int quality) { 5036fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly switch (quality) { 5046fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case ACCURACY_FINE: 5056fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case ACCURACY_BLOCK: 5066fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case ACCURACY_CITY: 5076fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case POWER_NONE: 5086fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case POWER_LOW: 5096fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case POWER_HIGH: 5106fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly break; 5116fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly default: 5126fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly throw new IllegalArgumentException("invalid quality: " + quality); 5136fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5146fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5156fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 5166fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private static void checkDisplacement(float meters) { 5176fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (meters < 0.0f) { 5186fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly throw new IllegalArgumentException("invalid displacement: " + meters); 5196fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5206fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5216fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 5226fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly private static void checkProvider(String name) { 5236fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (name == null) { 5246fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly throw new IllegalArgumentException("invalid provider: " + name); 5256fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5266fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5276fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 5286fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static final Parcelable.Creator<LocationRequest> CREATOR = 5296fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly new Parcelable.Creator<LocationRequest>() { 5306fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly @Override 5316fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest createFromParcel(Parcel in) { 5326fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly LocationRequest request = new LocationRequest(); 5336fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly request.setQuality(in.readInt()); 5346fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly request.setFastestInterval(in.readLong()); 5356fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly request.setInterval(in.readLong()); 5366fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly request.setExpireAt(in.readLong()); 5376fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly request.setNumUpdates(in.readInt()); 5386fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly request.setSmallestDisplacement(in.readFloat()); 5396fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly String provider = in.readString(); 5406fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (provider != null) request.setProvider(provider); 5416fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return request; 5426fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5436fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly @Override 5446fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public LocationRequest[] newArray(int size) { 5456fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return new LocationRequest[size]; 5466fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5476fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly }; 5484e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 5496fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly @Override 5506fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public int describeContents() { 5516fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return 0; 5526fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5534e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4Nick Pelly 5546fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly @Override 5556fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public void writeToParcel(Parcel parcel, int flags) { 5566fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly parcel.writeInt(mQuality); 5576fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly parcel.writeLong(mFastestInterval); 5586fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly parcel.writeLong(mInterval); 5596fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly parcel.writeLong(mExpireAt); 5606fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly parcel.writeInt(mNumUpdates); 5616fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly parcel.writeFloat(mSmallestDisplacement); 5626fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly parcel.writeString(mProvider); 5636fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5646fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 5656fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly /** @hide */ 5666fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public static String qualityToString(int quality) { 5676fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly switch (quality) { 5686fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case ACCURACY_FINE: 5696fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return "ACCURACY_FINE"; 5706fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case ACCURACY_BLOCK: 5716fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return "ACCURACY_BLOCK"; 5726fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case ACCURACY_CITY: 5736fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return "ACCURACY_CITY"; 5746fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case POWER_NONE: 5756fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return "POWER_NONE"; 5766fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case POWER_LOW: 5776fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return "POWER_LOW"; 5786fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly case POWER_HIGH: 5796fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return "POWER_HIGH"; 5806fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly default: 5816fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return "???"; 5826fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5836fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5846fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly 5856fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly @Override 5866fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly public String toString() { 5876fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly StringBuilder s = new StringBuilder(); 5886fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly s.append("Request[").append(qualityToString(mQuality)); 5896fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (mProvider != null) s.append(' ').append(mProvider); 5906fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (mQuality != POWER_NONE) { 5916fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly s.append(" requested="); 5926fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly TimeUtils.formatDuration(mInterval, s); 5936fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 5946fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly s.append(" fastest="); 5956fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly TimeUtils.formatDuration(mFastestInterval, s); 5966fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (mExpireAt != Long.MAX_VALUE) { 5976fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly long expireIn = mExpireAt - SystemClock.elapsedRealtime(); 5986fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly s.append(" expireIn="); 5996fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly TimeUtils.formatDuration(expireIn, s); 6006fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 6016fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly if (mNumUpdates != Integer.MAX_VALUE){ 6026fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly s.append(" num=").append(mNumUpdates); 6036fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 6046fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly s.append(']'); 6056fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly return s.toString(); 6066fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly } 6076fa9ad4afcd762aea519ff61811386c23d18ddb2Nick Pelly} 608