1 /* 2 * Copyright (C) 2017 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.companion; 18 19 20 import static com.android.internal.util.Preconditions.checkNotNull; 21 22 import android.annotation.NonNull; 23 import android.annotation.Nullable; 24 import android.annotation.SystemService; 25 import android.app.Activity; 26 import android.app.Application; 27 import android.app.PendingIntent; 28 import android.content.ComponentName; 29 import android.content.Context; 30 import android.content.IntentSender; 31 import android.content.pm.PackageManager; 32 import android.os.Bundle; 33 import android.os.Handler; 34 import android.os.RemoteException; 35 import android.service.notification.NotificationListenerService; 36 import android.util.Log; 37 38 import java.util.Collections; 39 import java.util.List; 40 import java.util.function.BiConsumer; 41 42 /** 43 * System level service for managing companion devices 44 * 45 * <p>To obtain an instance call {@link Context#getSystemService}({@link 46 * Context#COMPANION_DEVICE_SERVICE}) Then, call {@link #associate(AssociationRequest, 47 * Callback, Handler)} to initiate the flow of associating current package with a 48 * device selected by user.</p> 49 * 50 * @see AssociationRequest 51 */ 52 @SystemService(Context.COMPANION_DEVICE_SERVICE) 53 public final class CompanionDeviceManager { 54 55 private static final boolean DEBUG = false; 56 private static final String LOG_TAG = "CompanionDeviceManager"; 57 58 /** 59 * A device, returned in the activity result of the {@link IntentSender} received in 60 * {@link Callback#onDeviceFound} 61 */ 62 public static final String EXTRA_DEVICE = "android.companion.extra.DEVICE"; 63 64 /** 65 * The package name of the companion device discovery component. 66 * 67 * @hide 68 */ 69 public static final String COMPANION_DEVICE_DISCOVERY_PACKAGE_NAME = 70 "com.android.companiondevicemanager"; 71 72 /** 73 * A callback to receive once at least one suitable device is found, or the search failed 74 * (e.g. timed out) 75 */ 76 public abstract static class Callback { 77 78 /** 79 * Called once at least one suitable device is found 80 * 81 * @param chooserLauncher a {@link IntentSender} to launch the UI for user to select a 82 * device 83 */ 84 public abstract void onDeviceFound(IntentSender chooserLauncher); 85 86 /** 87 * Called if there was an error looking for device(s) 88 * 89 * @param error the cause of the error 90 */ 91 public abstract void onFailure(CharSequence error); 92 } 93 94 private final ICompanionDeviceManager mService; 95 private final Context mContext; 96 97 /** @hide */ 98 public CompanionDeviceManager( 99 @Nullable ICompanionDeviceManager service, @NonNull Context context) { 100 mService = service; 101 mContext = context; 102 } 103 104 /** 105 * Associate this app with a companion device, selected by user 106 * 107 * <p>Once at least one appropriate device is found, {@code callback} will be called with a 108 * {@link PendingIntent} that can be used to show the list of available devices for the user 109 * to select. 110 * It should be started for result (i.e. using 111 * {@link android.app.Activity#startIntentSenderForResult}), as the resulting 112 * {@link android.content.Intent} will contain extra {@link #EXTRA_DEVICE}, with the selected 113 * device. (e.g. {@link android.bluetooth.BluetoothDevice})</p> 114 * 115 * <p>If your app needs to be excluded from battery optimizations (run in the background) 116 * or to have unrestricted data access (use data in the background) you can declare that 117 * you use the {@link android.Manifest.permission#REQUEST_COMPANION_RUN_IN_BACKGROUND} and {@link 118 * android.Manifest.permission#REQUEST_COMPANION_USE_DATA_IN_BACKGROUND} respectively. Note that these 119 * special capabilities have a negative effect on the device's battery and user's data 120 * usage, therefore you should requested them when absolutely necessary.</p> 121 * 122 * <p>You can call {@link #getAssociations} to get the list of currently associated 123 * devices, and {@link #disassociate} to remove an association. Consider doing so when the 124 * association is no longer relevant to avoid unnecessary battery and/or data drain resulting 125 * from special privileges that the association provides</p> 126 * 127 * <p>Calling this API requires a uses-feature 128 * {@link PackageManager#FEATURE_COMPANION_DEVICE_SETUP} declaration in the manifest</p> 129 * 130 * @param request specific details about this request 131 * @param callback will be called once there's at least one device found for user to choose from 132 * @param handler A handler to control which thread the callback will be delivered on, or null, 133 * to deliver it on main thread 134 * 135 * @see AssociationRequest 136 */ 137 public void associate( 138 @NonNull AssociationRequest request, 139 @NonNull Callback callback, 140 @Nullable Handler handler) { 141 if (!checkFeaturePresent()) { 142 return; 143 } 144 checkNotNull(request, "Request cannot be null"); 145 checkNotNull(callback, "Callback cannot be null"); 146 try { 147 mService.associate( 148 request, 149 new CallbackProxy(request, callback, Handler.mainIfNull(handler)), 150 getCallingPackage()); 151 } catch (RemoteException e) { 152 throw e.rethrowFromSystemServer(); 153 } 154 } 155 156 /** 157 * <p>Calling this API requires a uses-feature 158 * {@link PackageManager#FEATURE_COMPANION_DEVICE_SETUP} declaration in the manifest</p> 159 * 160 * @return a list of MAC addresses of devices that have been previously associated with the 161 * current app. You can use these with {@link #disassociate} 162 */ 163 @NonNull 164 public List<String> getAssociations() { 165 if (!checkFeaturePresent()) { 166 return Collections.emptyList(); 167 } 168 try { 169 return mService.getAssociations(getCallingPackage(), mContext.getUserId()); 170 } catch (RemoteException e) { 171 throw e.rethrowFromSystemServer(); 172 } 173 } 174 175 /** 176 * Remove the association between this app and the device with the given mac address. 177 * 178 * <p>Any privileges provided via being associated with a given device will be revoked</p> 179 * 180 * <p>Consider doing so when the 181 * association is no longer relevant to avoid unnecessary battery and/or data drain resulting 182 * from special privileges that the association provides</p> 183 * 184 * <p>Calling this API requires a uses-feature 185 * {@link PackageManager#FEATURE_COMPANION_DEVICE_SETUP} declaration in the manifest</p> 186 * 187 * @param deviceMacAddress the MAC address of device to disassociate from this app 188 */ 189 public void disassociate(@NonNull String deviceMacAddress) { 190 if (!checkFeaturePresent()) { 191 return; 192 } 193 try { 194 mService.disassociate(deviceMacAddress, getCallingPackage()); 195 } catch (RemoteException e) { 196 throw e.rethrowFromSystemServer(); 197 } 198 } 199 200 /** 201 * Request notification access for the given component. 202 * 203 * The given component must follow the protocol specified in {@link NotificationListenerService} 204 * 205 * Only components from the same {@link ComponentName#getPackageName package} as the calling app 206 * are allowed. 207 * 208 * Your app must have an association with a device before calling this API 209 * 210 * <p>Calling this API requires a uses-feature 211 * {@link PackageManager#FEATURE_COMPANION_DEVICE_SETUP} declaration in the manifest</p> 212 */ 213 public void requestNotificationAccess(ComponentName component) { 214 if (!checkFeaturePresent()) { 215 return; 216 } 217 try { 218 IntentSender intentSender = mService.requestNotificationAccess(component) 219 .getIntentSender(); 220 mContext.startIntentSender(intentSender, null, 0, 0, 0); 221 } catch (RemoteException e) { 222 throw e.rethrowFromSystemServer(); 223 } catch (IntentSender.SendIntentException e) { 224 throw new RuntimeException(e); 225 } 226 } 227 228 /** 229 * Check whether the given component can access the notifications via a 230 * {@link NotificationListenerService} 231 * 232 * Your app must have an association with a device before calling this API 233 * 234 * <p>Calling this API requires a uses-feature 235 * {@link PackageManager#FEATURE_COMPANION_DEVICE_SETUP} declaration in the manifest</p> 236 * 237 * @param component the name of the component 238 * @return whether the given component has the notification listener permission 239 */ 240 public boolean hasNotificationAccess(ComponentName component) { 241 if (!checkFeaturePresent()) { 242 return false; 243 } 244 try { 245 return mService.hasNotificationAccess(component); 246 } catch (RemoteException e) { 247 throw e.rethrowFromSystemServer(); 248 } 249 } 250 251 private boolean checkFeaturePresent() { 252 boolean featurePresent = mService != null; 253 if (!featurePresent && DEBUG) { 254 Log.d(LOG_TAG, "Feature " + PackageManager.FEATURE_COMPANION_DEVICE_SETUP 255 + " not available"); 256 } 257 return featurePresent; 258 } 259 260 private Activity getActivity() { 261 return (Activity) mContext; 262 } 263 264 private String getCallingPackage() { 265 return mContext.getPackageName(); 266 } 267 268 private class CallbackProxy extends IFindDeviceCallback.Stub 269 implements Application.ActivityLifecycleCallbacks { 270 271 private Callback mCallback; 272 private Handler mHandler; 273 private AssociationRequest mRequest; 274 275 final Object mLock = new Object(); 276 277 private CallbackProxy(AssociationRequest request, Callback callback, Handler handler) { 278 mCallback = callback; 279 mHandler = handler; 280 mRequest = request; 281 getActivity().getApplication().registerActivityLifecycleCallbacks(this); 282 } 283 284 @Override 285 public void onSuccess(PendingIntent launcher) { 286 lockAndPost(Callback::onDeviceFound, launcher.getIntentSender()); 287 } 288 289 @Override 290 public void onFailure(CharSequence reason) { 291 lockAndPost(Callback::onFailure, reason); 292 } 293 294 <T> void lockAndPost(BiConsumer<Callback, T> action, T payload) { 295 synchronized (mLock) { 296 if (mHandler != null) { 297 mHandler.post(() -> { 298 Callback callback = null; 299 synchronized (mLock) { 300 callback = mCallback; 301 } 302 if (callback != null) { 303 action.accept(callback, payload); 304 } 305 }); 306 } 307 } 308 } 309 310 @Override 311 public void onActivityDestroyed(Activity activity) { 312 synchronized (mLock) { 313 if (activity != getActivity()) return; 314 try { 315 mService.stopScan(mRequest, this, getCallingPackage()); 316 } catch (RemoteException e) { 317 e.rethrowFromSystemServer(); 318 } 319 getActivity().getApplication().unregisterActivityLifecycleCallbacks(this); 320 mCallback = null; 321 mHandler = null; 322 mRequest = null; 323 } 324 } 325 326 @Override public void onActivityCreated(Activity activity, Bundle savedInstanceState) {} 327 @Override public void onActivityStarted(Activity activity) {} 328 @Override public void onActivityResumed(Activity activity) {} 329 @Override public void onActivityPaused(Activity activity) {} 330 @Override public void onActivityStopped(Activity activity) {} 331 @Override public void onActivitySaveInstanceState(Activity activity, Bundle outState) {} 332 } 333 } 334
