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