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  *     &lt;service android:name=".MyChooserTargetService"
48  *             android:label="&#64;string/service_name"
49  *             android:permission="android.permission.BIND_CHOOSER_TARGET_SERVICE">
50  *         &lt;intent-filter>
51  *             &lt;action android:name="android.service.chooser.ChooserTargetService" />
52  *         &lt;/intent-filter>
53  *     &lt;/service>
54  * </pre>
55  *
56  * <p>For the system to query your service, you must add a &lt;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  *     &lt;activity android:name=".MyShareActivity"
67  *             android:label="&#64;string/share_activity_label">
68  *         &lt;intent-filter>
69  *             &lt;action android:name="android.intent.action.SEND" />
70  *         &lt;/intent-filter>
71  *         &lt;meta-data android:name="android.service.chooser.chooser_target_service"
72  *                 android:value=".MyChooserTargetService" />
73  *     &lt;/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