1/*
2 * Copyright (C) 2009 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
17package android.accessibilityservice;
18
19import android.app.Service;
20import android.content.Intent;
21import android.os.IBinder;
22import android.os.Message;
23import android.os.RemoteException;
24import android.util.Log;
25import android.view.accessibility.AccessibilityEvent;
26import android.view.accessibility.AccessibilityInteractionClient;
27import android.view.accessibility.AccessibilityNodeInfo;
28
29import com.android.internal.os.HandlerCaller;
30
31/**
32 * An accessibility service runs in the background and receives callbacks by the system
33 * when {@link AccessibilityEvent}s are fired. Such events denote some state transition
34 * in the user interface, for example, the focus has changed, a button has been clicked,
35 * etc. Such a service can optionally request the capability for querying the content
36 * of the active window. Development of an accessibility service requires extending this
37 * class and implementing its abstract methods.
38 * <h3>Lifecycle</h3>
39 * <p>
40 * The lifecycle of an accessibility service is managed exclusively by the system and
41 * follows the established service life cycle. Additionally, starting or stopping an
42 * accessibility service is triggered exclusively by an explicit user action through
43 * enabling or disabling it in the device settings. After the system binds to a service it
44 * calls {@link AccessibilityService#onServiceConnected()}. This method can be
45 * overriden by clients that want to perform post binding setup.
46 * </p>
47 * <h3>Declaration</h3>
48 * <p>
49 * An accessibility is declared as any other service in an AndroidManifest.xml but it
50 * must also specify that it handles the "android.accessibilityservice.AccessibilityService"
51 * {@link android.content.Intent}. Failure to declare this intent will cause the system to
52 * ignore the accessibility service. Following is an example declaration:
53 * </p>
54 * <pre> &lt;service android:name=".MyAccessibilityService"&gt;
55 *     &lt;intent-filter&gt;
56 *         &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;
57 *     &lt;/intent-filter&gt;
58 *     . . .
59 * &lt;/service&gt;</pre>
60 * <h3>Configuration</h3>
61 * <p>
62 * An accessibility service can be configured to receive specific types of accessibility events,
63 * listen only to specific packages, get events from each type only once in a given time frame,
64 * retrieve window content, specify a settings activity, etc.
65 * </p>
66 * <p>
67 * There are two approaches for configuring an accessibility service:
68 * </p>
69 * <ul>
70 * <li>
71 * Providing a {@link #SERVICE_META_DATA meta-data} entry in the manifest when declaring
72 * the service. A service declaration with a meta-data tag is presented below:
73 * <pre> &lt;service android:name=".MyAccessibilityService"&gt;
74 *     &lt;intent-filter&gt;
75 *         &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;
76 *     &lt;/intent-filter&gt;
77 *     &lt;meta-data android:name="android.accessibilityservice" android:resource="@xml/accessibilityservice" /&gt;
78 * &lt;/service&gt;</pre>
79 * <p class="note">
80 * <strong>Note:</strong> This approach enables setting all properties.
81 * </p>
82 * <p>
83 * For more details refer to {@link #SERVICE_META_DATA} and
84 * <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>.
85 * </p>
86 * </li>
87 * <li>
88 * Calling {@link AccessibilityService#setServiceInfo(AccessibilityServiceInfo)}. Note
89 * that this method can be called any time to dynamically change the service configuration.
90 * <p class="note">
91 * <strong>Note:</strong> This approach enables setting only dynamically configurable properties:
92 * {@link AccessibilityServiceInfo#eventTypes},
93 * {@link AccessibilityServiceInfo#feedbackType},
94 * {@link AccessibilityServiceInfo#flags},
95 * {@link AccessibilityServiceInfo#notificationTimeout},
96 * {@link AccessibilityServiceInfo#packageNames}
97 * </p>
98 * <p>
99 * For more details refer to {@link AccessibilityServiceInfo}.
100 * </p>
101 * </li>
102 * </ul>
103 * <h3>Retrieving window content</h3>
104 * <p>
105 * An service can specify in its declaration that it can retrieve the active window
106 * content which is represented as a tree of {@link AccessibilityNodeInfo}. Note that
107 * declaring this capability requires that the service declares its configuration via
108 * an XML resource referenced by {@link #SERVICE_META_DATA}.
109 * </p>
110 * <p>
111 * For security purposes an accessibility service can retrieve only the content of the
112 * currently active window. The currently active window is defined as the window from
113 * which was fired the last event of the following types:
114 * {@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED},
115 * {@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER},
116 * {@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT},
117 * In other words, the last window that was shown or the last window that the user has touched
118 * during touch exploration.
119 * </p>
120 * <p>
121 * The entry point for retrieving window content is through calling
122 * {@link AccessibilityEvent#getSource() AccessibilityEvent.getSource()} of the last received
123 * event of the above types or a previous event from the same window
124 * (see {@link AccessibilityEvent#getWindowId() AccessibilityEvent.getWindowId()}). Invoking
125 * this method will return an {@link AccessibilityNodeInfo} that can be used to traverse the
126 * window content which represented as a tree of such objects.
127 * </p>
128 * <p class="note">
129 * <strong>Note</strong> An accessibility service may have requested to be notified for
130 * a subset of the event types, thus be unaware that the active window has changed. Therefore
131 * accessibility service that would like to retrieve window content should:
132 * <ul>
133 * <li>
134 * Register for all event types with no notification timeout and keep track for the active
135 * window by calling {@link AccessibilityEvent#getWindowId()} of the last received event and
136 * compare this with the {@link AccessibilityNodeInfo#getWindowId()} before calling retrieval
137 * methods on the latter.
138 * </li>
139 * <li>
140 * Prepare that a retrieval method on {@link AccessibilityNodeInfo} may fail since the
141 * active window has changed and the service did not get the accessibility event yet. Note
142 * that it is possible to have a retrieval method failing even adopting the strategy
143 * specified in the previous bullet because the accessibility event dispatch is asynchronous
144 * and crosses process boundaries.
145 * </li>
146 * </ul>
147 * </p>
148 * <h3>Notification strategy</h3>
149 * <p>
150 * For each feedback type only one accessibility service is notified. Services are notified
151 * in the order of registration. Hence, if two services are registered for the same
152 * feedback type in the same package the first one wins. It is possible however, to
153 * register a service as the default one for a given feedback type. In such a case this
154 * service is invoked if no other service was interested in the event. In other words, default
155 * services do not compete with other services and are notified last regardless of the
156 * registration order. This enables "generic" accessibility services that work reasonably
157 * well with most applications to coexist with "polished" ones that are targeted for
158 * specific applications.
159 * </p>
160 * <p class="note">
161 * <strong>Note:</strong> The event notification timeout is useful to avoid propagating
162 * events to the client too frequently since this is accomplished via an expensive
163 * interprocess call. One can think of the timeout as a criteria to determine when
164 * event generation has settled down.</p>
165 * <h3>Event types</h3>
166 * <ul>
167 * <li>{@link AccessibilityEvent#TYPE_VIEW_CLICKED}
168 * <li>{@link AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}
169 * <li>{@link AccessibilityEvent#TYPE_VIEW_FOCUSED}
170 * <li>{@link AccessibilityEvent#TYPE_VIEW_SELECTED}
171 * <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED}
172 * <li>{@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED}
173 * <li>{@link AccessibilityEvent#TYPE_NOTIFICATION_STATE_CHANGED}
174 * <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_START}
175 * <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_END}
176 * <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}
177 * <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}
178 * <li>{@link AccessibilityEvent#TYPE_VIEW_SCROLLED}
179 * <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_SELECTION_CHANGED}
180 * <li>{@link AccessibilityEvent#TYPE_WINDOW_CONTENT_CHANGED}
181 * </ul>
182 * <h3>Feedback types</h3>
183 * <ul>
184 * <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}
185 * <li>{@link AccessibilityServiceInfo#FEEDBACK_HAPTIC}
186 * <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}
187 * <li>{@link AccessibilityServiceInfo#FEEDBACK_VISUAL}
188 * <li>{@link AccessibilityServiceInfo#FEEDBACK_GENERIC}
189 * </ul>
190 * @see AccessibilityEvent
191 * @see AccessibilityServiceInfo
192 * @see android.view.accessibility.AccessibilityManager
193 */
194public abstract class AccessibilityService extends Service {
195    /**
196     * The {@link Intent} that must be declared as handled by the service.
197     */
198    public static final String SERVICE_INTERFACE =
199        "android.accessibilityservice.AccessibilityService";
200
201    /**
202     * Name under which an AccessibilityService component publishes information
203     * about itself. This meta-data must reference an XML resource containing an
204     * <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>
205     * tag. This is a a sample XML file configuring an accessibility service:
206     * <pre> &lt;accessibility-service
207     *     android:accessibilityEventTypes="typeViewClicked|typeViewFocused"
208     *     android:packageNames="foo.bar, foo.baz"
209     *     android:accessibilityFeedbackType="feedbackSpoken"
210     *     android:notificationTimeout="100"
211     *     android:accessibilityFlags="flagDefault"
212     *     android:settingsActivity="foo.bar.TestBackActivity"
213     *     android:canRetrieveWindowContent="true"
214     *     . . .
215     * /&gt;</pre>
216     */
217    public static final String SERVICE_META_DATA = "android.accessibilityservice";
218
219    private static final String LOG_TAG = "AccessibilityService";
220
221    private AccessibilityServiceInfo mInfo;
222
223    private int mConnectionId;
224
225    /**
226     * Callback for {@link android.view.accessibility.AccessibilityEvent}s.
227     *
228     * @param event An event.
229     */
230    public abstract void onAccessibilityEvent(AccessibilityEvent event);
231
232    /**
233     * Callback for interrupting the accessibility feedback.
234     */
235    public abstract void onInterrupt();
236
237    /**
238     * This method is a part of the {@link AccessibilityService} lifecycle and is
239     * called after the system has successfully bound to the service. If is
240     * convenient to use this method for setting the {@link AccessibilityServiceInfo}.
241     *
242     * @see AccessibilityServiceInfo
243     * @see #setServiceInfo(AccessibilityServiceInfo)
244     */
245    protected void onServiceConnected() {
246
247    }
248
249    /**
250     * Sets the {@link AccessibilityServiceInfo} that describes this service.
251     * <p>
252     * Note: You can call this method any time but the info will be picked up after
253     *       the system has bound to this service and when this method is called thereafter.
254     *
255     * @param info The info.
256     */
257    public final void setServiceInfo(AccessibilityServiceInfo info) {
258        mInfo = info;
259        sendServiceInfo();
260    }
261
262    /**
263     * Sets the {@link AccessibilityServiceInfo} for this service if the latter is
264     * properly set and there is an {@link IAccessibilityServiceConnection} to the
265     * AccessibilityManagerService.
266     */
267    private void sendServiceInfo() {
268        IAccessibilityServiceConnection connection =
269            AccessibilityInteractionClient.getInstance().getConnection(mConnectionId);
270        if (mInfo != null && connection != null) {
271            try {
272                connection.setServiceInfo(mInfo);
273            } catch (RemoteException re) {
274                Log.w(LOG_TAG, "Error while setting AccessibilityServiceInfo", re);
275            }
276        }
277    }
278
279    /**
280     * Implement to return the implementation of the internal accessibility
281     * service interface.
282     */
283    @Override
284    public final IBinder onBind(Intent intent) {
285        return new IEventListenerWrapper(this);
286    }
287
288    /**
289     * Implements the internal {@link IEventListener} interface to convert
290     * incoming calls to it back to calls on an {@link AccessibilityService}.
291     */
292    class IEventListenerWrapper extends IEventListener.Stub
293            implements HandlerCaller.Callback {
294
295        private static final int DO_SET_SET_CONNECTION = 10;
296        private static final int DO_ON_INTERRUPT = 20;
297        private static final int DO_ON_ACCESSIBILITY_EVENT = 30;
298
299        private final HandlerCaller mCaller;
300
301        private final AccessibilityService mTarget;
302
303        public IEventListenerWrapper(AccessibilityService context) {
304            mTarget = context;
305            mCaller = new HandlerCaller(context, this);
306        }
307
308        public void setConnection(IAccessibilityServiceConnection connection, int connectionId) {
309            Message message = mCaller.obtainMessageIO(DO_SET_SET_CONNECTION, connectionId,
310                    connection);
311            mCaller.sendMessage(message);
312        }
313
314        public void onInterrupt() {
315            Message message = mCaller.obtainMessage(DO_ON_INTERRUPT);
316            mCaller.sendMessage(message);
317        }
318
319        public void onAccessibilityEvent(AccessibilityEvent event) {
320            Message message = mCaller.obtainMessageO(DO_ON_ACCESSIBILITY_EVENT, event);
321            mCaller.sendMessage(message);
322        }
323
324        public void executeMessage(Message message) {
325            switch (message.what) {
326                case DO_ON_ACCESSIBILITY_EVENT :
327                    AccessibilityEvent event = (AccessibilityEvent) message.obj;
328                    if (event != null) {
329                        mTarget.onAccessibilityEvent(event);
330                        event.recycle();
331                    }
332                    return;
333                case DO_ON_INTERRUPT :
334                    mTarget.onInterrupt();
335                    return;
336                case DO_SET_SET_CONNECTION :
337                    final int connectionId = message.arg1;
338                    IAccessibilityServiceConnection connection =
339                        (IAccessibilityServiceConnection) message.obj;
340                    if (connection != null) {
341                        AccessibilityInteractionClient.getInstance().addConnection(connectionId,
342                                connection);
343                        mConnectionId = connectionId;
344                        mTarget.onServiceConnected();
345                    } else {
346                        AccessibilityInteractionClient.getInstance().removeConnection(connectionId);
347                        mConnectionId = AccessibilityInteractionClient.NO_ID;
348                        // TODO: Do we need a onServiceDisconnected callback?
349                    }
350                    return;
351                default :
352                    Log.w(LOG_TAG, "Unknown message type " + message.what);
353            }
354        }
355    }
356}
357