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