1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.location; 18 19 import android.annotation.NonNull; 20 import android.os.Bundle; 21 22 import java.util.List; 23 import java.util.concurrent.Executor; 24 25 /** 26 * Used for receiving notifications when the device location has changed. These methods are called 27 * when the listener has been registered with the LocationManager. 28 * 29 * <div class="special reference"> 30 * <h3>Developer Guides</h3> 31 * <p>For more information about identifying user location, read the 32 * <a href="{@docRoot}guide/topics/location/obtaining-user-location.html">Obtaining User 33 * Location</a> developer guide.</p> 34 * </div> 35 * 36 * @see LocationManager#requestLocationUpdates(String, LocationRequest, Executor, LocationListener) 37 */ 38 public interface LocationListener { 39 40 /** 41 * Called when the location has changed. A wakelock may be held on behalf on the listener for 42 * some brief amount of time as this callback executes. If this callback performs long running 43 * operations, it is the client's responsibility to obtain their own wakelock if necessary. 44 * 45 * @param location the updated location 46 */ onLocationChanged(@onNull Location location)47 void onLocationChanged(@NonNull Location location); 48 49 /** 50 * Called when the location has changed and locations are being delivered in batches. The 51 * default implementation calls through to {@link #onLocationChanged(Location)} with all 52 * locations in the batch. The list of locations is always guaranteed to be non-empty, and is 53 * always guaranteed to be ordered from earliest location to latest location (so that the 54 * earliest location in the batch is at index 0 in the list, and the latest location in the 55 * batch is at index size-1 in the list). 56 * 57 * @see LocationRequest#getMaxUpdateDelayMillis() 58 * @param locations the location list 59 */ onLocationChanged(@onNull List<Location> locations)60 default void onLocationChanged(@NonNull List<Location> locations) { 61 final int size = locations.size(); 62 for (int i = 0; i < size; i++) { 63 onLocationChanged(locations.get(i)); 64 } 65 } 66 67 /** 68 * Invoked when a flush operation is complete and after flushed locations have been delivered. 69 * 70 * @param requestCode the request code passed into 71 * {@link LocationManager#requestFlush(String, LocationListener, int)} 72 */ onFlushComplete(int requestCode)73 default void onFlushComplete(int requestCode) {} 74 75 /** 76 * This callback will never be invoked on Android Q and above, and providers can be considered 77 * as always in the {@link LocationProvider#AVAILABLE} state. 78 * 79 * <p class="note">Note that this method only has a default implementation on Android R and 80 * above, and this method must still be overridden in order to run successfully on Android 81 * versions below R. LocationListenerCompat from the compat libraries may be used to avoid the 82 * need to override for older platforms. 83 * 84 * @deprecated This callback will never be invoked on Android Q and above. 85 */ 86 @Deprecated onStatusChanged(String provider, int status, Bundle extras)87 default void onStatusChanged(String provider, int status, Bundle extras) {} 88 89 /** 90 * Called when a provider this listener is registered with becomes enabled. 91 * 92 * <p class="note">Note that this method only has a default implementation on Android R and 93 * above, and this method must still be overridden in order to run successfully on Android 94 * versions below R. LocationListenerCompat from the compat libraries may be used to avoid the 95 * need to override for older platforms. 96 * 97 * @param provider the name of the location provider 98 */ onProviderEnabled(@onNull String provider)99 default void onProviderEnabled(@NonNull String provider) {} 100 101 /** 102 * Called when the provider this listener is registered with becomes disabled. If a provider is 103 * disabled when this listener is registered, this callback will be invoked immediately. 104 * 105 * <p class="note">Note that this method only has a default implementation on Android R and 106 * above, and this method must still be overridden in order to run successfully on Android 107 * versions below R. LocationListenerCompat from the compat libraries may be used to avoid the 108 * need to override for older platforms. 109 * 110 * @param provider the name of the location provider 111 */ onProviderDisabled(@onNull String provider)112 default void onProviderDisabled(@NonNull String provider) {} 113 } 114