1 /* 2 * Copyright (C) 2015 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 18 package android.service.chooser; 19 20 import android.annotation.SdkConstant; 21 import android.app.Service; 22 import android.content.ComponentName; 23 import android.content.Intent; 24 import android.content.IntentFilter; 25 import android.os.IBinder; 26 import android.os.RemoteException; 27 import android.util.Log; 28 29 import java.util.List; 30 31 /** 32 * A service that receives calls from the system when the user is asked to choose 33 * a target for an intent explicitly by another app. The calling app must have invoked 34 * {@link android.content.Intent#ACTION_CHOOSER ACTION_CHOOSER} as handled by the system; 35 * applications do not have the ability to query a ChooserTargetService directly. 36 * 37 * <p>Which ChooserTargetServices are queried depends on a system-level policy decision 38 * made at the moment the chooser is invoked, including but not limited to user time 39 * spent with the app package or associated components in the foreground, recency of usage 40 * or frequency of usage. These will generally correlate with the order that app targets 41 * are shown in the list of intent handlers shown in the system chooser or resolver.</p> 42 * 43 * <p>To extend this class, you must declare the service in your manifest file with 44 * the {@link android.Manifest.permission#BIND_CHOOSER_TARGET_SERVICE} permission 45 * and include an intent filter with the {@link #SERVICE_INTERFACE} action. For example:</p> 46 * <pre> 47 * <service android:name=".MyChooserTargetService" 48 * android:label="@string/service_name" 49 * android:permission="android.permission.BIND_CHOOSER_TARGET_SERVICE"> 50 * <intent-filter> 51 * <action android:name="android.service.chooser.ChooserTargetService" /> 52 * </intent-filter> 53 * </service> 54 * </pre> 55 * 56 * <p>For the system to query your service, you must add a <meta-data> element to the 57 * Activity in your manifest that can handle Intents that you would also like to provide 58 * optional deep links for. For example, a chat app might offer deep links to recent active 59 * conversations instead of invoking a generic picker after the app itself is chosen as a target. 60 * </p> 61 * 62 * <p>The meta-data element should have the name 63 * <code>android.service.chooser.chooser_target_service</code> and a value corresponding to 64 * the component name of your service. Example:</p> 65 * <pre> 66 * <activity android:name=".MyShareActivity" 67 * android:label="@string/share_activity_label"> 68 * <intent-filter> 69 * <action android:name="android.intent.action.SEND" /> 70 * </intent-filter> 71 * <meta-data android:name="android.service.chooser.chooser_target_service" 72 * android:value=".MyChooserTargetService" /> 73 * </activity> 74 * </pre> 75 */ 76 public abstract class ChooserTargetService extends Service { 77 // TAG = "ChooserTargetService[MySubclass]"; 78 private final String TAG = ChooserTargetService.class.getSimpleName() 79 + '[' + getClass().getSimpleName() + ']'; 80 81 private static final boolean DEBUG = false; 82 83 /** 84 * The Intent action that a ChooserTargetService must respond to 85 */ 86 @SdkConstant(SdkConstant.SdkConstantType.SERVICE_ACTION) 87 public static final String SERVICE_INTERFACE = "android.service.chooser.ChooserTargetService"; 88 89 /** 90 * The name of the <code>meta-data</code> element that must be present on an 91 * <code>activity</code> element in a manifest to link it to a ChooserTargetService 92 */ 93 public static final String META_DATA_NAME = "android.service.chooser.chooser_target_service"; 94 95 /** 96 * The permission that a ChooserTargetService must require in order to bind to it. 97 * If this permission is not enforced the system will skip that ChooserTargetService. 98 */ 99 public static final String BIND_PERMISSION = "android.permission.BIND_CHOOSER_TARGET_SERVICE"; 100 101 private IChooserTargetServiceWrapper mWrapper = null; 102 103 /** 104 * Called by the system to retrieve a set of deep-link {@link ChooserTarget targets} that 105 * can handle an intent. 106 * 107 * <p>The returned list should be sorted such that the most relevant targets appear first. 108 * The score for each ChooserTarget will be combined with the system's score for the original 109 * target Activity to sort and filter targets presented to the user.</p> 110 * 111 * <p><em>Important:</em> Calls to this method from other applications will occur on 112 * a binder thread, not on your app's main thread. Make sure that access to relevant data 113 * within your app is thread-safe.</p> 114 * 115 * @param targetActivityName the ComponentName of the matched activity that referred the system 116 * to this ChooserTargetService 117 * @param matchedFilter the specific IntentFilter on the component that was matched 118 * @return a list of deep-link targets to fulfill the intent match, sorted by relevance 119 */ onGetChooserTargets(ComponentName targetActivityName, IntentFilter matchedFilter)120 public abstract List<ChooserTarget> onGetChooserTargets(ComponentName targetActivityName, 121 IntentFilter matchedFilter); 122 123 @Override onBind(Intent intent)124 public IBinder onBind(Intent intent) { 125 if (DEBUG) Log.d(TAG, "onBind " + intent); 126 if (!SERVICE_INTERFACE.equals(intent.getAction())) { 127 if (DEBUG) Log.d(TAG, "bad intent action " + intent.getAction() + "; returning null"); 128 return null; 129 } 130 131 if (mWrapper == null) { 132 mWrapper = new IChooserTargetServiceWrapper(); 133 } 134 return mWrapper; 135 } 136 137 private class IChooserTargetServiceWrapper extends IChooserTargetService.Stub { 138 @Override getChooserTargets(ComponentName targetComponentName, IntentFilter matchedFilter, IChooserTargetResult result)139 public void getChooserTargets(ComponentName targetComponentName, 140 IntentFilter matchedFilter, IChooserTargetResult result) throws RemoteException { 141 List<ChooserTarget> targets = null; 142 final long id = clearCallingIdentity(); 143 try { 144 if (DEBUG) { 145 Log.d(TAG, "getChooserTargets calling onGetChooserTargets; " 146 + targetComponentName + " filter: " + matchedFilter); 147 } 148 targets = onGetChooserTargets(targetComponentName, matchedFilter); 149 } finally { 150 restoreCallingIdentity(id); 151 result.sendResult(targets); 152 if (DEBUG) Log.d(TAG, "Sent results"); 153 } 154 } 155 } 156 } 157