1 /* 2 * Copyright (C) 2010 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 com.android.location.provider; 18 19 import java.io.FileDescriptor; 20 import java.io.FileOutputStream; 21 import java.io.PrintWriter; 22 23 import android.content.Context; 24 import android.location.ILocationManager; 25 import android.location.Location; 26 import android.location.LocationManager; 27 import android.os.Bundle; 28 import android.os.IBinder; 29 import android.os.RemoteException; 30 import android.os.ServiceManager; 31 import android.os.WorkSource; 32 import android.util.Log; 33 34 import com.android.internal.location.ILocationProvider; 35 import com.android.internal.location.ProviderProperties; 36 import com.android.internal.location.ProviderRequest; 37 import com.android.internal.util.FastPrintWriter; 38 39 /** 40 * Base class for location providers implemented as unbundled services. 41 * 42 * <p>The network location provider must export a service with action 43 * "com.android.location.service.v2.NetworkLocationProvider" 44 * and a valid minor version in a meta-data field on the service, and 45 * then return the result of {@link #getBinder()} on service binding. 46 * 47 * <p>The fused location provider must export a service with action 48 * "com.android.location.service.FusedLocationProvider" 49 * and a valid minor version in a meta-data field on the service, and 50 * then return the result of {@link #getBinder()} on service binding. 51 * 52 * <p>IMPORTANT: This class is effectively a public API for unbundled 53 * applications, and must remain API stable. See README.txt in the root 54 * of this package for more information. 55 */ 56 public abstract class LocationProviderBase { 57 private final String TAG; 58 59 protected final ILocationManager mLocationManager; 60 private final ProviderProperties mProperties; 61 private final IBinder mBinder; 62 63 /** 64 * Bundle key for a version of the location containing no GPS data. 65 * Allows location providers to flag locations as being safe to 66 * feed to LocationFudger. 67 */ 68 public static final String EXTRA_NO_GPS_LOCATION = Location.EXTRA_NO_GPS_LOCATION; 69 70 /** 71 * Name of the Fused location provider. 72 * 73 * <p>This provider combines inputs for all possible location sources 74 * to provide the best possible Location fix. 75 */ 76 public static final String FUSED_PROVIDER = LocationManager.FUSED_PROVIDER; 77 78 private final class Service extends ILocationProvider.Stub { 79 @Override enable()80 public void enable() { 81 onEnable(); 82 } 83 @Override disable()84 public void disable() { 85 onDisable(); 86 } 87 @Override setRequest(ProviderRequest request, WorkSource ws)88 public void setRequest(ProviderRequest request, WorkSource ws) { 89 onSetRequest(new ProviderRequestUnbundled(request), ws); 90 } 91 @Override getProperties()92 public ProviderProperties getProperties() { 93 return mProperties; 94 } 95 @Override getStatus(Bundle extras)96 public int getStatus(Bundle extras) { 97 return onGetStatus(extras); 98 } 99 @Override getStatusUpdateTime()100 public long getStatusUpdateTime() { 101 return onGetStatusUpdateTime(); 102 } 103 @Override sendExtraCommand(String command, Bundle extras)104 public boolean sendExtraCommand(String command, Bundle extras) { 105 return onSendExtraCommand(command, extras); 106 } 107 @Override dump(FileDescriptor fd, String[] args)108 public void dump(FileDescriptor fd, String[] args) { 109 PrintWriter pw = new FastPrintWriter(new FileOutputStream(fd)); 110 onDump(fd, pw, args); 111 pw.flush(); 112 } 113 } 114 LocationProviderBase(String tag, ProviderPropertiesUnbundled properties)115 public LocationProviderBase(String tag, ProviderPropertiesUnbundled properties) { 116 TAG = tag; 117 IBinder b = ServiceManager.getService(Context.LOCATION_SERVICE); 118 mLocationManager = ILocationManager.Stub.asInterface(b); 119 mProperties = properties.getProviderProperties(); 120 mBinder = new Service(); 121 } 122 getBinder()123 public IBinder getBinder() { 124 return mBinder; 125 } 126 127 /** 128 * Used by the location provider to report new locations. 129 * 130 * @param location new Location to report 131 * 132 * Requires the android.permission.INSTALL_LOCATION_PROVIDER permission. 133 */ reportLocation(Location location)134 public final void reportLocation(Location location) { 135 try { 136 mLocationManager.reportLocation(location, false); 137 } catch (RemoteException e) { 138 Log.e(TAG, "RemoteException", e); 139 } catch (Exception e) { 140 // never crash provider, might be running in a system process 141 Log.e(TAG, "Exception", e); 142 } 143 } 144 145 /** 146 * Enable the location provider. 147 * <p>The provider may initialize resources, but does 148 * not yet need to report locations. 149 */ onEnable()150 public abstract void onEnable(); 151 152 /** 153 * Disable the location provider. 154 * <p>The provider must release resources, and stop 155 * performing work. It may no longer report locations. 156 */ onDisable()157 public abstract void onDisable(); 158 159 /** 160 * Set the {@link ProviderRequest} requirements for this provider. 161 * <p>Each call to this method overrides all previous requests. 162 * <p>This method might trigger the provider to start returning 163 * locations, or to stop returning locations, depending on the 164 * parameters in the request. 165 */ onSetRequest(ProviderRequestUnbundled request, WorkSource source)166 public abstract void onSetRequest(ProviderRequestUnbundled request, WorkSource source); 167 168 /** 169 * Dump debug information. 170 */ onDump(FileDescriptor fd, PrintWriter pw, String[] args)171 public void onDump(FileDescriptor fd, PrintWriter pw, String[] args) { 172 } 173 174 /** 175 * Returns a information on the status of this provider. 176 * <p>{@link android.location.LocationProvider#OUT_OF_SERVICE} is returned if the provider is 177 * out of service, and this is not expected to change in the near 178 * future; {@link android.location.LocationProvider#TEMPORARILY_UNAVAILABLE} is returned if 179 * the provider is temporarily unavailable but is expected to be 180 * available shortly; and {@link android.location.LocationProvider#AVAILABLE} is returned 181 * if the provider is currently available. 182 * 183 * <p>If extras is non-null, additional status information may be 184 * added to it in the form of provider-specific key/value pairs. 185 */ onGetStatus(Bundle extras)186 public abstract int onGetStatus(Bundle extras); 187 188 /** 189 * Returns the time at which the status was last updated. It is the 190 * responsibility of the provider to appropriately set this value using 191 * {@link android.os.SystemClock#elapsedRealtime SystemClock.elapsedRealtime()}. 192 * there is a status update that it wishes to broadcast to all its 193 * listeners. The provider should be careful not to broadcast 194 * the same status again. 195 * 196 * @return time of last status update in millis since last reboot 197 */ onGetStatusUpdateTime()198 public abstract long onGetStatusUpdateTime(); 199 200 /** 201 * Implements addditional location provider specific additional commands. 202 * 203 * @param command name of the command to send to the provider. 204 * @param extras optional arguments for the command (or null). 205 * The provider may optionally fill the extras Bundle with results from the command. 206 * 207 * @return true if the command succeeds. 208 */ onSendExtraCommand(String command, Bundle extras)209 public boolean onSendExtraCommand(String command, Bundle extras) { 210 // default implementation 211 return false; 212 } 213 } 214