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