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 * @deprecated For publishing direct share targets, please follow the instructions in 77 * https://developer.android.com/training/sharing/receive.html#providing-direct-share-targets 78 * instead. 79 */ 80 81 @Deprecated 82 public abstract class ChooserTargetService extends Service { 83 // TAG = "ChooserTargetService[MySubclass]"; 84 private final String TAG = ChooserTargetService.class.getSimpleName() 85 + '[' + getClass().getSimpleName() + ']'; 86 87 private static final boolean DEBUG = false; 88 89 /** 90 * The Intent action that a ChooserTargetService must respond to 91 */ 92 @SdkConstant(SdkConstant.SdkConstantType.SERVICE_ACTION) 93 public static final String SERVICE_INTERFACE = "android.service.chooser.ChooserTargetService"; 94 95 /** 96 * The name of the <code>meta-data</code> element that must be present on an 97 * <code>activity</code> element in a manifest to link it to a ChooserTargetService 98 */ 99 public static final String META_DATA_NAME = "android.service.chooser.chooser_target_service"; 100 101 /** 102 * The permission that a ChooserTargetService must require in order to bind to it. 103 * If this permission is not enforced the system will skip that ChooserTargetService. 104 */ 105 public static final String BIND_PERMISSION = "android.permission.BIND_CHOOSER_TARGET_SERVICE"; 106 107 private IChooserTargetServiceWrapper mWrapper = null; 108 109 /** 110 * Called by the system to retrieve a set of deep-link {@link ChooserTarget targets} that 111 * can handle an intent. 112 * 113 * <p>The returned list should be sorted such that the most relevant targets appear first. 114 * The score for each ChooserTarget will be combined with the system's score for the original 115 * target Activity to sort and filter targets presented to the user.</p> 116 * 117 * <p><em>Important:</em> Calls to this method from other applications will occur on 118 * a binder thread, not on your app's main thread. Make sure that access to relevant data 119 * within your app is thread-safe.</p> 120 * 121 * @param targetActivityName the ComponentName of the matched activity that referred the system 122 * to this ChooserTargetService 123 * @param matchedFilter the specific IntentFilter on the component that was matched 124 * @return a list of deep-link targets to fulfill the intent match, sorted by relevance 125 */ onGetChooserTargets(ComponentName targetActivityName, IntentFilter matchedFilter)126 public abstract List<ChooserTarget> onGetChooserTargets(ComponentName targetActivityName, 127 IntentFilter matchedFilter); 128 129 @Override onBind(Intent intent)130 public IBinder onBind(Intent intent) { 131 if (DEBUG) Log.d(TAG, "onBind " + intent); 132 if (!SERVICE_INTERFACE.equals(intent.getAction())) { 133 if (DEBUG) Log.d(TAG, "bad intent action " + intent.getAction() + "; returning null"); 134 return null; 135 } 136 137 if (mWrapper == null) { 138 mWrapper = new IChooserTargetServiceWrapper(); 139 } 140 return mWrapper; 141 } 142 143 private class IChooserTargetServiceWrapper extends IChooserTargetService.Stub { 144 @Override getChooserTargets(ComponentName targetComponentName, IntentFilter matchedFilter, IChooserTargetResult result)145 public void getChooserTargets(ComponentName targetComponentName, 146 IntentFilter matchedFilter, IChooserTargetResult result) throws RemoteException { 147 List<ChooserTarget> targets = null; 148 final long id = clearCallingIdentity(); 149 try { 150 if (DEBUG) { 151 Log.d(TAG, "getChooserTargets calling onGetChooserTargets; " 152 + targetComponentName + " filter: " + matchedFilter); 153 } 154 targets = onGetChooserTargets(targetComponentName, matchedFilter); 155 } finally { 156 restoreCallingIdentity(id); 157 result.sendResult(targets); 158 if (DEBUG) Log.d(TAG, "Sent results"); 159 } 160 } 161 } 162 } 163