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