AccessibilityService.java revision 4503fcfa2d26091c2a02d610da591e8b7c7b5a9f
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.accessibilityservice.GestureDescription.MotionEventGenerator;
20import android.annotation.IntDef;
21import android.annotation.NonNull;
22import android.annotation.Nullable;
23import android.app.Service;
24import android.content.Context;
25import android.content.Intent;
26import android.content.pm.ParceledListSlice;
27import android.graphics.Region;
28import android.os.Handler;
29import android.os.IBinder;
30import android.os.Looper;
31import android.os.Message;
32import android.os.RemoteException;
33import android.provider.Settings;
34import android.util.ArrayMap;
35import android.util.Log;
36import android.util.Pair;
37import android.util.Slog;
38import android.util.SparseArray;
39import android.view.KeyEvent;
40import android.view.MotionEvent;
41import android.view.WindowManager;
42import android.view.WindowManagerImpl;
43import android.view.accessibility.AccessibilityEvent;
44import android.view.accessibility.AccessibilityInteractionClient;
45import android.view.accessibility.AccessibilityNodeInfo;
46import android.view.accessibility.AccessibilityWindowInfo;
47
48import com.android.internal.os.HandlerCaller;
49import com.android.internal.os.SomeArgs;
50
51import java.lang.annotation.Retention;
52import java.lang.annotation.RetentionPolicy;
53import java.util.List;
54
55/**
56 * Accessibility services are intended to assist users with disabilities in using
57 * Android devices and apps. They run in the background and receive callbacks by the system
58 * when {@link AccessibilityEvent}s are fired. Such events denote some state transition
59 * in the user interface, for example, the focus has changed, a button has been clicked,
60 * etc. Such a service can optionally request the capability for querying the content
61 * of the active window. Development of an accessibility service requires extending this
62 * class and implementing its abstract methods.
63 *
64 * <div class="special reference">
65 * <h3>Developer Guides</h3>
66 * <p>For more information about creating AccessibilityServices, read the
67 * <a href="{@docRoot}guide/topics/ui/accessibility/index.html">Accessibility</a>
68 * developer guide.</p>
69 * </div>
70 *
71 * <h3>Lifecycle</h3>
72 * <p>
73 * The lifecycle of an accessibility service is managed exclusively by the system and
74 * follows the established service life cycle. Starting an accessibility service is triggered
75 * exclusively by the user explicitly turning the service on in device settings. After the system
76 * binds to a service, it calls {@link AccessibilityService#onServiceConnected()}. This method can
77 * be overriden by clients that want to perform post binding setup.
78 * </p>
79 * <p>
80 * An accessibility service stops either when the user turns it off in device settings or when
81 * it calls {@link AccessibilityService#disableSelf()}.
82 * </p>
83 * <h3>Declaration</h3>
84 * <p>
85 * An accessibility is declared as any other service in an AndroidManifest.xml, but it
86 * must do two things:
87 * <ul>
88 *     <ol>
89 *         Specify that it handles the "android.accessibilityservice.AccessibilityService"
90 *         {@link android.content.Intent}.
91 *     </ol>
92 *     <ol>
93 *         Request the {@link android.Manifest.permission#BIND_ACCESSIBILITY_SERVICE} permission to
94 *         ensure that only the system can bind to it.
95 *     </ol>
96 * </ul>
97 * If either of these items is missing, the system will ignore the accessibility service.
98 * Following is an example declaration:
99 * </p>
100 * <pre> &lt;service android:name=".MyAccessibilityService"
101 *         android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"&gt;
102 *     &lt;intent-filter&gt;
103 *         &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;
104 *     &lt;/intent-filter&gt;
105 *     . . .
106 * &lt;/service&gt;</pre>
107 * <h3>Configuration</h3>
108 * <p>
109 * An accessibility service can be configured to receive specific types of accessibility events,
110 * listen only to specific packages, get events from each type only once in a given time frame,
111 * retrieve window content, specify a settings activity, etc.
112 * </p>
113 * <p>
114 * There are two approaches for configuring an accessibility service:
115 * </p>
116 * <ul>
117 * <li>
118 * Providing a {@link #SERVICE_META_DATA meta-data} entry in the manifest when declaring
119 * the service. A service declaration with a meta-data tag is presented below:
120 * <pre> &lt;service android:name=".MyAccessibilityService"&gt;
121 *     &lt;intent-filter&gt;
122 *         &lt;action android:name="android.accessibilityservice.AccessibilityService" /&gt;
123 *     &lt;/intent-filter&gt;
124 *     &lt;meta-data android:name="android.accessibilityservice" android:resource="@xml/accessibilityservice" /&gt;
125 * &lt;/service&gt;</pre>
126 * <p class="note">
127 * <strong>Note:</strong> This approach enables setting all properties.
128 * </p>
129 * <p>
130 * For more details refer to {@link #SERVICE_META_DATA} and
131 * <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>.
132 * </p>
133 * </li>
134 * <li>
135 * Calling {@link AccessibilityService#setServiceInfo(AccessibilityServiceInfo)}. Note
136 * that this method can be called any time to dynamically change the service configuration.
137 * <p class="note">
138 * <strong>Note:</strong> This approach enables setting only dynamically configurable properties:
139 * {@link AccessibilityServiceInfo#eventTypes},
140 * {@link AccessibilityServiceInfo#feedbackType},
141 * {@link AccessibilityServiceInfo#flags},
142 * {@link AccessibilityServiceInfo#notificationTimeout},
143 * {@link AccessibilityServiceInfo#packageNames}
144 * </p>
145 * <p>
146 * For more details refer to {@link AccessibilityServiceInfo}.
147 * </p>
148 * </li>
149 * </ul>
150 * <h3>Retrieving window content</h3>
151 * <p>
152 * A service can specify in its declaration that it can retrieve window
153 * content which is represented as a tree of {@link AccessibilityWindowInfo} and
154 * {@link AccessibilityNodeInfo} objects. Note that
155 * declaring this capability requires that the service declares its configuration via
156 * an XML resource referenced by {@link #SERVICE_META_DATA}.
157 * </p>
158 * <p>
159 * Window content may be retrieved with
160 * {@link AccessibilityEvent#getSource() AccessibilityEvent.getSource()},
161 * {@link AccessibilityService#findFocus(int)},
162 * {@link AccessibilityService#getWindows()}, or
163 * {@link AccessibilityService#getRootInActiveWindow()}.
164 * </p>
165 * <p class="note">
166 * <strong>Note</strong> An accessibility service may have requested to be notified for
167 * a subset of the event types, and thus be unaware when the node hierarchy has changed. It is also
168 * possible for a node to contain outdated information because the window content may change at any
169 * time.
170 * </p>
171 * <h3>Notification strategy</h3>
172 * <p>
173 * All accessibility services are notified of all events they have requested, regardless of their
174 * feedback type.
175 * </p>
176 * <p class="note">
177 * <strong>Note:</strong> The event notification timeout is useful to avoid propagating
178 * events to the client too frequently since this is accomplished via an expensive
179 * interprocess call. One can think of the timeout as a criteria to determine when
180 * event generation has settled down.</p>
181 * <h3>Event types</h3>
182 * <ul>
183 * <li>{@link AccessibilityEvent#TYPE_VIEW_CLICKED}</li>
184 * <li>{@link AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}</li>
185 * <li>{@link AccessibilityEvent#TYPE_VIEW_FOCUSED}</li>
186 * <li>{@link AccessibilityEvent#TYPE_VIEW_SELECTED}</li>
187 * <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED}</li>
188 * <li>{@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED}</li>
189 * <li>{@link AccessibilityEvent#TYPE_NOTIFICATION_STATE_CHANGED}</li>
190 * <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_START}</li>
191 * <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_END}</li>
192 * <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}</li>
193 * <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}</li>
194 * <li>{@link AccessibilityEvent#TYPE_VIEW_SCROLLED}</li>
195 * <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_SELECTION_CHANGED}</li>
196 * <li>{@link AccessibilityEvent#TYPE_WINDOW_CONTENT_CHANGED}</li>
197 * <li>{@link AccessibilityEvent#TYPE_ANNOUNCEMENT}</li>
198 * <li>{@link AccessibilityEvent#TYPE_GESTURE_DETECTION_START}</li>
199 * <li>{@link AccessibilityEvent#TYPE_GESTURE_DETECTION_END}</li>
200 * <li>{@link AccessibilityEvent#TYPE_TOUCH_INTERACTION_START}</li>
201 * <li>{@link AccessibilityEvent#TYPE_TOUCH_INTERACTION_END}</li>
202 * <li>{@link AccessibilityEvent#TYPE_VIEW_ACCESSIBILITY_FOCUSED}</li>
203 * <li>{@link AccessibilityEvent#TYPE_WINDOWS_CHANGED}</li>
204 * <li>{@link AccessibilityEvent#TYPE_VIEW_ACCESSIBILITY_FOCUS_CLEARED}</li>
205 * </ul>
206 * <h3>Feedback types</h3>
207 * <ul>
208 * <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}</li>
209 * <li>{@link AccessibilityServiceInfo#FEEDBACK_HAPTIC}</li>
210 * <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE}</li>
211 * <li>{@link AccessibilityServiceInfo#FEEDBACK_VISUAL}</li>
212 * <li>{@link AccessibilityServiceInfo#FEEDBACK_GENERIC}</li>
213 * <li>{@link AccessibilityServiceInfo#FEEDBACK_BRAILLE}</li>
214 * </ul>
215 * @see AccessibilityEvent
216 * @see AccessibilityServiceInfo
217 * @see android.view.accessibility.AccessibilityManager
218 */
219public abstract class AccessibilityService extends Service {
220
221    /**
222     * The user has performed a swipe up gesture on the touch screen.
223     */
224    public static final int GESTURE_SWIPE_UP = 1;
225
226    /**
227     * The user has performed a swipe down gesture on the touch screen.
228     */
229    public static final int GESTURE_SWIPE_DOWN = 2;
230
231    /**
232     * The user has performed a swipe left gesture on the touch screen.
233     */
234    public static final int GESTURE_SWIPE_LEFT = 3;
235
236    /**
237     * The user has performed a swipe right gesture on the touch screen.
238     */
239    public static final int GESTURE_SWIPE_RIGHT = 4;
240
241    /**
242     * The user has performed a swipe left and right gesture on the touch screen.
243     */
244    public static final int GESTURE_SWIPE_LEFT_AND_RIGHT = 5;
245
246    /**
247     * The user has performed a swipe right and left gesture on the touch screen.
248     */
249    public static final int GESTURE_SWIPE_RIGHT_AND_LEFT = 6;
250
251    /**
252     * The user has performed a swipe up and down gesture on the touch screen.
253     */
254    public static final int GESTURE_SWIPE_UP_AND_DOWN = 7;
255
256    /**
257     * The user has performed a swipe down and up gesture on the touch screen.
258     */
259    public static final int GESTURE_SWIPE_DOWN_AND_UP = 8;
260
261    /**
262     * The user has performed a left and up gesture on the touch screen.
263     */
264    public static final int GESTURE_SWIPE_LEFT_AND_UP = 9;
265
266    /**
267     * The user has performed a left and down gesture on the touch screen.
268     */
269    public static final int GESTURE_SWIPE_LEFT_AND_DOWN = 10;
270
271    /**
272     * The user has performed a right and up gesture on the touch screen.
273     */
274    public static final int GESTURE_SWIPE_RIGHT_AND_UP = 11;
275
276    /**
277     * The user has performed a right and down gesture on the touch screen.
278     */
279    public static final int GESTURE_SWIPE_RIGHT_AND_DOWN = 12;
280
281    /**
282     * The user has performed an up and left gesture on the touch screen.
283     */
284    public static final int GESTURE_SWIPE_UP_AND_LEFT = 13;
285
286    /**
287     * The user has performed an up and right gesture on the touch screen.
288     */
289    public static final int GESTURE_SWIPE_UP_AND_RIGHT = 14;
290
291    /**
292     * The user has performed an down and left gesture on the touch screen.
293     */
294    public static final int GESTURE_SWIPE_DOWN_AND_LEFT = 15;
295
296    /**
297     * The user has performed an down and right gesture on the touch screen.
298     */
299    public static final int GESTURE_SWIPE_DOWN_AND_RIGHT = 16;
300
301    /**
302     * The {@link Intent} that must be declared as handled by the service.
303     */
304    public static final String SERVICE_INTERFACE =
305        "android.accessibilityservice.AccessibilityService";
306
307    /**
308     * Name under which an AccessibilityService component publishes information
309     * about itself. This meta-data must reference an XML resource containing an
310     * <code>&lt;{@link android.R.styleable#AccessibilityService accessibility-service}&gt;</code>
311     * tag. This is a a sample XML file configuring an accessibility service:
312     * <pre> &lt;accessibility-service
313     *     android:accessibilityEventTypes="typeViewClicked|typeViewFocused"
314     *     android:packageNames="foo.bar, foo.baz"
315     *     android:accessibilityFeedbackType="feedbackSpoken"
316     *     android:notificationTimeout="100"
317     *     android:accessibilityFlags="flagDefault"
318     *     android:settingsActivity="foo.bar.TestBackActivity"
319     *     android:canRetrieveWindowContent="true"
320     *     android:canRequestTouchExplorationMode="true"
321     *     . . .
322     * /&gt;</pre>
323     */
324    public static final String SERVICE_META_DATA = "android.accessibilityservice";
325
326    /**
327     * Action to go back.
328     */
329    public static final int GLOBAL_ACTION_BACK = 1;
330
331    /**
332     * Action to go home.
333     */
334    public static final int GLOBAL_ACTION_HOME = 2;
335
336    /**
337     * Action to toggle showing the overview of recent apps
338     */
339    public static final int GLOBAL_ACTION_RECENTS = 3;
340
341    /**
342     * Action to open the notifications.
343     */
344    public static final int GLOBAL_ACTION_NOTIFICATIONS = 4;
345
346    /**
347     * Action to open the quick settings.
348     */
349    public static final int GLOBAL_ACTION_QUICK_SETTINGS = 5;
350
351    /**
352     * Action to open the power long-press dialog.
353     */
354    public static final int GLOBAL_ACTION_POWER_DIALOG = 6;
355
356    /**
357     * Action to toggle docking the current app's window
358     */
359    public static final int GLOBAL_ACTION_TOGGLE_SPLIT_SCREEN = 7;
360
361    private static final String LOG_TAG = "AccessibilityService";
362
363    /**
364     * @hide
365     */
366    public interface Callbacks {
367        public void onAccessibilityEvent(AccessibilityEvent event);
368        public void onInterrupt();
369        public void onServiceConnected();
370        public void init(int connectionId, IBinder windowToken);
371        public boolean onGesture(int gestureId);
372        public boolean onKeyEvent(KeyEvent event);
373        public void onMagnificationChanged(@NonNull Region region,
374                float scale, float centerX, float centerY);
375        public void onSoftKeyboardShowModeChanged(int showMode);
376        public void onPerformGestureResult(int sequence, boolean completedSuccessfully);
377    }
378
379    /**
380     * Annotations for Soft Keyboard show modes so tools can catch invalid show modes.
381     * @hide
382     */
383    @Retention(RetentionPolicy.SOURCE)
384    @IntDef({SHOW_MODE_AUTO, SHOW_MODE_HIDDEN})
385    public @interface SoftKeyboardShowMode {};
386    public static final int SHOW_MODE_AUTO = 0;
387    public static final int SHOW_MODE_HIDDEN = 1;
388
389    private int mConnectionId;
390
391    private AccessibilityServiceInfo mInfo;
392
393    private IBinder mWindowToken;
394
395    private WindowManager mWindowManager;
396
397    private MagnificationController mMagnificationController;
398    private SoftKeyboardController mSoftKeyboardController;
399
400    private int mGestureStatusCallbackSequence;
401
402    private SparseArray<GestureResultCallbackInfo> mGestureStatusCallbackInfos;
403
404    private final Object mLock = new Object();
405
406    /**
407     * Callback for {@link android.view.accessibility.AccessibilityEvent}s.
408     *
409     * @param event An event.
410     */
411    public abstract void onAccessibilityEvent(AccessibilityEvent event);
412
413    /**
414     * Callback for interrupting the accessibility feedback.
415     */
416    public abstract void onInterrupt();
417
418    /**
419     * Dispatches service connection to internal components first, then the
420     * client code.
421     */
422    private void dispatchServiceConnected() {
423        if (mMagnificationController != null) {
424            mMagnificationController.onServiceConnected();
425        }
426
427        // The client gets to handle service connection last, after we've set
428        // up any state upon which their code may rely.
429        onServiceConnected();
430    }
431
432    /**
433     * This method is a part of the {@link AccessibilityService} lifecycle and is
434     * called after the system has successfully bound to the service. If is
435     * convenient to use this method for setting the {@link AccessibilityServiceInfo}.
436     *
437     * @see AccessibilityServiceInfo
438     * @see #setServiceInfo(AccessibilityServiceInfo)
439     */
440    protected void onServiceConnected() {
441
442    }
443
444    /**
445     * Called by the system when the user performs a specific gesture on the
446     * touch screen.
447     *
448     * <strong>Note:</strong> To receive gestures an accessibility service must
449     * request that the device is in touch exploration mode by setting the
450     * {@link android.accessibilityservice.AccessibilityServiceInfo#FLAG_REQUEST_TOUCH_EXPLORATION_MODE}
451     * flag.
452     *
453     * @param gestureId The unique id of the performed gesture.
454     *
455     * @return Whether the gesture was handled.
456     *
457     * @see #GESTURE_SWIPE_UP
458     * @see #GESTURE_SWIPE_UP_AND_LEFT
459     * @see #GESTURE_SWIPE_UP_AND_DOWN
460     * @see #GESTURE_SWIPE_UP_AND_RIGHT
461     * @see #GESTURE_SWIPE_DOWN
462     * @see #GESTURE_SWIPE_DOWN_AND_LEFT
463     * @see #GESTURE_SWIPE_DOWN_AND_UP
464     * @see #GESTURE_SWIPE_DOWN_AND_RIGHT
465     * @see #GESTURE_SWIPE_LEFT
466     * @see #GESTURE_SWIPE_LEFT_AND_UP
467     * @see #GESTURE_SWIPE_LEFT_AND_RIGHT
468     * @see #GESTURE_SWIPE_LEFT_AND_DOWN
469     * @see #GESTURE_SWIPE_RIGHT
470     * @see #GESTURE_SWIPE_RIGHT_AND_UP
471     * @see #GESTURE_SWIPE_RIGHT_AND_LEFT
472     * @see #GESTURE_SWIPE_RIGHT_AND_DOWN
473     */
474    protected boolean onGesture(int gestureId) {
475        return false;
476    }
477
478    /**
479     * Callback that allows an accessibility service to observe the key events
480     * before they are passed to the rest of the system. This means that the events
481     * are first delivered here before they are passed to the device policy, the
482     * input method, or applications.
483     * <p>
484     * <strong>Note:</strong> It is important that key events are handled in such
485     * a way that the event stream that would be passed to the rest of the system
486     * is well-formed. For example, handling the down event but not the up event
487     * and vice versa would generate an inconsistent event stream.
488     * </p>
489     * <p>
490     * <strong>Note:</strong> The key events delivered in this method are copies
491     * and modifying them will have no effect on the events that will be passed
492     * to the system. This method is intended to perform purely filtering
493     * functionality.
494     * <p>
495     *
496     * @param event The event to be processed.
497     * @return If true then the event will be consumed and not delivered to
498     *         applications, otherwise it will be delivered as usual.
499     */
500    protected boolean onKeyEvent(KeyEvent event) {
501        return false;
502    }
503
504    /**
505     * Gets the windows on the screen. This method returns only the windows
506     * that a sighted user can interact with, as opposed to all windows.
507     * For example, if there is a modal dialog shown and the user cannot touch
508     * anything behind it, then only the modal window will be reported
509     * (assuming it is the top one). For convenience the returned windows
510     * are ordered in a descending layer order, which is the windows that
511     * are higher in the Z-order are reported first. Since the user can always
512     * interact with the window that has input focus by typing, the focused
513     * window is always returned (even if covered by a modal window).
514     * <p>
515     * <strong>Note:</strong> In order to access the windows your service has
516     * to declare the capability to retrieve window content by setting the
517     * {@link android.R.styleable#AccessibilityService_canRetrieveWindowContent}
518     * property in its meta-data. For details refer to {@link #SERVICE_META_DATA}.
519     * Also the service has to opt-in to retrieve the interactive windows by
520     * setting the {@link AccessibilityServiceInfo#FLAG_RETRIEVE_INTERACTIVE_WINDOWS}
521     * flag.
522     * </p>
523     *
524     * @return The windows if there are windows and the service is can retrieve
525     *         them, otherwise an empty list.
526     */
527    public List<AccessibilityWindowInfo> getWindows() {
528        return AccessibilityInteractionClient.getInstance().getWindows(mConnectionId);
529    }
530
531    /**
532     * Gets the root node in the currently active window if this service
533     * can retrieve window content. The active window is the one that the user
534     * is currently touching or the window with input focus, if the user is not
535     * touching any window.
536     * <p>
537     * The currently active window is defined as the window that most recently fired one
538     * of the following events:
539     * {@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED},
540     * {@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER},
541     * {@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}.
542     * In other words, the last window shown that also has input focus.
543     * </p>
544     * <p>
545     * <strong>Note:</strong> In order to access the root node your service has
546     * to declare the capability to retrieve window content by setting the
547     * {@link android.R.styleable#AccessibilityService_canRetrieveWindowContent}
548     * property in its meta-data. For details refer to {@link #SERVICE_META_DATA}.
549     * </p>
550     *
551     * @return The root node if this service can retrieve window content.
552     */
553    public AccessibilityNodeInfo getRootInActiveWindow() {
554        return AccessibilityInteractionClient.getInstance().getRootInActiveWindow(mConnectionId);
555    }
556
557    /**
558     * Disables the service. After calling this method, the service will be disabled and settings
559     * will show that it is turned off.
560     */
561    public final void disableSelf() {
562        final IAccessibilityServiceConnection connection =
563                AccessibilityInteractionClient.getInstance().getConnection(mConnectionId);
564        if (connection != null) {
565            try {
566                connection.disableSelf();
567            } catch (RemoteException re) {
568                throw new RuntimeException(re);
569            }
570        }
571    }
572
573    /**
574     * Returns the magnification controller, which may be used to query and
575     * modify the state of display magnification.
576     * <p>
577     * <strong>Note:</strong> In order to control magnification, your service
578     * must declare the capability by setting the
579     * {@link android.R.styleable#AccessibilityService_canControlMagnification}
580     * property in its meta-data. For more information, see
581     * {@link #SERVICE_META_DATA}.
582     *
583     * @return the magnification controller
584     */
585    @NonNull
586    public final MagnificationController getMagnificationController() {
587        synchronized (mLock) {
588            if (mMagnificationController == null) {
589                mMagnificationController = new MagnificationController(this, mLock);
590            }
591            return mMagnificationController;
592        }
593    }
594
595    /**
596     * Dispatch a gesture to the touch screen. Any gestures currently in progress, whether from
597     * the user, this service, or another service, will be cancelled.
598     * <p>
599     * <strong>Note:</strong> In order to dispatch gestures, your service
600     * must declare the capability by setting the
601     * {@link android.R.styleable#AccessibilityService_canPerformGestures}
602     * property in its meta-data. For more information, see
603     * {@link #SERVICE_META_DATA}.
604     *
605     * @param gesture The gesture to dispatch
606     * @param callback The object to call back when the status of the gesture is known. If
607     * {@code null}, no status is reported.
608     * @param handler The handler on which to call back the {@code callback} object. If
609     * {@code null}, the object is called back on the service's main thread.
610     *
611     * @return {@code true} if the gesture is dispatched, {@code false} if not.
612     */
613    public final boolean dispatchGesture(@NonNull GestureDescription gesture,
614            @Nullable GestureResultCallback callback,
615            @Nullable Handler handler) {
616        final IAccessibilityServiceConnection connection =
617                AccessibilityInteractionClient.getInstance().getConnection(
618                        mConnectionId);
619        if (connection == null) {
620            return false;
621        }
622        List<MotionEvent> events = MotionEventGenerator.getMotionEventsFromGestureDescription(
623                gesture, 100);
624        try {
625            synchronized (mLock) {
626                mGestureStatusCallbackSequence++;
627                if (callback != null) {
628                    if (mGestureStatusCallbackInfos == null) {
629                        mGestureStatusCallbackInfos = new SparseArray<>();
630                    }
631                    GestureResultCallbackInfo callbackInfo = new GestureResultCallbackInfo(gesture,
632                            callback, handler);
633                    mGestureStatusCallbackInfos.put(mGestureStatusCallbackSequence, callbackInfo);
634                }
635                connection.sendMotionEvents(mGestureStatusCallbackSequence,
636                        new ParceledListSlice<>(events));
637            }
638        } catch (RemoteException re) {
639            throw new RuntimeException(re);
640        }
641        return true;
642    }
643
644    void onPerformGestureResult(int sequence, final boolean completedSuccessfully) {
645        if (mGestureStatusCallbackInfos == null) {
646            return;
647        }
648        GestureResultCallbackInfo callbackInfo;
649        synchronized (mLock) {
650            callbackInfo = mGestureStatusCallbackInfos.get(sequence);
651        }
652        final GestureResultCallbackInfo finalCallbackInfo = callbackInfo;
653        if ((callbackInfo != null) && (callbackInfo.gestureDescription != null)
654                && (callbackInfo.callback != null)) {
655            if (callbackInfo.handler != null) {
656                callbackInfo.handler.post(new Runnable() {
657                    @Override
658                    public void run() {
659                        if (completedSuccessfully) {
660                            finalCallbackInfo.callback
661                                    .onCompleted(finalCallbackInfo.gestureDescription);
662                        } else {
663                            finalCallbackInfo.callback
664                                    .onCancelled(finalCallbackInfo.gestureDescription);
665                        }
666                    }
667                });
668                return;
669            }
670            if (completedSuccessfully) {
671                callbackInfo.callback.onCompleted(callbackInfo.gestureDescription);
672            } else {
673                callbackInfo.callback.onCancelled(callbackInfo.gestureDescription);
674            }
675        }
676    }
677
678    private void onMagnificationChanged(@NonNull Region region, float scale,
679            float centerX, float centerY) {
680        if (mMagnificationController != null) {
681            mMagnificationController.dispatchMagnificationChanged(
682                    region, scale, centerX, centerY);
683        }
684    }
685
686    /**
687     * Used to control and query the state of display magnification.
688     */
689    public static final class MagnificationController {
690        private final AccessibilityService mService;
691
692        /**
693         * Map of listeners to their handlers. Lazily created when adding the
694         * first magnification listener.
695         */
696        private ArrayMap<OnMagnificationChangedListener, Handler> mListeners;
697        private final Object mLock;
698
699        MagnificationController(@NonNull AccessibilityService service, @NonNull Object lock) {
700            mService = service;
701            mLock = lock;
702        }
703
704        /**
705         * Called when the service is connected.
706         */
707        void onServiceConnected() {
708            synchronized (mLock) {
709                if (mListeners != null && !mListeners.isEmpty()) {
710                    setMagnificationCallbackEnabled(true);
711                }
712            }
713        }
714
715        /**
716         * Adds the specified change listener to the list of magnification
717         * change listeners. The callback will occur on the service's main
718         * thread.
719         *
720         * @param listener the listener to add, must be non-{@code null}
721         */
722        public void addListener(@NonNull OnMagnificationChangedListener listener) {
723            addListener(listener, null);
724        }
725
726        /**
727         * Adds the specified change listener to the list of magnification
728         * change listeners. The callback will occur on the specified
729         * {@link Handler}'s thread, or on the service's main thread if the
730         * handler is {@code null}.
731         *
732         * @param listener the listener to add, must be non-null
733         * @param handler the handler on which the callback should execute, or
734         *        {@code null} to execute on the service's main thread
735         */
736        public void addListener(@NonNull OnMagnificationChangedListener listener,
737                @Nullable Handler handler) {
738            synchronized (mLock) {
739                if (mListeners == null) {
740                    mListeners = new ArrayMap<>();
741                }
742
743                final boolean shouldEnableCallback = mListeners.isEmpty();
744                mListeners.put(listener, handler);
745
746                if (shouldEnableCallback) {
747                    // This may fail if the service is not connected yet, but if we
748                    // still have listeners when it connects then we can try again.
749                    setMagnificationCallbackEnabled(true);
750                }
751            }
752        }
753
754        /**
755         * Removes all instances of the specified change listener from the list
756         * of magnification change listeners.
757         *
758         * @param listener the listener to remove, must be non-null
759         * @return {@code true} if at least one instance of the listener was
760         *         removed
761         */
762        public boolean removeListener(@NonNull OnMagnificationChangedListener listener) {
763            if (mListeners == null) {
764                return false;
765            }
766
767            synchronized (mLock) {
768                final int keyIndex = mListeners.indexOfKey(listener);
769                final boolean hasKey = keyIndex >= 0;
770                if (hasKey) {
771                    mListeners.removeAt(keyIndex);
772                }
773
774                if (hasKey && mListeners.isEmpty()) {
775                    // We just removed the last listener, so we don't need
776                    // callbacks from the service anymore.
777                    setMagnificationCallbackEnabled(false);
778                }
779
780                return hasKey;
781            }
782        }
783
784        private void setMagnificationCallbackEnabled(boolean enabled) {
785            final IAccessibilityServiceConnection connection =
786                    AccessibilityInteractionClient.getInstance().getConnection(
787                            mService.mConnectionId);
788            if (connection != null) {
789                try {
790                    connection.setMagnificationCallbackEnabled(enabled);
791                } catch (RemoteException re) {
792                    throw new RuntimeException(re);
793                }
794            }
795        }
796
797        /**
798         * Dispatches magnification changes to any registered listeners. This
799         * should be called on the service's main thread.
800         */
801        void dispatchMagnificationChanged(final @NonNull Region region, final float scale,
802                final float centerX, final float centerY) {
803            final ArrayMap<OnMagnificationChangedListener, Handler> entries;
804            synchronized (mLock) {
805                if (mListeners == null || mListeners.isEmpty()) {
806                    Slog.d(LOG_TAG, "Received magnification changed "
807                            + "callback with no listeners registered!");
808                    setMagnificationCallbackEnabled(false);
809                    return;
810                }
811
812                // Listeners may remove themselves. Perform a shallow copy to avoid concurrent
813                // modification.
814                entries = new ArrayMap<>(mListeners);
815            }
816
817            for (int i = 0, count = entries.size(); i < count; i++) {
818                final OnMagnificationChangedListener listener = entries.keyAt(i);
819                final Handler handler = entries.valueAt(i);
820                if (handler != null) {
821                    handler.post(new Runnable() {
822                        @Override
823                        public void run() {
824                            listener.onMagnificationChanged(MagnificationController.this,
825                                    region, scale, centerX, centerY);
826                        }
827                    });
828                } else {
829                    // We're already on the main thread, just run the listener.
830                    listener.onMagnificationChanged(this, region, scale, centerX, centerY);
831                }
832            }
833        }
834
835        /**
836         * Returns the current magnification scale.
837         * <p>
838         * <strong>Note:</strong> If the service is not yet connected (e.g.
839         * {@link AccessibilityService#onServiceConnected()} has not yet been
840         * called) or the service has been disconnected, this method will
841         * return a default value of {@code 1.0f}.
842         *
843         * @return the current magnification scale
844         */
845        public float getScale() {
846            final IAccessibilityServiceConnection connection =
847                    AccessibilityInteractionClient.getInstance().getConnection(
848                            mService.mConnectionId);
849            if (connection != null) {
850                try {
851                    return connection.getMagnificationScale();
852                } catch (RemoteException re) {
853                    Log.w(LOG_TAG, "Failed to obtain scale", re);
854                    re.rethrowFromSystemServer();
855                }
856            }
857            return 1.0f;
858        }
859
860        /**
861         * Returns the unscaled screen-relative X coordinate of the focal
862         * center of the magnified region. This is the point around which
863         * zooming occurs and is guaranteed to lie within the magnified
864         * region.
865         * <p>
866         * <strong>Note:</strong> If the service is not yet connected (e.g.
867         * {@link AccessibilityService#onServiceConnected()} has not yet been
868         * called) or the service has been disconnected, this method will
869         * return a default value of {@code 0.0f}.
870         *
871         * @return the unscaled screen-relative X coordinate of the center of
872         *         the magnified region
873         */
874        public float getCenterX() {
875            final IAccessibilityServiceConnection connection =
876                    AccessibilityInteractionClient.getInstance().getConnection(
877                            mService.mConnectionId);
878            if (connection != null) {
879                try {
880                    return connection.getMagnificationCenterX();
881                } catch (RemoteException re) {
882                    Log.w(LOG_TAG, "Failed to obtain center X", re);
883                    re.rethrowFromSystemServer();
884                }
885            }
886            return 0.0f;
887        }
888
889        /**
890         * Returns the unscaled screen-relative Y coordinate of the focal
891         * center of the magnified region. This is the point around which
892         * zooming occurs and is guaranteed to lie within the magnified
893         * region.
894         * <p>
895         * <strong>Note:</strong> If the service is not yet connected (e.g.
896         * {@link AccessibilityService#onServiceConnected()} has not yet been
897         * called) or the service has been disconnected, this method will
898         * return a default value of {@code 0.0f}.
899         *
900         * @return the unscaled screen-relative Y coordinate of the center of
901         *         the magnified region
902         */
903        public float getCenterY() {
904            final IAccessibilityServiceConnection connection =
905                    AccessibilityInteractionClient.getInstance().getConnection(
906                            mService.mConnectionId);
907            if (connection != null) {
908                try {
909                    return connection.getMagnificationCenterY();
910                } catch (RemoteException re) {
911                    Log.w(LOG_TAG, "Failed to obtain center Y", re);
912                    re.rethrowFromSystemServer();
913                }
914            }
915            return 0.0f;
916        }
917
918        /**
919         * Returns the region of the screen currently being magnified. If
920         * magnification is not enabled, the returned region will be empty.
921         * <p>
922         * <strong>Note:</strong> If the service is not yet connected (e.g.
923         * {@link AccessibilityService#onServiceConnected()} has not yet been
924         * called) or the service has been disconnected, this method will
925         * return an empty region.
926         *
927         * @return the screen-relative bounds of the magnified region
928         */
929        @NonNull
930        public Region getMagnifiedRegion() {
931            final IAccessibilityServiceConnection connection =
932                    AccessibilityInteractionClient.getInstance().getConnection(
933                            mService.mConnectionId);
934            if (connection != null) {
935                try {
936                    return connection.getMagnifiedRegion();
937                } catch (RemoteException re) {
938                    Log.w(LOG_TAG, "Failed to obtain magnified region", re);
939                    re.rethrowFromSystemServer();
940                }
941            }
942            return Region.obtain();
943        }
944
945        /**
946         * Resets magnification scale and center to their default (e.g. no
947         * magnification) values.
948         * <p>
949         * <strong>Note:</strong> If the service is not yet connected (e.g.
950         * {@link AccessibilityService#onServiceConnected()} has not yet been
951         * called) or the service has been disconnected, this method will have
952         * no effect and return {@code false}.
953         *
954         * @param animate {@code true} to animate from the current scale and
955         *                center or {@code false} to reset the scale and center
956         *                immediately
957         * @return {@code true} on success, {@code false} on failure
958         */
959        public boolean reset(boolean animate) {
960            final IAccessibilityServiceConnection connection =
961                    AccessibilityInteractionClient.getInstance().getConnection(
962                            mService.mConnectionId);
963            if (connection != null) {
964                try {
965                    return connection.resetMagnification(animate);
966                } catch (RemoteException re) {
967                    Log.w(LOG_TAG, "Failed to reset", re);
968                    re.rethrowFromSystemServer();
969                }
970            }
971            return false;
972        }
973
974        /**
975         * Sets the magnification scale.
976         * <p>
977         * <strong>Note:</strong> If the service is not yet connected (e.g.
978         * {@link AccessibilityService#onServiceConnected()} has not yet been
979         * called) or the service has been disconnected, this method will have
980         * no effect and return {@code false}.
981         *
982         * @param scale the magnification scale to set, must be >= 1 and <= 5
983         * @param animate {@code true} to animate from the current scale or
984         *                {@code false} to set the scale immediately
985         * @return {@code true} on success, {@code false} on failure
986         */
987        public boolean setScale(float scale, boolean animate) {
988            final IAccessibilityServiceConnection connection =
989                    AccessibilityInteractionClient.getInstance().getConnection(
990                            mService.mConnectionId);
991            if (connection != null) {
992                try {
993                    return connection.setMagnificationScaleAndCenter(
994                            scale, Float.NaN, Float.NaN, animate);
995                } catch (RemoteException re) {
996                    Log.w(LOG_TAG, "Failed to set scale", re);
997                    re.rethrowFromSystemServer();
998                }
999            }
1000            return false;
1001        }
1002
1003        /**
1004         * Sets the center of the magnified viewport.
1005         * <p>
1006         * <strong>Note:</strong> If the service is not yet connected (e.g.
1007         * {@link AccessibilityService#onServiceConnected()} has not yet been
1008         * called) or the service has been disconnected, this method will have
1009         * no effect and return {@code false}.
1010         *
1011         * @param centerX the unscaled screen-relative X coordinate on which to
1012         *                center the viewport
1013         * @param centerY the unscaled screen-relative Y coordinate on which to
1014         *                center the viewport
1015         * @param animate {@code true} to animate from the current viewport
1016         *                center or {@code false} to set the center immediately
1017         * @return {@code true} on success, {@code false} on failure
1018         */
1019        public boolean setCenter(float centerX, float centerY, boolean animate) {
1020            final IAccessibilityServiceConnection connection =
1021                    AccessibilityInteractionClient.getInstance().getConnection(
1022                            mService.mConnectionId);
1023            if (connection != null) {
1024                try {
1025                    return connection.setMagnificationScaleAndCenter(
1026                            Float.NaN, centerX, centerY, animate);
1027                } catch (RemoteException re) {
1028                    Log.w(LOG_TAG, "Failed to set center", re);
1029                    re.rethrowFromSystemServer();
1030                }
1031            }
1032            return false;
1033        }
1034
1035        /**
1036         * Listener for changes in the state of magnification.
1037         */
1038        public interface OnMagnificationChangedListener {
1039            /**
1040             * Called when the magnified region, scale, or center changes.
1041             *
1042             * @param controller the magnification controller
1043             * @param region the new magnified region, may be empty if
1044             *               magnification is not enabled (e.g. scale is 1)
1045             * @param scale the new scale
1046             * @param centerX the new X coordinate around which magnification is focused
1047             * @param centerY the new Y coordinate around which magnification is focused
1048             */
1049            void onMagnificationChanged(@NonNull MagnificationController controller,
1050                    @NonNull Region region, float scale, float centerX, float centerY);
1051        }
1052    }
1053
1054    /**
1055     * Returns the soft keyboard controller, which may be used to query and modify the soft keyboard
1056     * show mode.
1057     *
1058     * @return the soft keyboard controller
1059     */
1060    @NonNull
1061    public final SoftKeyboardController getSoftKeyboardController() {
1062        synchronized (mLock) {
1063            if (mSoftKeyboardController == null) {
1064                mSoftKeyboardController = new SoftKeyboardController(this, mLock);
1065            }
1066            return mSoftKeyboardController;
1067        }
1068    }
1069
1070    private void onSoftKeyboardShowModeChanged(int showMode) {
1071        if (mSoftKeyboardController != null) {
1072            mSoftKeyboardController.dispatchSoftKeyboardShowModeChanged(showMode);
1073        }
1074    }
1075
1076    /**
1077     * Used to control and query the soft keyboard show mode.
1078     */
1079    public static final class SoftKeyboardController {
1080        private final AccessibilityService mService;
1081
1082        /**
1083         * Map of listeners to their handlers. Lazily created when adding the first
1084         * soft keyboard change listener.
1085         */
1086        private ArrayMap<OnShowModeChangedListener, Handler> mListeners;
1087        private final Object mLock;
1088
1089        SoftKeyboardController(@NonNull AccessibilityService service, @NonNull Object lock) {
1090            mService = service;
1091            mLock = lock;
1092        }
1093
1094        /**
1095         * Called when the service is connected.
1096         */
1097        void onServiceConnected() {
1098            synchronized(mLock) {
1099                if (mListeners != null && !mListeners.isEmpty()) {
1100                    setSoftKeyboardCallbackEnabled(true);
1101                }
1102            }
1103        }
1104
1105        /**
1106         * Adds the specified change listener to the list of show mode change listeners. The
1107         * callback will occur on the service's main thread. Listener is not called on registration.
1108         */
1109        public void addOnShowModeChangedListener(@NonNull OnShowModeChangedListener listener) {
1110            addOnShowModeChangedListener(listener, null);
1111        }
1112
1113        /**
1114         * Adds the specified change listener to the list of soft keyboard show mode change
1115         * listeners. The callback will occur on the specified {@link Handler}'s thread, or on the
1116         * services's main thread if the handler is {@code null}.
1117         *
1118         * @param listener the listener to add, must be non-null
1119         * @param handler the handler on which to callback should execute, or {@code null} to
1120         *        execute on the service's main thread
1121         */
1122        public void addOnShowModeChangedListener(@NonNull OnShowModeChangedListener listener,
1123                @Nullable Handler handler) {
1124            synchronized (mLock) {
1125                if (mListeners == null) {
1126                    mListeners = new ArrayMap<>();
1127                }
1128
1129                final boolean shouldEnableCallback = mListeners.isEmpty();
1130                mListeners.put(listener, handler);
1131
1132                if (shouldEnableCallback) {
1133                    // This may fail if the service is not connected yet, but if we still have
1134                    // listeners when it connects, we can try again.
1135                    setSoftKeyboardCallbackEnabled(true);
1136                }
1137            }
1138        }
1139
1140        /**
1141         * Removes all instances of the specified change listener from the list of magnification
1142         * change listeners.
1143         *
1144         * @param listener the listener to remove, must be non-null
1145         * @return {@code true} if at least one instance of the listener was removed
1146         */
1147        public boolean removeOnShowModeChangedListener(@NonNull OnShowModeChangedListener listener) {
1148            if (mListeners == null) {
1149                return false;
1150            }
1151
1152            synchronized (mLock) {
1153                final int keyIndex = mListeners.indexOfKey(listener);
1154                final boolean hasKey = keyIndex >= 0;
1155                if (hasKey) {
1156                    mListeners.removeAt(keyIndex);
1157                }
1158
1159                if (hasKey && mListeners.isEmpty()) {
1160                    // We just removed the last listener, so we don't need callbacks from the
1161                    // service anymore.
1162                    setSoftKeyboardCallbackEnabled(false);
1163                }
1164
1165                return hasKey;
1166            }
1167        }
1168
1169        private void setSoftKeyboardCallbackEnabled(boolean enabled) {
1170            final IAccessibilityServiceConnection connection =
1171                    AccessibilityInteractionClient.getInstance().getConnection(
1172                            mService.mConnectionId);
1173            if (connection != null) {
1174                try {
1175                    connection.setSoftKeyboardCallbackEnabled(enabled);
1176                } catch (RemoteException re) {
1177                    throw new RuntimeException(re);
1178                }
1179            }
1180        }
1181
1182        /**
1183         * Dispatches the soft keyboard show mode change to any registered listeners. This should
1184         * be called on the service's main thread.
1185         */
1186        void dispatchSoftKeyboardShowModeChanged(final int showMode) {
1187            final ArrayMap<OnShowModeChangedListener, Handler> entries;
1188            synchronized (mLock) {
1189                if (mListeners == null || mListeners.isEmpty()) {
1190                    Slog.d(LOG_TAG, "Received soft keyboard show mode changed callback"
1191                            + " with no listeners registered!");
1192                    setSoftKeyboardCallbackEnabled(false);
1193                    return;
1194                }
1195
1196                // Listeners may remove themselves. Perform a shallow copy to avoid concurrent
1197                // modification.
1198                entries = new ArrayMap<>(mListeners);
1199            }
1200
1201            for (int i = 0, count = entries.size(); i < count; i++) {
1202                final OnShowModeChangedListener listener = entries.keyAt(i);
1203                final Handler handler = entries.valueAt(i);
1204                if (handler != null) {
1205                    handler.post(new Runnable() {
1206                        @Override
1207                        public void run() {
1208                            listener.onShowModeChanged(SoftKeyboardController.this, showMode);
1209                        }
1210                    });
1211                } else {
1212                    // We're already on the main thread, just run the listener.
1213                    listener.onShowModeChanged(this, showMode);
1214                }
1215            }
1216        }
1217
1218        /**
1219         * Returns the show mode of the soft keyboard. The default show mode is
1220         * {@code SHOW_MODE_AUTO}, where the soft keyboard is shown when a text input field is
1221         * focused. An AccessibilityService can also request the show mode
1222         * {@code SHOW_MODE_HIDDEN}, where the soft keyboard is never shown.
1223         *
1224         * @return the current soft keyboard show mode
1225         */
1226        @SoftKeyboardShowMode
1227        public int getShowMode() {
1228           try {
1229               return Settings.Secure.getInt(mService.getContentResolver(),
1230                       Settings.Secure.ACCESSIBILITY_SOFT_KEYBOARD_MODE);
1231           } catch (Settings.SettingNotFoundException e) {
1232               Log.v(LOG_TAG, "Failed to obtain the soft keyboard mode", e);
1233               // The settings hasn't been changed yet, so it's value is null. Return the default.
1234               return 0;
1235           }
1236        }
1237
1238        /**
1239         * Sets the soft keyboard show mode. The default show mode is
1240         * {@code SHOW_MODE_AUTO}, where the soft keyboard is shown when a text input field is
1241         * focused. An AccessibilityService can also request the show mode
1242         * {@code SHOW_MODE_HIDDEN}, where the soft keyboard is never shown. The
1243         * The lastto this method will be honored, regardless of any previous calls (including those
1244         * made by other AccessibilityServices).
1245         * <p>
1246         * <strong>Note:</strong> If the service is not yet conected (e.g.
1247         * {@link AccessibilityService#onServiceConnected()} has not yet been called) or the
1248         * service has been disconnected, this method will hav no effect and return {@code false}.
1249         *
1250         * @param showMode the new show mode for the soft keyboard
1251         * @return {@code true} on success
1252         */
1253        public boolean setShowMode(@SoftKeyboardShowMode int showMode) {
1254           final IAccessibilityServiceConnection connection =
1255                   AccessibilityInteractionClient.getInstance().getConnection(
1256                           mService.mConnectionId);
1257           if (connection != null) {
1258               try {
1259                   return connection.setSoftKeyboardShowMode(showMode);
1260               } catch (RemoteException re) {
1261                   Log.w(LOG_TAG, "Failed to set soft keyboard behavior", re);
1262                   re.rethrowFromSystemServer();
1263               }
1264           }
1265           return false;
1266        }
1267
1268        /**
1269         * Listener for changes in the soft keyboard show mode.
1270         */
1271        public interface OnShowModeChangedListener {
1272           /**
1273            * Called when the soft keyboard behavior changes. The default show mode is
1274            * {@code SHOW_MODE_AUTO}, where the soft keyboard is shown when a text input field is
1275            * focused. An AccessibilityService can also request the show mode
1276            * {@code SHOW_MODE_HIDDEN}, where the soft keyboard is never shown.
1277            *
1278            * @param controller the soft keyboard controller
1279            * @param showMode the current soft keyboard show mode
1280            */
1281            void onShowModeChanged(@NonNull SoftKeyboardController controller,
1282                    @SoftKeyboardShowMode int showMode);
1283        }
1284    }
1285
1286    /**
1287     * Performs a global action. Such an action can be performed
1288     * at any moment regardless of the current application or user
1289     * location in that application. For example going back, going
1290     * home, opening recents, etc.
1291     *
1292     * @param action The action to perform.
1293     * @return Whether the action was successfully performed.
1294     *
1295     * @see #GLOBAL_ACTION_BACK
1296     * @see #GLOBAL_ACTION_HOME
1297     * @see #GLOBAL_ACTION_NOTIFICATIONS
1298     * @see #GLOBAL_ACTION_RECENTS
1299     */
1300    public final boolean performGlobalAction(int action) {
1301        IAccessibilityServiceConnection connection =
1302            AccessibilityInteractionClient.getInstance().getConnection(mConnectionId);
1303        if (connection != null) {
1304            try {
1305                return connection.performGlobalAction(action);
1306            } catch (RemoteException re) {
1307                Log.w(LOG_TAG, "Error while calling performGlobalAction", re);
1308                re.rethrowFromSystemServer();
1309            }
1310        }
1311        return false;
1312    }
1313
1314    /**
1315     * Find the view that has the specified focus type. The search is performed
1316     * across all windows.
1317     * <p>
1318     * <strong>Note:</strong> In order to access the windows your service has
1319     * to declare the capability to retrieve window content by setting the
1320     * {@link android.R.styleable#AccessibilityService_canRetrieveWindowContent}
1321     * property in its meta-data. For details refer to {@link #SERVICE_META_DATA}.
1322     * Also the service has to opt-in to retrieve the interactive windows by
1323     * setting the {@link AccessibilityServiceInfo#FLAG_RETRIEVE_INTERACTIVE_WINDOWS}
1324     * flag. Otherwise, the search will be performed only in the active window.
1325     * </p>
1326     *
1327     * @param focus The focus to find. One of {@link AccessibilityNodeInfo#FOCUS_INPUT} or
1328     *         {@link AccessibilityNodeInfo#FOCUS_ACCESSIBILITY}.
1329     * @return The node info of the focused view or null.
1330     *
1331     * @see AccessibilityNodeInfo#FOCUS_INPUT
1332     * @see AccessibilityNodeInfo#FOCUS_ACCESSIBILITY
1333     */
1334    public AccessibilityNodeInfo findFocus(int focus) {
1335        return AccessibilityInteractionClient.getInstance().findFocus(mConnectionId,
1336                AccessibilityNodeInfo.ANY_WINDOW_ID, AccessibilityNodeInfo.ROOT_NODE_ID, focus);
1337    }
1338
1339    /**
1340     * Gets the an {@link AccessibilityServiceInfo} describing this
1341     * {@link AccessibilityService}. This method is useful if one wants
1342     * to change some of the dynamically configurable properties at
1343     * runtime.
1344     *
1345     * @return The accessibility service info.
1346     *
1347     * @see AccessibilityServiceInfo
1348     */
1349    public final AccessibilityServiceInfo getServiceInfo() {
1350        IAccessibilityServiceConnection connection =
1351            AccessibilityInteractionClient.getInstance().getConnection(mConnectionId);
1352        if (connection != null) {
1353            try {
1354                return connection.getServiceInfo();
1355            } catch (RemoteException re) {
1356                Log.w(LOG_TAG, "Error while getting AccessibilityServiceInfo", re);
1357                re.rethrowFromSystemServer();
1358            }
1359        }
1360        return null;
1361    }
1362
1363    /**
1364     * Sets the {@link AccessibilityServiceInfo} that describes this service.
1365     * <p>
1366     * Note: You can call this method any time but the info will be picked up after
1367     *       the system has bound to this service and when this method is called thereafter.
1368     *
1369     * @param info The info.
1370     */
1371    public final void setServiceInfo(AccessibilityServiceInfo info) {
1372        mInfo = info;
1373        sendServiceInfo();
1374    }
1375
1376    /**
1377     * Sets the {@link AccessibilityServiceInfo} for this service if the latter is
1378     * properly set and there is an {@link IAccessibilityServiceConnection} to the
1379     * AccessibilityManagerService.
1380     */
1381    private void sendServiceInfo() {
1382        IAccessibilityServiceConnection connection =
1383            AccessibilityInteractionClient.getInstance().getConnection(mConnectionId);
1384        if (mInfo != null && connection != null) {
1385            try {
1386                connection.setServiceInfo(mInfo);
1387                mInfo = null;
1388                AccessibilityInteractionClient.getInstance().clearCache();
1389            } catch (RemoteException re) {
1390                Log.w(LOG_TAG, "Error while setting AccessibilityServiceInfo", re);
1391                re.rethrowFromSystemServer();
1392            }
1393        }
1394    }
1395
1396    @Override
1397    public Object getSystemService(@ServiceName @NonNull String name) {
1398        if (getBaseContext() == null) {
1399            throw new IllegalStateException(
1400                    "System services not available to Activities before onCreate()");
1401        }
1402
1403        // Guarantee that we always return the same window manager instance.
1404        if (WINDOW_SERVICE.equals(name)) {
1405            if (mWindowManager == null) {
1406                mWindowManager = (WindowManager) getBaseContext().getSystemService(name);
1407            }
1408            return mWindowManager;
1409        }
1410        return super.getSystemService(name);
1411    }
1412
1413    /**
1414     * Implement to return the implementation of the internal accessibility
1415     * service interface.
1416     */
1417    @Override
1418    public final IBinder onBind(Intent intent) {
1419        return new IAccessibilityServiceClientWrapper(this, getMainLooper(), new Callbacks() {
1420            @Override
1421            public void onServiceConnected() {
1422                AccessibilityService.this.dispatchServiceConnected();
1423            }
1424
1425            @Override
1426            public void onInterrupt() {
1427                AccessibilityService.this.onInterrupt();
1428            }
1429
1430            @Override
1431            public void onAccessibilityEvent(AccessibilityEvent event) {
1432                AccessibilityService.this.onAccessibilityEvent(event);
1433            }
1434
1435            @Override
1436            public void init(int connectionId, IBinder windowToken) {
1437                mConnectionId = connectionId;
1438                mWindowToken = windowToken;
1439
1440                // The client may have already obtained the window manager, so
1441                // update the default token on whatever manager we gave them.
1442                final WindowManagerImpl wm = (WindowManagerImpl) getSystemService(WINDOW_SERVICE);
1443                wm.setDefaultToken(windowToken);
1444            }
1445
1446            @Override
1447            public boolean onGesture(int gestureId) {
1448                return AccessibilityService.this.onGesture(gestureId);
1449            }
1450
1451            @Override
1452            public boolean onKeyEvent(KeyEvent event) {
1453                return AccessibilityService.this.onKeyEvent(event);
1454            }
1455
1456            @Override
1457            public void onMagnificationChanged(@NonNull Region region,
1458                    float scale, float centerX, float centerY) {
1459                AccessibilityService.this.onMagnificationChanged(region, scale, centerX, centerY);
1460            }
1461
1462            @Override
1463            public void onSoftKeyboardShowModeChanged(int showMode) {
1464                AccessibilityService.this.onSoftKeyboardShowModeChanged(showMode);
1465            }
1466
1467            @Override
1468            public void onPerformGestureResult(int sequence, boolean completedSuccessfully) {
1469                AccessibilityService.this.onPerformGestureResult(sequence, completedSuccessfully);
1470            }
1471        });
1472    }
1473
1474    /**
1475     * Implements the internal {@link IAccessibilityServiceClient} interface to convert
1476     * incoming calls to it back to calls on an {@link AccessibilityService}.
1477     *
1478     * @hide
1479     */
1480    public static class IAccessibilityServiceClientWrapper extends IAccessibilityServiceClient.Stub
1481            implements HandlerCaller.Callback {
1482        private static final int DO_INIT = 1;
1483        private static final int DO_ON_INTERRUPT = 2;
1484        private static final int DO_ON_ACCESSIBILITY_EVENT = 3;
1485        private static final int DO_ON_GESTURE = 4;
1486        private static final int DO_CLEAR_ACCESSIBILITY_CACHE = 5;
1487        private static final int DO_ON_KEY_EVENT = 6;
1488        private static final int DO_ON_MAGNIFICATION_CHANGED = 7;
1489        private static final int DO_ON_SOFT_KEYBOARD_SHOW_MODE_CHANGED = 8;
1490        private static final int DO_GESTURE_COMPLETE = 9;
1491
1492        private final HandlerCaller mCaller;
1493
1494        private final Callbacks mCallback;
1495
1496        private int mConnectionId;
1497
1498        public IAccessibilityServiceClientWrapper(Context context, Looper looper,
1499                Callbacks callback) {
1500            mCallback = callback;
1501            mCaller = new HandlerCaller(context, looper, this, true /*asyncHandler*/);
1502        }
1503
1504        public void init(IAccessibilityServiceConnection connection, int connectionId,
1505                IBinder windowToken) {
1506            Message message = mCaller.obtainMessageIOO(DO_INIT, connectionId,
1507                    connection, windowToken);
1508            mCaller.sendMessage(message);
1509        }
1510
1511        public void onInterrupt() {
1512            Message message = mCaller.obtainMessage(DO_ON_INTERRUPT);
1513            mCaller.sendMessage(message);
1514        }
1515
1516        public void onAccessibilityEvent(AccessibilityEvent event) {
1517            Message message = mCaller.obtainMessageO(DO_ON_ACCESSIBILITY_EVENT, event);
1518            mCaller.sendMessage(message);
1519        }
1520
1521        public void onGesture(int gestureId) {
1522            Message message = mCaller.obtainMessageI(DO_ON_GESTURE, gestureId);
1523            mCaller.sendMessage(message);
1524        }
1525
1526        public void clearAccessibilityCache() {
1527            Message message = mCaller.obtainMessage(DO_CLEAR_ACCESSIBILITY_CACHE);
1528            mCaller.sendMessage(message);
1529        }
1530
1531        @Override
1532        public void onKeyEvent(KeyEvent event, int sequence) {
1533            Message message = mCaller.obtainMessageIO(DO_ON_KEY_EVENT, sequence, event);
1534            mCaller.sendMessage(message);
1535        }
1536
1537        public void onMagnificationChanged(@NonNull Region region,
1538                float scale, float centerX, float centerY) {
1539            final SomeArgs args = SomeArgs.obtain();
1540            args.arg1 = region;
1541            args.arg2 = scale;
1542            args.arg3 = centerX;
1543            args.arg4 = centerY;
1544
1545            final Message message = mCaller.obtainMessageO(DO_ON_MAGNIFICATION_CHANGED, args);
1546            mCaller.sendMessage(message);
1547        }
1548
1549        public void onSoftKeyboardShowModeChanged(int showMode) {
1550          final Message message =
1551                  mCaller.obtainMessageI(DO_ON_SOFT_KEYBOARD_SHOW_MODE_CHANGED, showMode);
1552          mCaller.sendMessage(message);
1553        }
1554
1555        public void onPerformGestureResult(int sequence, boolean successfully) {
1556            Message message = mCaller.obtainMessageII(DO_GESTURE_COMPLETE, sequence,
1557                    successfully ? 1 : 0);
1558            mCaller.sendMessage(message);
1559        }
1560
1561        @Override
1562        public void executeMessage(Message message) {
1563            switch (message.what) {
1564                case DO_ON_ACCESSIBILITY_EVENT: {
1565                    AccessibilityEvent event = (AccessibilityEvent) message.obj;
1566                    if (event != null) {
1567                        AccessibilityInteractionClient.getInstance().onAccessibilityEvent(event);
1568                        mCallback.onAccessibilityEvent(event);
1569                        // Make sure the event is recycled.
1570                        try {
1571                            event.recycle();
1572                        } catch (IllegalStateException ise) {
1573                            /* ignore - best effort */
1574                        }
1575                    }
1576                } return;
1577
1578                case DO_ON_INTERRUPT: {
1579                    mCallback.onInterrupt();
1580                } return;
1581
1582                case DO_INIT: {
1583                    mConnectionId = message.arg1;
1584                    SomeArgs args = (SomeArgs) message.obj;
1585                    IAccessibilityServiceConnection connection =
1586                            (IAccessibilityServiceConnection) args.arg1;
1587                    IBinder windowToken = (IBinder) args.arg2;
1588                    args.recycle();
1589                    if (connection != null) {
1590                        AccessibilityInteractionClient.getInstance().addConnection(mConnectionId,
1591                                connection);
1592                        mCallback.init(mConnectionId, windowToken);
1593                        mCallback.onServiceConnected();
1594                    } else {
1595                        AccessibilityInteractionClient.getInstance().removeConnection(
1596                                mConnectionId);
1597                        mConnectionId = AccessibilityInteractionClient.NO_ID;
1598                        AccessibilityInteractionClient.getInstance().clearCache();
1599                        mCallback.init(AccessibilityInteractionClient.NO_ID, null);
1600                    }
1601                } return;
1602
1603                case DO_ON_GESTURE: {
1604                    final int gestureId = message.arg1;
1605                    mCallback.onGesture(gestureId);
1606                } return;
1607
1608                case DO_CLEAR_ACCESSIBILITY_CACHE: {
1609                    AccessibilityInteractionClient.getInstance().clearCache();
1610                } return;
1611
1612                case DO_ON_KEY_EVENT: {
1613                    KeyEvent event = (KeyEvent) message.obj;
1614                    try {
1615                        IAccessibilityServiceConnection connection = AccessibilityInteractionClient
1616                                .getInstance().getConnection(mConnectionId);
1617                        if (connection != null) {
1618                            final boolean result = mCallback.onKeyEvent(event);
1619                            final int sequence = message.arg1;
1620                            try {
1621                                connection.setOnKeyEventResult(result, sequence);
1622                            } catch (RemoteException re) {
1623                                /* ignore */
1624                            }
1625                        }
1626                    } finally {
1627                        // Make sure the event is recycled.
1628                        try {
1629                            event.recycle();
1630                        } catch (IllegalStateException ise) {
1631                            /* ignore - best effort */
1632                        }
1633                    }
1634                } return;
1635
1636                case DO_ON_MAGNIFICATION_CHANGED: {
1637                    final SomeArgs args = (SomeArgs) message.obj;
1638                    final Region region = (Region) args.arg1;
1639                    final float scale = (float) args.arg2;
1640                    final float centerX = (float) args.arg3;
1641                    final float centerY = (float) args.arg4;
1642                    mCallback.onMagnificationChanged(region, scale, centerX, centerY);
1643                } return;
1644
1645                case DO_ON_SOFT_KEYBOARD_SHOW_MODE_CHANGED: {
1646                    final int showMode = (int) message.arg1;
1647                    mCallback.onSoftKeyboardShowModeChanged(showMode);
1648                } return;
1649
1650                case DO_GESTURE_COMPLETE: {
1651                    final boolean successfully = message.arg2 == 1;
1652                    mCallback.onPerformGestureResult(message.arg1, successfully);
1653                } return;
1654
1655                default :
1656                    Log.w(LOG_TAG, "Unknown message type " + message.what);
1657            }
1658        }
1659    }
1660
1661    /**
1662     * Class used to report status of dispatched gestures
1663     */
1664    public static abstract class GestureResultCallback {
1665        /** Called when the gesture has completed successfully
1666         *
1667         * @param gestureDescription The description of the gesture that completed.
1668         */
1669        public void onCompleted(GestureDescription gestureDescription) {
1670        }
1671
1672        /** Called when the gesture was cancelled
1673         *
1674         * @param gestureDescription The description of the gesture that was cancelled.
1675         */
1676        public void onCancelled(GestureDescription gestureDescription) {
1677        }
1678    }
1679
1680    /* Object to keep track of gesture result callbacks */
1681    private static class GestureResultCallbackInfo {
1682        GestureDescription gestureDescription;
1683        GestureResultCallback callback;
1684        Handler handler;
1685
1686        GestureResultCallbackInfo(GestureDescription gestureDescription,
1687                GestureResultCallback callback, Handler handler) {
1688            this.gestureDescription = gestureDescription;
1689            this.callback = callback;
1690            this.handler = handler;
1691        }
1692    }
1693}
1694