AccessibilityService.java revision 7b1e0c7046abefc0b40884b36197c8a803d9cf6d
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.Context; 21import android.content.Intent; 22import android.os.IBinder; 23import android.os.Looper; 24import android.os.Message; 25import android.os.RemoteException; 26import android.util.Log; 27import android.view.accessibility.AccessibilityEvent; 28import android.view.accessibility.AccessibilityInteractionClient; 29import android.view.accessibility.AccessibilityNodeInfo; 30 31import com.android.internal.os.HandlerCaller; 32 33/** 34 * An accessibility service runs in the background and receives callbacks by the system 35 * when {@link AccessibilityEvent}s are fired. Such events denote some state transition 36 * in the user interface, for example, the focus has changed, a button has been clicked, 37 * etc. Such a service can optionally request the capability for querying the content 38 * of the active window. Development of an accessibility service requires extending this 39 * class and implementing its abstract methods. 40 * 41 * <div class="special reference"> 42 * <h3>Developer Guides</h3> 43 * <p>For more information about creating AccessibilityServices, read the 44 * <a href="{@docRoot}guide/topics/ui/accessibility/index.html">Accessibility</a> 45 * developer guide.</p> 46 * </div> 47 * 48 * <h3>Lifecycle</h3> 49 * <p> 50 * The lifecycle of an accessibility service is managed exclusively by the system and 51 * follows the established service life cycle. Additionally, starting or stopping an 52 * accessibility service is triggered exclusively by an explicit user action through 53 * enabling or disabling it in the device settings. After the system binds to a service it 54 * calls {@link AccessibilityService#onServiceConnected()}. This method can be 55 * overriden by clients that want to perform post binding setup. 56 * </p> 57 * <h3>Declaration</h3> 58 * <p> 59 * An accessibility is declared as any other service in an AndroidManifest.xml but it 60 * must also specify that it handles the "android.accessibilityservice.AccessibilityService" 61 * {@link android.content.Intent}. Failure to declare this intent will cause the system to 62 * ignore the accessibility service. Following is an example declaration: 63 * </p> 64 * <pre> <service android:name=".MyAccessibilityService"> 65 * <intent-filter> 66 * <action android:name="android.accessibilityservice.AccessibilityService" /> 67 * </intent-filter> 68 * . . . 69 * </service></pre> 70 * <h3>Configuration</h3> 71 * <p> 72 * An accessibility service can be configured to receive specific types of accessibility events, 73 * listen only to specific packages, get events from each type only once in a given time frame, 74 * retrieve window content, specify a settings activity, etc. 75 * </p> 76 * <p> 77 * There are two approaches for configuring an accessibility service: 78 * </p> 79 * <ul> 80 * <li> 81 * Providing a {@link #SERVICE_META_DATA meta-data} entry in the manifest when declaring 82 * the service. A service declaration with a meta-data tag is presented below: 83 * <pre> <service android:name=".MyAccessibilityService"> 84 * <intent-filter> 85 * <action android:name="android.accessibilityservice.AccessibilityService" /> 86 * </intent-filter> 87 * <meta-data android:name="android.accessibilityservice" android:resource="@xml/accessibilityservice" /> 88 * </service></pre> 89 * <p class="note"> 90 * <strong>Note:</strong> This approach enables setting all properties. 91 * </p> 92 * <p> 93 * For more details refer to {@link #SERVICE_META_DATA} and 94 * <code><{@link android.R.styleable#AccessibilityService accessibility-service}></code>. 95 * </p> 96 * </li> 97 * <li> 98 * Calling {@link AccessibilityService#setServiceInfo(AccessibilityServiceInfo)}. Note 99 * that this method can be called any time to dynamically change the service configuration. 100 * <p class="note"> 101 * <strong>Note:</strong> This approach enables setting only dynamically configurable properties: 102 * {@link AccessibilityServiceInfo#eventTypes}, 103 * {@link AccessibilityServiceInfo#feedbackType}, 104 * {@link AccessibilityServiceInfo#flags}, 105 * {@link AccessibilityServiceInfo#notificationTimeout}, 106 * {@link AccessibilityServiceInfo#packageNames} 107 * </p> 108 * <p> 109 * For more details refer to {@link AccessibilityServiceInfo}. 110 * </p> 111 * </li> 112 * </ul> 113 * <h3>Retrieving window content</h3> 114 * <p> 115 * A service can specify in its declaration that it can retrieve the active window 116 * content which is represented as a tree of {@link AccessibilityNodeInfo}. Note that 117 * declaring this capability requires that the service declares its configuration via 118 * an XML resource referenced by {@link #SERVICE_META_DATA}. 119 * </p> 120 * <p> 121 * For security purposes an accessibility service can retrieve only the content of the 122 * currently active window. The currently active window is defined as the window from 123 * which was fired the last event of the following types: 124 * {@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED}, 125 * {@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}, 126 * {@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}, 127 * In other words, the last window that was shown or the last window that the user has touched 128 * during touch exploration. 129 * </p> 130 * <p> 131 * The entry point for retrieving window content is through calling 132 * {@link AccessibilityEvent#getSource() AccessibilityEvent.getSource()} of the last received 133 * event of the above types or a previous event from the same window 134 * (see {@link AccessibilityEvent#getWindowId() AccessibilityEvent.getWindowId()}). Invoking 135 * this method will return an {@link AccessibilityNodeInfo} that can be used to traverse the 136 * window content which represented as a tree of such objects. 137 * </p> 138 * <p class="note"> 139 * <strong>Note</strong> An accessibility service may have requested to be notified for 140 * a subset of the event types, thus be unaware that the active window has changed. Therefore 141 * accessibility service that would like to retrieve window content should: 142 * <ul> 143 * <li> 144 * Register for all event types with no notification timeout and keep track for the active 145 * window by calling {@link AccessibilityEvent#getWindowId()} of the last received event and 146 * compare this with the {@link AccessibilityNodeInfo#getWindowId()} before calling retrieval 147 * methods on the latter. 148 * </li> 149 * <li> 150 * Prepare that a retrieval method on {@link AccessibilityNodeInfo} may fail since the 151 * active window has changed and the service did not get the accessibility event yet. Note 152 * that it is possible to have a retrieval method failing even adopting the strategy 153 * specified in the previous bullet because the accessibility event dispatch is asynchronous 154 * and crosses process boundaries. 155 * </li> 156 * </ul> 157 * </p> 158 * <h3>Notification strategy</h3> 159 * <p> 160 * For each feedback type only one accessibility service is notified. Services are notified 161 * in the order of registration. Hence, if two services are registered for the same 162 * feedback type in the same package the first one wins. It is possible however, to 163 * register a service as the default one for a given feedback type. In such a case this 164 * service is invoked if no other service was interested in the event. In other words, default 165 * services do not compete with other services and are notified last regardless of the 166 * registration order. This enables "generic" accessibility services that work reasonably 167 * well with most applications to coexist with "polished" ones that are targeted for 168 * specific applications. 169 * </p> 170 * <p class="note"> 171 * <strong>Note:</strong> The event notification timeout is useful to avoid propagating 172 * events to the client too frequently since this is accomplished via an expensive 173 * interprocess call. One can think of the timeout as a criteria to determine when 174 * event generation has settled down.</p> 175 * <h3>Event types</h3> 176 * <ul> 177 * <li>{@link AccessibilityEvent#TYPE_VIEW_CLICKED} 178 * <li>{@link AccessibilityEvent#TYPE_VIEW_LONG_CLICKED} 179 * <li>{@link AccessibilityEvent#TYPE_VIEW_FOCUSED} 180 * <li>{@link AccessibilityEvent#TYPE_VIEW_SELECTED} 181 * <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED} 182 * <li>{@link AccessibilityEvent#TYPE_WINDOW_STATE_CHANGED} 183 * <li>{@link AccessibilityEvent#TYPE_NOTIFICATION_STATE_CHANGED} 184 * <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_START} 185 * <li>{@link AccessibilityEvent#TYPE_TOUCH_EXPLORATION_GESTURE_END} 186 * <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_ENTER} 187 * <li>{@link AccessibilityEvent#TYPE_VIEW_HOVER_EXIT} 188 * <li>{@link AccessibilityEvent#TYPE_VIEW_SCROLLED} 189 * <li>{@link AccessibilityEvent#TYPE_VIEW_TEXT_SELECTION_CHANGED} 190 * <li>{@link AccessibilityEvent#TYPE_WINDOW_CONTENT_CHANGED} 191 * </ul> 192 * <h3>Feedback types</h3> 193 * <ul> 194 * <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE} 195 * <li>{@link AccessibilityServiceInfo#FEEDBACK_HAPTIC} 196 * <li>{@link AccessibilityServiceInfo#FEEDBACK_AUDIBLE} 197 * <li>{@link AccessibilityServiceInfo#FEEDBACK_VISUAL} 198 * <li>{@link AccessibilityServiceInfo#FEEDBACK_GENERIC} 199 * </ul> 200 * @see AccessibilityEvent 201 * @see AccessibilityServiceInfo 202 * @see android.view.accessibility.AccessibilityManager 203 */ 204public abstract class AccessibilityService extends Service { 205 206 /** 207 * The user has performed a swipe up gesture on the touch screen. 208 */ 209 public static final int GESTURE_SWIPE_UP = 1; 210 211 /** 212 * The user has performed a swipe down gesture on the touch screen. 213 */ 214 public static final int GESTURE_SWIPE_DOWN = 2; 215 216 /** 217 * The user has performed a swipe left gesture on the touch screen. 218 */ 219 public static final int GESTURE_SWIPE_LEFT = 3; 220 221 /** 222 * The user has performed a swipe right gesture on the touch screen. 223 */ 224 public static final int GESTURE_SWIPE_RIGHT = 4; 225 226 /** 227 * The user has performed a swipe left and right gesture on the touch screen. 228 */ 229 public static final int GESTURE_SWIPE_LEFT_AND_RIGHT = 5; 230 231 /** 232 * The user has performed a swipe right and left gesture on the touch screen. 233 */ 234 public static final int GESTURE_SWIPE_RIGHT_AND_LEFT = 6; 235 236 /** 237 * The user has performed a swipe up and down gesture on the touch screen. 238 */ 239 public static final int GESTURE_SWIPE_UP_AND_DOWN = 7; 240 241 /** 242 * The user has performed a swipe down and up gesture on the touch screen. 243 */ 244 public static final int GESTURE_SWIPE_DOWN_AND_UP = 8; 245 246 /** 247 * The user has performed a left and up gesture on the touch screen. 248 */ 249 public static final int GESTURE_SWIPE_LEFT_AND_UP = 9; 250 251 /** 252 * The user has performed a left and down gesture on the touch screen. 253 */ 254 public static final int GESTURE_SWIPE_LEFT_AND_DOWN = 10; 255 256 /** 257 * The user has performed a right and up gesture on the touch screen. 258 */ 259 public static final int GESTURE_SWIPE_RIGHT_AND_UP = 11; 260 261 /** 262 * The user has performed a right and down gesture on the touch screen. 263 */ 264 public static final int GESTURE_SWIPE_RIGHT_AND_DOWN = 12; 265 266 /** 267 * The user has performed an up and left gesture on the touch screen. 268 */ 269 public static final int GESTURE_SWIPE_UP_AND_LEFT = 13; 270 271 /** 272 * The user has performed an up and right gesture on the touch screen. 273 */ 274 public static final int GESTURE_SWIPE_UP_AND_RIGHT = 14; 275 276 /** 277 * The user has performed an down and left gesture on the touch screen. 278 */ 279 public static final int GESTURE_SWIPE_DOWN_AND_LEFT = 15; 280 281 /** 282 * The user has performed an down and right gesture on the touch screen. 283 */ 284 public static final int GESTURE_SWIPE_DOWN_AND_RIGHT = 16; 285 286 /** 287 * The {@link Intent} that must be declared as handled by the service. 288 */ 289 public static final String SERVICE_INTERFACE = 290 "android.accessibilityservice.AccessibilityService"; 291 292 /** 293 * Name under which an AccessibilityService component publishes information 294 * about itself. This meta-data must reference an XML resource containing an 295 * <code><{@link android.R.styleable#AccessibilityService accessibility-service}></code> 296 * tag. This is a a sample XML file configuring an accessibility service: 297 * <pre> <accessibility-service 298 * android:accessibilityEventTypes="typeViewClicked|typeViewFocused" 299 * android:packageNames="foo.bar, foo.baz" 300 * android:accessibilityFeedbackType="feedbackSpoken" 301 * android:notificationTimeout="100" 302 * android:accessibilityFlags="flagDefault" 303 * android:settingsActivity="foo.bar.TestBackActivity" 304 * android:canRetrieveWindowContent="true" 305 * . . . 306 * /></pre> 307 */ 308 public static final String SERVICE_META_DATA = "android.accessibilityservice"; 309 310 /** 311 * Action to go back. 312 */ 313 public static final int GLOBAL_ACTION_BACK = 1; 314 315 /** 316 * Action to go home. 317 */ 318 public static final int GLOBAL_ACTION_HOME = 2; 319 320 /** 321 * Action to open the recents. 322 */ 323 public static final int GLOBAL_ACTION_RECENTS = 3; 324 325 /** 326 * Action to open the notifications. 327 */ 328 public static final int GLOBAL_ACTION_NOTIFICATIONS = 4; 329 330 private static final String LOG_TAG = "AccessibilityService"; 331 332 interface Callbacks { 333 public void onAccessibilityEvent(AccessibilityEvent event); 334 public void onInterrupt(); 335 public void onServiceConnected(); 336 public void onSetConnectionId(int connectionId); 337 public boolean onGesture(int gestureId); 338 } 339 340 private int mConnectionId; 341 342 private AccessibilityServiceInfo mInfo; 343 344 /** 345 * Callback for {@link android.view.accessibility.AccessibilityEvent}s. 346 * 347 * @param event An event. 348 */ 349 public abstract void onAccessibilityEvent(AccessibilityEvent event); 350 351 /** 352 * Callback for interrupting the accessibility feedback. 353 */ 354 public abstract void onInterrupt(); 355 356 /** 357 * This method is a part of the {@link AccessibilityService} lifecycle and is 358 * called after the system has successfully bound to the service. If is 359 * convenient to use this method for setting the {@link AccessibilityServiceInfo}. 360 * 361 * @see AccessibilityServiceInfo 362 * @see #setServiceInfo(AccessibilityServiceInfo) 363 */ 364 protected void onServiceConnected() { 365 366 } 367 368 /** 369 * Called by the system when the user performs a specific gesture on the 370 * touch screen. 371 * 372 * <strong>Note:</strong> To receive gestures an accessibility service must 373 * request that the device is in touch exploration mode by setting the 374 * {@link android.accessibilityservice.AccessibilityServiceInfo#FLAG_REQUEST_TOUCH_EXPLORATION_MODE} 375 * flag. 376 * 377 * @param gestureId The unique id of the performed gesture. 378 * 379 * @return Whether the gesture was handled. 380 * 381 * @see #GESTURE_SWIPE_UP 382 * @see #GESTURE_SWIPE_UP_AND_LEFT 383 * @see #GESTURE_SWIPE_UP_AND_DOWN 384 * @see #GESTURE_SWIPE_UP_AND_RIGHT 385 * @see #GESTURE_SWIPE_DOWN 386 * @see #GESTURE_SWIPE_DOWN_AND_LEFT 387 * @see #GESTURE_SWIPE_DOWN_AND_UP 388 * @see #GESTURE_SWIPE_DOWN_AND_RIGHT 389 * @see #GESTURE_SWIPE_LEFT 390 * @see #GESTURE_SWIPE_LEFT_AND_UP 391 * @see #GESTURE_SWIPE_LEFT_AND_RIGHT 392 * @see #GESTURE_SWIPE_LEFT_AND_DOWN 393 * @see #GESTURE_SWIPE_RIGHT 394 * @see #GESTURE_SWIPE_RIGHT_AND_UP 395 * @see #GESTURE_SWIPE_RIGHT_AND_LEFT 396 * @see #GESTURE_SWIPE_RIGHT_AND_DOWN 397 */ 398 protected boolean onGesture(int gestureId) { 399 return false; 400 } 401 402 /** 403 * Gets the root node in the currently active window if this service 404 * can retrieve window content. 405 * 406 * @return The root node if this service can retrieve window content. 407 */ 408 public AccessibilityNodeInfo getRootInActiveWindow() { 409 return AccessibilityInteractionClient.getInstance().getRootInActiveWindow(mConnectionId); 410 } 411 412 /** 413 * Performs a global action. Such an action can be performed 414 * at any moment regardless of the current application or user 415 * location in that application. For example going back, going 416 * home, opening recents, etc. 417 * 418 * @param action The action to perform. 419 * @return Whether the action was successfully performed. 420 * 421 * @see #GLOBAL_ACTION_BACK 422 * @see #GLOBAL_ACTION_HOME 423 * @see #GLOBAL_ACTION_NOTIFICATIONS 424 * @see #GLOBAL_ACTION_RECENTS 425 */ 426 public final boolean performGlobalAction(int action) { 427 IAccessibilityServiceConnection connection = 428 AccessibilityInteractionClient.getInstance().getConnection(mConnectionId); 429 if (connection != null) { 430 try { 431 return connection.performGlobalAction(action); 432 } catch (RemoteException re) { 433 Log.w(LOG_TAG, "Error while calling performGlobalAction", re); 434 } 435 } 436 return false; 437 } 438 439 /** 440 * Gets the an {@link AccessibilityServiceInfo} describing this 441 * {@link AccessibilityService}. This method is useful if one wants 442 * to change some of the dynamically configurable properties at 443 * runtime. 444 * 445 * @return The accessibility service info. 446 * 447 * @see AccessibilityNodeInfo 448 */ 449 public final AccessibilityServiceInfo getServiceInfo() { 450 IAccessibilityServiceConnection connection = 451 AccessibilityInteractionClient.getInstance().getConnection(mConnectionId); 452 if (connection != null) { 453 try { 454 return connection.getServiceInfo(); 455 } catch (RemoteException re) { 456 Log.w(LOG_TAG, "Error while getting AccessibilityServiceInfo", re); 457 } 458 } 459 return null; 460 } 461 462 /** 463 * Sets the {@link AccessibilityServiceInfo} that describes this service. 464 * <p> 465 * Note: You can call this method any time but the info will be picked up after 466 * the system has bound to this service and when this method is called thereafter. 467 * 468 * @param info The info. 469 */ 470 public final void setServiceInfo(AccessibilityServiceInfo info) { 471 mInfo = info; 472 sendServiceInfo(); 473 } 474 475 /** 476 * Sets the {@link AccessibilityServiceInfo} for this service if the latter is 477 * properly set and there is an {@link IAccessibilityServiceConnection} to the 478 * AccessibilityManagerService. 479 */ 480 private void sendServiceInfo() { 481 IAccessibilityServiceConnection connection = 482 AccessibilityInteractionClient.getInstance().getConnection(mConnectionId); 483 if (mInfo != null && connection != null) { 484 try { 485 connection.setServiceInfo(mInfo); 486 mInfo = null; 487 AccessibilityInteractionClient.getInstance().clearCache(); 488 } catch (RemoteException re) { 489 Log.w(LOG_TAG, "Error while setting AccessibilityServiceInfo", re); 490 } 491 } 492 } 493 494 /** 495 * Implement to return the implementation of the internal accessibility 496 * service interface. 497 */ 498 @Override 499 public final IBinder onBind(Intent intent) { 500 return new IAccessibilityServiceClientWrapper(this, getMainLooper(), new Callbacks() { 501 @Override 502 public void onServiceConnected() { 503 AccessibilityService.this.onServiceConnected(); 504 } 505 506 @Override 507 public void onInterrupt() { 508 AccessibilityService.this.onInterrupt(); 509 } 510 511 @Override 512 public void onAccessibilityEvent(AccessibilityEvent event) { 513 AccessibilityService.this.onAccessibilityEvent(event); 514 } 515 516 @Override 517 public void onSetConnectionId( int connectionId) { 518 mConnectionId = connectionId; 519 } 520 521 @Override 522 public boolean onGesture(int gestureId) { 523 return AccessibilityService.this.onGesture(gestureId); 524 } 525 }); 526 } 527 528 /** 529 * Implements the internal {@link IAccessibilityServiceClient} interface to convert 530 * incoming calls to it back to calls on an {@link AccessibilityService}. 531 */ 532 static class IAccessibilityServiceClientWrapper extends IAccessibilityServiceClient.Stub 533 implements HandlerCaller.Callback { 534 535 static final int NO_ID = -1; 536 537 private static final int DO_SET_SET_CONNECTION = 10; 538 private static final int DO_ON_INTERRUPT = 20; 539 private static final int DO_ON_ACCESSIBILITY_EVENT = 30; 540 private static final int DO_ON_GESTURE = 40; 541 542 private final HandlerCaller mCaller; 543 544 private final Callbacks mCallback; 545 546 public IAccessibilityServiceClientWrapper(Context context, Looper looper, 547 Callbacks callback) { 548 mCallback = callback; 549 mCaller = new HandlerCaller(context, looper, this); 550 } 551 552 public void setConnection(IAccessibilityServiceConnection connection, int connectionId) { 553 Message message = mCaller.obtainMessageIO(DO_SET_SET_CONNECTION, connectionId, 554 connection); 555 mCaller.sendMessage(message); 556 } 557 558 public void onInterrupt() { 559 Message message = mCaller.obtainMessage(DO_ON_INTERRUPT); 560 mCaller.sendMessage(message); 561 } 562 563 public void onAccessibilityEvent(AccessibilityEvent event) { 564 Message message = mCaller.obtainMessageO(DO_ON_ACCESSIBILITY_EVENT, event); 565 mCaller.sendMessage(message); 566 } 567 568 public void onGesture(int gestureId) { 569 Message message = mCaller.obtainMessageI(DO_ON_GESTURE, gestureId); 570 mCaller.sendMessage(message); 571 } 572 573 public void executeMessage(Message message) { 574 switch (message.what) { 575 case DO_ON_ACCESSIBILITY_EVENT : 576 AccessibilityEvent event = (AccessibilityEvent) message.obj; 577 if (event != null) { 578 AccessibilityInteractionClient.getInstance().onAccessibilityEvent(event); 579 mCallback.onAccessibilityEvent(event); 580 event.recycle(); 581 } 582 return; 583 case DO_ON_INTERRUPT : 584 mCallback.onInterrupt(); 585 return; 586 case DO_SET_SET_CONNECTION : 587 final int connectionId = message.arg1; 588 IAccessibilityServiceConnection connection = 589 (IAccessibilityServiceConnection) message.obj; 590 if (connection != null) { 591 AccessibilityInteractionClient.getInstance().addConnection(connectionId, 592 connection); 593 mCallback.onSetConnectionId(connectionId); 594 mCallback.onServiceConnected(); 595 } else { 596 AccessibilityInteractionClient.getInstance().removeConnection(connectionId); 597 mCallback.onSetConnectionId(AccessibilityInteractionClient.NO_ID); 598 } 599 return; 600 case DO_ON_GESTURE : 601 final int gestureId = message.arg1; 602 mCallback.onGesture(gestureId); 603 return; 604 default : 605 Log.w(LOG_TAG, "Unknown message type " + message.what); 606 } 607 } 608 } 609} 610