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