NfcAdapter.java revision bb951c893973691554f49d2e725985125f866b27
1/* 2 * Copyright (C) 2010 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.nfc; 18 19import java.util.HashMap; 20 21import android.annotation.SdkConstant; 22import android.annotation.SdkConstant.SdkConstantType; 23import android.app.Activity; 24import android.app.ActivityThread; 25import android.app.OnActivityPausedListener; 26import android.app.PendingIntent; 27import android.content.Context; 28import android.content.IntentFilter; 29import android.content.pm.IPackageManager; 30import android.content.pm.PackageManager; 31import android.nfc.tech.MifareClassic; 32import android.nfc.tech.Ndef; 33import android.nfc.tech.NfcA; 34import android.nfc.tech.NfcF; 35import android.os.IBinder; 36import android.os.RemoteException; 37import android.os.ServiceManager; 38import android.util.Log; 39 40/** 41 * Represents the local NFC adapter. 42 * <p> 43 * Use the helper {@link #getDefaultAdapter(Context)} to get the default NFC 44 * adapter for this Android device. 45 */ 46public final class NfcAdapter { 47 static final String TAG = "NFC"; 48 49 /** 50 * Intent to start an activity when a tag with NDEF payload is discovered. 51 * 52 * <p>The system inspects the first {@link NdefRecord} in the first {@link NdefMessage} and 53 * looks for a URI, SmartPoster, or MIME record. If a URI or SmartPoster record is found the 54 * intent will contain the URI in its data field. If a MIME record is found the intent will 55 * contain the MIME type in its type field. This allows activities to register 56 * {@link IntentFilter}s targeting specific content on tags. Activities should register the 57 * most specific intent filters possible to avoid the activity chooser dialog, which can 58 * disrupt the interaction with the tag as the user interacts with the screen. 59 * 60 * <p>If the tag has an NDEF payload this intent is started before 61 * {@link #ACTION_TECH_DISCOVERED}. If any activities respond to this intent neither 62 * {@link #ACTION_TECH_DISCOVERED} or {@link #ACTION_TAG_DISCOVERED} will be started. 63 */ 64 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 65 public static final String ACTION_NDEF_DISCOVERED = "android.nfc.action.NDEF_DISCOVERED"; 66 67 /** 68 * Intent to start an activity when a tag is discovered and activities are registered for the 69 * specific technologies on the tag. 70 * 71 * <p>To receive this intent an activity must include an intent filter 72 * for this action and specify the desired tech types in a 73 * manifest <code>meta-data</code> entry. Here is an example manfiest entry: 74 * <pre> 75 * <activity android:name=".nfc.TechFilter" android:label="NFC/TechFilter"> 76 * <!-- Add a technology filter --> 77 * <intent-filter> 78 * <action android:name="android.nfc.action.TECH_DISCOVERED" /> 79 * </intent-filter> 80 * 81 * <meta-data android:name="android.nfc.action.TECH_DISCOVERED" 82 * android:resource="@xml/filter_nfc" 83 * /> 84 * </activity> 85 * </pre> 86 * 87 * <p>The meta-data XML file should contain one or more <code>tech-list</code> entries 88 * each consisting or one or more <code>tech</code> entries. The <code>tech</code> entries refer 89 * to the qualified class name implementing the technology, for example "android.nfc.tech.NfcA". 90 * 91 * <p>A tag matches if any of the 92 * <code>tech-list</code> sets is a subset of {@link Tag#getTechList() Tag.getTechList()}. Each 93 * of the <code>tech-list</code>s is considered independently and the 94 * activity is considered a match is any single <code>tech-list</code> matches the tag that was 95 * discovered. This provides AND and OR semantics for filtering desired techs. Here is an 96 * example that will match any tag using {@link NfcF} or any tag using {@link NfcA}, 97 * {@link MifareClassic}, and {@link Ndef}: 98 * 99 * <pre> 100 * <resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"> 101 * <!-- capture anything using NfcF --> 102 * <tech-list> 103 * <tech>android.nfc.tech.NfcF</tech> 104 * </tech-list> 105 * 106 * <!-- OR --> 107 * 108 * <!-- capture all MIFARE Classics with NDEF payloads --> 109 * <tech-list> 110 * <tech>android.nfc.tech.NfcA</tech> 111 * <tech>android.nfc.tech.MifareClassic</tech> 112 * <tech>android.nfc.tech.Ndef</tech> 113 * </tech-list> 114 * </resources> 115 * </pre> 116 * 117 * <p>This intent is started after {@link #ACTION_NDEF_DISCOVERED} and before 118 * {@link #ACTION_TAG_DISCOVERED}. If any activities respond to {@link #ACTION_NDEF_DISCOVERED} 119 * this intent will not be started. If any activities respond to this intent 120 * {@link #ACTION_TAG_DISCOVERED} will not be started. 121 */ 122 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 123 public static final String ACTION_TECH_DISCOVERED = "android.nfc.action.TECH_DISCOVERED"; 124 125 /** 126 * Intent to start an activity when a tag is discovered. 127 * 128 * <p>This intent will not be started when a tag is discovered if any activities respond to 129 * {@link #ACTION_NDEF_DISCOVERED} or {@link #ACTION_TECH_DISCOVERED} for the current tag. 130 */ 131 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 132 public static final String ACTION_TAG_DISCOVERED = "android.nfc.action.TAG_DISCOVERED"; 133 134 /** 135 * Broadcast to only the activity that handles ACTION_TAG_DISCOVERED 136 * @hide 137 */ 138 public static final String ACTION_TAG_LEFT_FIELD = "android.nfc.action.TAG_LOST"; 139 140 /** 141 * Mandatory extra containing the {@link Tag} that was discovered for the 142 * {@link #ACTION_NDEF_DISCOVERED}, {@link #ACTION_TECH_DISCOVERED}, and 143 * {@link #ACTION_TAG_DISCOVERED} intents. 144 */ 145 public static final String EXTRA_TAG = "android.nfc.extra.TAG"; 146 147 /** 148 * Optional extra containing an array of {@link NdefMessage} present on the discovered tag for 149 * the {@link #ACTION_NDEF_DISCOVERED}, {@link #ACTION_TECH_DISCOVERED}, and 150 * {@link #ACTION_TAG_DISCOVERED} intents. 151 */ 152 public static final String EXTRA_NDEF_MESSAGES = "android.nfc.extra.NDEF_MESSAGES"; 153 154 /** 155 * Optional extra containing a byte array containing the ID of the discovered tag for 156 * the {@link #ACTION_NDEF_DISCOVERED}, {@link #ACTION_TECH_DISCOVERED}, and 157 * {@link #ACTION_TAG_DISCOVERED} intents. 158 */ 159 public static final String EXTRA_ID = "android.nfc.extra.ID"; 160 161 /** 162 * Broadcast Action: The state of the local NFC adapter has been 163 * changed. 164 * <p>For example, NFC has been turned on or off. 165 * <p>Always contains the extra field {@link #EXTRA_STATE} 166 * @hide 167 */ 168 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 169 public static final String ACTION_ADAPTER_STATE_CHANGED = 170 "android.nfc.action.ADAPTER_STATE_CHANGED"; 171 172 /** 173 * Used as an int extra field in {@link #ACTION_STATE_CHANGED} 174 * intents to request the current power state. Possible values are: 175 * {@link #STATE_OFF}, 176 * {@link #STATE_TURNING_ON}, 177 * {@link #STATE_ON}, 178 * {@link #STATE_TURNING_OFF}, 179 * @hide 180 */ 181 public static final String EXTRA_ADAPTER_STATE = "android.nfc.extra.ADAPTER_STATE"; 182 183 /** @hide */ 184 public static final int STATE_OFF = 1; 185 /** @hide */ 186 public static final int STATE_TURNING_ON = 2; 187 /** @hide */ 188 public static final int STATE_ON = 3; 189 /** @hide */ 190 public static final int STATE_TURNING_OFF = 4; 191 192 // Guarded by NfcAdapter.class 193 static boolean sIsInitialized = false; 194 195 // Final after first constructor, except for 196 // attemptDeadServiceRecovery() when NFC crashes - we accept a best effort 197 // recovery 198 static INfcAdapter sService; 199 static INfcTag sTagService; 200 201 /** 202 * The NfcAdapter object for each application context. 203 * There is a 1-1 relationship between application context and 204 * NfcAdapter object. 205 */ 206 static HashMap<Context, NfcAdapter> sNfcAdapters = new HashMap(); //guard by NfcAdapter.class 207 208 /** 209 * NfcAdapter used with a null context. This ctor was deprecated but we have 210 * to support it for backwards compatibility. New methods that require context 211 * might throw when called on the null-context NfcAdapter. 212 */ 213 static NfcAdapter sNullContextNfcAdapter; // protected by NfcAdapter.class 214 215 final NfcActivityManager mNfcActivityManager; 216 final Context mContext; 217 218 /** 219 * A callback to be invoked when the system successfully delivers your {@link NdefMessage} 220 * to another device. 221 * @see #setOnNdefPushCompleteCallback 222 */ 223 public interface OnNdefPushCompleteCallback { 224 /** 225 * Called on successful NDEF push. 226 * 227 * <p>This callback is usually made on a binder thread (not the UI thread). 228 * 229 * @param event {@link NfcEvent} with the {@link NfcEvent#nfcAdapter} field set 230 * @see #setNdefPushMessageCallback 231 */ 232 public void onNdefPushComplete(NfcEvent event); 233 } 234 235 /** 236 * A callback to be invoked when another NFC device capable of NDEF push (Android Beam) 237 * is within range. 238 * <p>Implement this interface and pass it to {@link 239 * NfcAdapter#setNdefPushMessageCallback setNdefPushMessageCallback()} in order to create an 240 * {@link NdefMessage} at the moment that another device is within range for NFC. Using this 241 * callback allows you to create a message with data that might vary based on the 242 * content currently visible to the user. Alternatively, you can call {@link 243 * #setNdefPushMessage setNdefPushMessage()} if the {@link NdefMessage} always contains the 244 * same data. 245 */ 246 public interface CreateNdefMessageCallback { 247 /** 248 * Called to provide a {@link NdefMessage} to push. 249 * 250 * <p>This callback is usually made on a binder thread (not the UI thread). 251 * 252 * <p>Called when this device is in range of another device 253 * that might support NDEF push. It allows the application to 254 * create the NDEF message only when it is required. 255 * 256 * <p>NDEF push cannot occur until this method returns, so do not 257 * block for too long. 258 * 259 * <p>The Android operating system will usually show a system UI 260 * on top of your activity during this time, so do not try to request 261 * input from the user to complete the callback, or provide custom NDEF 262 * push UI. The user probably will not see it. 263 * 264 * @param event {@link NfcEvent} with the {@link NfcEvent#nfcAdapter} field set 265 * @return NDEF message to push, or null to not provide a message 266 */ 267 public NdefMessage createNdefMessage(NfcEvent event); 268 } 269 270 /** 271 * Helper to check if this device has FEATURE_NFC, but without using 272 * a context. 273 * Equivalent to 274 * context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_NFC) 275 */ 276 private static boolean hasNfcFeature() { 277 IPackageManager pm = ActivityThread.getPackageManager(); 278 if (pm == null) { 279 Log.e(TAG, "Cannot get package manager, assuming no NFC feature"); 280 return false; 281 } 282 try { 283 return pm.hasSystemFeature(PackageManager.FEATURE_NFC); 284 } catch (RemoteException e) { 285 Log.e(TAG, "Package manager query failed, assuming no NFC feature", e); 286 return false; 287 } 288 } 289 290 /** 291 * Returns the NfcAdapter for application context, 292 * or throws if NFC is not available. 293 * @hide 294 */ 295 public static synchronized NfcAdapter getNfcAdapter(Context context) { 296 if (!sIsInitialized) { 297 /* is this device meant to have NFC */ 298 if (!hasNfcFeature()) { 299 Log.v(TAG, "this device does not have NFC support"); 300 throw new UnsupportedOperationException(); 301 } 302 303 sService = getServiceInterface(); 304 if (sService == null) { 305 Log.e(TAG, "could not retrieve NFC service"); 306 throw new UnsupportedOperationException(); 307 } 308 try { 309 sTagService = sService.getNfcTagInterface(); 310 } catch (RemoteException e) { 311 Log.e(TAG, "could not retrieve NFC Tag service"); 312 throw new UnsupportedOperationException(); 313 } 314 315 sIsInitialized = true; 316 } 317 if (context == null) { 318 if (sNullContextNfcAdapter == null) { 319 sNullContextNfcAdapter = new NfcAdapter(null); 320 } 321 return sNullContextNfcAdapter; 322 } 323 NfcAdapter adapter = sNfcAdapters.get(context); 324 if (adapter == null) { 325 adapter = new NfcAdapter(context); 326 sNfcAdapters.put(context, adapter); 327 } 328 return adapter; 329 } 330 331 /** get handle to NFC service interface */ 332 private static INfcAdapter getServiceInterface() { 333 /* get a handle to NFC service */ 334 IBinder b = ServiceManager.getService("nfc"); 335 if (b == null) { 336 return null; 337 } 338 return INfcAdapter.Stub.asInterface(b); 339 } 340 341 /** 342 * Helper to get the default NFC Adapter. 343 * <p> 344 * Most Android devices will only have one NFC Adapter (NFC Controller). 345 * <p> 346 * This helper is the equivalent of: 347 * <pre>{@code 348 * NfcManager manager = (NfcManager) context.getSystemService(Context.NFC_SERVICE); 349 * NfcAdapter adapter = manager.getDefaultAdapter(); 350 * }</pre> 351 * @param context the calling application's context 352 * 353 * @return the default NFC adapter, or null if no NFC adapter exists 354 */ 355 public static NfcAdapter getDefaultAdapter(Context context) { 356 if (context == null) { 357 throw new IllegalArgumentException("context cannot be null"); 358 } 359 context = context.getApplicationContext(); 360 /* use getSystemService() instead of just instantiating to take 361 * advantage of the context's cached NfcManager & NfcAdapter */ 362 NfcManager manager = (NfcManager) context.getSystemService(Context.NFC_SERVICE); 363 return manager.getDefaultAdapter(); 364 } 365 366 /** 367 * Legacy NfcAdapter getter, always use {@link #getDefaultAdapter(Context)} instead.<p> 368 * This method was deprecated at API level 10 (Gingerbread MR1) because a context is required 369 * for many NFC API methods. Those methods will fail when called on an NfcAdapter 370 * object created from this method.<p> 371 * @deprecated use {@link #getDefaultAdapter(Context)} 372 */ 373 @Deprecated 374 public static NfcAdapter getDefaultAdapter() { 375 Log.w(TAG, "WARNING: NfcAdapter.getDefaultAdapter() is deprecated, use " + 376 "NfcAdapter.getDefaultAdapter(Context) instead", new Exception()); 377 378 return NfcAdapter.getNfcAdapter(null); 379 } 380 381 NfcAdapter(Context context) { 382 mContext = context; 383 mNfcActivityManager = new NfcActivityManager(this); 384 } 385 386 /** 387 * @hide 388 */ 389 public Context getContext() { 390 return mContext; 391 } 392 393 /** 394 * Returns the binder interface to the service. 395 * @hide 396 */ 397 public INfcAdapter getService() { 398 isEnabled(); // NOP call to recover sService if it is stale 399 return sService; 400 } 401 402 /** 403 * Returns the binder interface to the tag service. 404 * @hide 405 */ 406 public INfcTag getTagService() { 407 isEnabled(); // NOP call to recover sTagService if it is stale 408 return sTagService; 409 } 410 411 /** 412 * NFC service dead - attempt best effort recovery 413 * @hide 414 */ 415 public void attemptDeadServiceRecovery(Exception e) { 416 Log.e(TAG, "NFC service dead - attempting to recover", e); 417 INfcAdapter service = getServiceInterface(); 418 if (service == null) { 419 Log.e(TAG, "could not retrieve NFC service during service recovery"); 420 // nothing more can be done now, sService is still stale, we'll hit 421 // this recovery path again later 422 return; 423 } 424 // assigning to sService is not thread-safe, but this is best-effort code 425 // and on a well-behaved system should never happen 426 sService = service; 427 try { 428 sTagService = service.getNfcTagInterface(); 429 } catch (RemoteException ee) { 430 Log.e(TAG, "could not retrieve NFC tag service during service recovery"); 431 // nothing more can be done now, sService is still stale, we'll hit 432 // this recovery path again later 433 } 434 435 return; 436 } 437 438 /** 439 * Return true if this NFC Adapter has any features enabled. 440 * 441 * <p>Application may use this as a helper to suggest that the user 442 * should turn on NFC in Settings. 443 * <p>If this method returns false, the NFC hardware is guaranteed not to 444 * generate or respond to any NFC transactions. 445 * 446 * @return true if this NFC Adapter has any features enabled 447 */ 448 public boolean isEnabled() { 449 try { 450 return sService.getState() == STATE_ON; 451 } catch (RemoteException e) { 452 attemptDeadServiceRecovery(e); 453 return false; 454 } 455 } 456 457 /** 458 * Return the state of this NFC Adapter. 459 * 460 * <p>Returns one of {@link #STATE_ON}, {@link #STATE_TURNING_ON}, 461 * {@link #STATE_OFF}, {@link #STATE_TURNING_OFF}. 462 * 463 * <p>{@link #isEnabled()} is equivalent to 464 * <code>{@link #getAdapterState()} == {@link #STATE_ON}</code> 465 * 466 * @return the current state of this NFC adapter 467 * 468 * @hide 469 */ 470 public int getAdapterState() { 471 try { 472 return sService.getState(); 473 } catch (RemoteException e) { 474 attemptDeadServiceRecovery(e); 475 return NfcAdapter.STATE_OFF; 476 } 477 } 478 479 /** 480 * Enable NFC hardware. 481 * 482 * <p>This call is asynchronous. Listen for 483 * {@link #ACTION_ADAPTER_STATE_CHANGED} broadcasts to find out when the 484 * operation is complete. 485 * 486 * <p>If this returns true, then either NFC is already on, or 487 * a {@link #ACTION_ADAPTER_STATE_CHANGED} broadcast will be sent 488 * to indicate a state transition. If this returns false, then 489 * there is some problem that prevents an attempt to turn 490 * NFC on (for example we are in airplane mode and NFC is not 491 * toggleable in airplane mode on this platform). 492 * 493 * @hide 494 */ 495 public boolean enable() { 496 try { 497 return sService.enable(); 498 } catch (RemoteException e) { 499 attemptDeadServiceRecovery(e); 500 return false; 501 } 502 } 503 504 /** 505 * Disable NFC hardware. 506 * 507 * <p>No NFC features will work after this call, and the hardware 508 * will not perform or respond to any NFC communication. 509 * 510 * <p>This call is asynchronous. Listen for 511 * {@link #ACTION_ADAPTER_STATE_CHANGED} broadcasts to find out when the 512 * operation is complete. 513 * 514 * <p>If this returns true, then either NFC is already off, or 515 * a {@link #ACTION_ADAPTER_STATE_CHANGED} broadcast will be sent 516 * to indicate a state transition. If this returns false, then 517 * there is some problem that prevents an attempt to turn 518 * NFC off. 519 * 520 * @hide 521 */ 522 public boolean disable() { 523 try { 524 return sService.disable(); 525 } catch (RemoteException e) { 526 attemptDeadServiceRecovery(e); 527 return false; 528 } 529 } 530 531 /** 532 * Set the {@link NdefMessage} to push over NFC during the specified activities. 533 * 534 * <p>This method may be called at any time, but the NDEF message is 535 * only made available for NDEF push when one of the specified activities 536 * is in resumed (foreground) state. 537 * 538 * <p>Only one NDEF message can be pushed by the currently resumed activity. 539 * If both {@link #setNdefPushMessage} and 540 * {@link #setNdefPushMessageCallback} are set then 541 * the callback will take priority. 542 * 543 * <p>Pass a null NDEF message to disable foreground NDEF push in the 544 * specified activities. 545 * 546 * <p>At least one activity must be specified, and usually only one is necessary. 547 * 548 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 549 * 550 * @param message NDEF message to push over NFC, or null to disable 551 * @param activity an activity in which NDEF push should be enabled to share the provided 552 * NDEF message 553 * @param activities optional additional activities that should also enable NDEF push with 554 * the provided NDEF message 555 */ 556 public void setNdefPushMessage(NdefMessage message, Activity activity, 557 Activity ... activities) { 558 if (activity == null) { 559 throw new NullPointerException("activity cannot be null"); 560 } 561 mNfcActivityManager.setNdefPushMessage(activity, message); 562 for (Activity a : activities) { 563 if (a == null) { 564 throw new NullPointerException("activities cannot contain null"); 565 } 566 mNfcActivityManager.setNdefPushMessage(a, message); 567 } 568 } 569 570 /** 571 * Set the callback to create a {@link NdefMessage} to push over NFC. 572 * 573 * <p>This method may be called at any time, but this callback is 574 * only made if one of the specified activities 575 * is in resumed (foreground) state. 576 * 577 * <p>Only one NDEF message can be pushed by the currently resumed activity. 578 * If both {@link #setNdefPushMessage} and 579 * {@link #setNdefPushMessageCallback} are set then 580 * the callback will take priority. 581 * 582 * <p>Pass a null callback to disable the callback in the 583 * specified activities. 584 * 585 * <p>At least one activity must be specified, and usually only one is necessary. 586 * 587 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 588 * 589 * @param callback callback, or null to disable 590 * @param activity an activity in which NDEF push should be enabled to share an NDEF message 591 * that's retrieved from the provided callback 592 * @param activities optional additional activities that should also enable NDEF push using 593 * the provided callback 594 */ 595 public void setNdefPushMessageCallback(CreateNdefMessageCallback callback, Activity activity, 596 Activity ... activities) { 597 if (activity == null) { 598 throw new NullPointerException("activity cannot be null"); 599 } 600 mNfcActivityManager.setNdefPushMessageCallback(activity, callback); 601 for (Activity a : activities) { 602 if (a == null) { 603 throw new NullPointerException("activities cannot contain null"); 604 } 605 mNfcActivityManager.setNdefPushMessageCallback(a, callback); 606 } 607 } 608 609 /** 610 * Set the callback on a successful NDEF push over NFC. 611 * 612 * <p>This method may be called at any time, but NDEF push and this callback 613 * can only occur when one of the specified activities is in resumed 614 * (foreground) state. 615 * 616 * <p>One or more activities must be specified. 617 * 618 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 619 * 620 * @param callback callback, or null to disable 621 * @param activity an activity to enable the callback (at least one is required) 622 * @param activities zero or more additional activities to enable to callback 623 */ 624 public void setOnNdefPushCompleteCallback(OnNdefPushCompleteCallback callback, 625 Activity activity, Activity ... activities) { 626 if (activity == null) { 627 throw new NullPointerException("activity cannot be null"); 628 } 629 mNfcActivityManager.setOnNdefPushCompleteCallback(activity, callback); 630 for (Activity a : activities) { 631 if (a == null) { 632 throw new NullPointerException("activities cannot contain null"); 633 } 634 mNfcActivityManager.setOnNdefPushCompleteCallback(a, callback); 635 } 636 } 637 638 /** 639 * Enable foreground dispatch to the given Activity. 640 * 641 * <p>This will give give priority to the foreground activity when 642 * dispatching a discovered {@link Tag} to an application. 643 * 644 * <p>If any IntentFilters are provided to this method they are used to match dispatch Intents 645 * for both the {@link NfcAdapter#ACTION_NDEF_DISCOVERED} and 646 * {@link NfcAdapter#ACTION_TAG_DISCOVERED}. Since {@link NfcAdapter#ACTION_TECH_DISCOVERED} 647 * relies on meta data outside of the IntentFilter matching for that dispatch Intent is handled 648 * by passing in the tech lists separately. Each first level entry in the tech list represents 649 * an array of technologies that must all be present to match. If any of the first level sets 650 * match then the dispatch is routed through the given PendingIntent. In other words, the second 651 * level is ANDed together and the first level entries are ORed together. 652 * 653 * <p>If you pass {@code null} for both the {@code filters} and {@code techLists} parameters 654 * that acts a wild card and will cause the foreground activity to receive all tags via the 655 * {@link NfcAdapter#ACTION_TAG_DISCOVERED} intent. 656 * 657 * <p>This method must be called from the main thread, and only when the activity is in the 658 * foreground (resumed). Also, activities must call {@link #disableForegroundDispatch} before 659 * the completion of their {@link Activity#onPause} callback to disable foreground dispatch 660 * after it has been enabled. 661 * 662 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 663 * 664 * @param activity the Activity to dispatch to 665 * @param intent the PendingIntent to start for the dispatch 666 * @param filters the IntentFilters to override dispatching for, or null to always dispatch 667 * @param techLists the tech lists used to perform matching for dispatching of the 668 * {@link NfcAdapter#ACTION_TECH_DISCOVERED} intent 669 * @throws IllegalStateException if the Activity is not currently in the foreground 670 */ 671 public void enableForegroundDispatch(Activity activity, PendingIntent intent, 672 IntentFilter[] filters, String[][] techLists) { 673 if (activity == null || intent == null) { 674 throw new NullPointerException(); 675 } 676 if (!activity.isResumed()) { 677 throw new IllegalStateException("Foreground dispatch can only be enabled " + 678 "when your activity is resumed"); 679 } 680 try { 681 TechListParcel parcel = null; 682 if (techLists != null && techLists.length > 0) { 683 parcel = new TechListParcel(techLists); 684 } 685 ActivityThread.currentActivityThread().registerOnActivityPausedListener(activity, 686 mForegroundDispatchListener); 687 sService.setForegroundDispatch(intent, filters, parcel); 688 } catch (RemoteException e) { 689 attemptDeadServiceRecovery(e); 690 } 691 } 692 693 /** 694 * Disable foreground dispatch to the given activity. 695 * 696 * <p>After calling {@link #enableForegroundDispatch}, an activity 697 * must call this method before its {@link Activity#onPause} callback 698 * completes. 699 * 700 * <p>This method must be called from the main thread. 701 * 702 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 703 * 704 * @param activity the Activity to disable dispatch to 705 * @throws IllegalStateException if the Activity has already been paused 706 */ 707 public void disableForegroundDispatch(Activity activity) { 708 ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity, 709 mForegroundDispatchListener); 710 disableForegroundDispatchInternal(activity, false); 711 } 712 713 OnActivityPausedListener mForegroundDispatchListener = new OnActivityPausedListener() { 714 @Override 715 public void onPaused(Activity activity) { 716 disableForegroundDispatchInternal(activity, true); 717 } 718 }; 719 720 void disableForegroundDispatchInternal(Activity activity, boolean force) { 721 try { 722 sService.setForegroundDispatch(null, null, null); 723 if (!force && !activity.isResumed()) { 724 throw new IllegalStateException("You must disable foreground dispatching " + 725 "while your activity is still resumed"); 726 } 727 } catch (RemoteException e) { 728 attemptDeadServiceRecovery(e); 729 } 730 } 731 732 /** 733 * Enable NDEF message push over NFC while this Activity is in the foreground. 734 * 735 * <p>You must explicitly call this method every time the activity is 736 * resumed, and you must call {@link #disableForegroundNdefPush} before 737 * your activity completes {@link Activity#onPause}. 738 * 739 * <p>Strongly recommend to use the new {@link #setNdefPushMessage} 740 * instead: it automatically hooks into your activity life-cycle, 741 * so you do not need to call enable/disable in your onResume/onPause. 742 * 743 * <p>For NDEF push to function properly the other NFC device must 744 * support either NFC Forum's SNEP (Simple Ndef Exchange Protocol), or 745 * Android's "com.android.npp" (Ndef Push Protocol). This was optional 746 * on Gingerbread level Android NFC devices, but SNEP is mandatory on 747 * Ice-Cream-Sandwich and beyond. 748 * 749 * <p>This method must be called from the main thread. 750 * 751 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 752 * 753 * @param activity foreground activity 754 * @param message a NDEF Message to push over NFC 755 * @throws IllegalStateException if the activity is not currently in the foreground 756 * @deprecated use {@link #setNdefPushMessage} instead 757 */ 758 @Deprecated 759 public void enableForegroundNdefPush(Activity activity, NdefMessage message) { 760 if (activity == null || message == null) { 761 throw new NullPointerException(); 762 } 763 enforceResumed(activity); 764 mNfcActivityManager.setNdefPushMessage(activity, message); 765 } 766 767 /** 768 * Disable NDEF message push over P2P. 769 * 770 * <p>After calling {@link #enableForegroundNdefPush}, an activity 771 * must call this method before its {@link Activity#onPause} callback 772 * completes. 773 * 774 * <p>Strongly recommend to use the new {@link #setNdefPushMessage} 775 * instead: it automatically hooks into your activity life-cycle, 776 * so you do not need to call enable/disable in your onResume/onPause. 777 * 778 * <p>This method must be called from the main thread. 779 * 780 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 781 * 782 * @param activity the Foreground activity 783 * @throws IllegalStateException if the Activity has already been paused 784 * @deprecated use {@link #setNdefPushMessage} instead 785 */ 786 public void disableForegroundNdefPush(Activity activity) { 787 if (activity == null) { 788 throw new NullPointerException(); 789 } 790 enforceResumed(activity); 791 mNfcActivityManager.setNdefPushMessage(activity, null); 792 mNfcActivityManager.setNdefPushMessageCallback(activity, null); 793 mNfcActivityManager.setOnNdefPushCompleteCallback(activity, null); 794 } 795 796 /** 797 * TODO: Remove this once pre-built apk's (Maps, Youtube etc) are updated 798 * @deprecated use {@link CreateNdefMessageCallback} or {@link OnNdefPushCompleteCallback} 799 * @hide 800 */ 801 @Deprecated 802 public interface NdefPushCallback { 803 /** 804 * @deprecated use {@link CreateNdefMessageCallback} instead 805 */ 806 @Deprecated 807 NdefMessage createMessage(); 808 /** 809 * @deprecated use{@link OnNdefPushCompleteCallback} instead 810 */ 811 @Deprecated 812 void onMessagePushed(); 813 } 814 815 /** 816 * TODO: Remove this 817 * Converts new callbacks to old callbacks. 818 */ 819 static final class LegacyCallbackWrapper implements CreateNdefMessageCallback, 820 OnNdefPushCompleteCallback { 821 final NdefPushCallback mLegacyCallback; 822 LegacyCallbackWrapper(NdefPushCallback legacyCallback) { 823 mLegacyCallback = legacyCallback; 824 } 825 @Override 826 public void onNdefPushComplete(NfcEvent event) { 827 mLegacyCallback.onMessagePushed(); 828 } 829 @Override 830 public NdefMessage createNdefMessage(NfcEvent event) { 831 return mLegacyCallback.createMessage(); 832 } 833 } 834 835 /** 836 * TODO: Remove this once pre-built apk's (Maps, Youtube etc) are updated 837 * @deprecated use {@link #setNdefPushMessageCallback} instead 838 * @hide 839 */ 840 @Deprecated 841 public void enableForegroundNdefPush(Activity activity, final NdefPushCallback callback) { 842 if (activity == null || callback == null) { 843 throw new NullPointerException(); 844 } 845 enforceResumed(activity); 846 LegacyCallbackWrapper callbackWrapper = new LegacyCallbackWrapper(callback); 847 mNfcActivityManager.setNdefPushMessageCallback(activity, callbackWrapper); 848 mNfcActivityManager.setOnNdefPushCompleteCallback(activity, callbackWrapper); 849 } 850 851 /** 852 * Enable NDEF Push feature. 853 * <p>This API is for the Settings application. 854 * @hide 855 */ 856 public boolean enableNdefPush() { 857 try { 858 return sService.enableNdefPush(); 859 } catch (RemoteException e) { 860 attemptDeadServiceRecovery(e); 861 return false; 862 } 863 } 864 865 /** 866 * Disable NDEF Push feature. 867 * <p>This API is for the Settings application. 868 * @hide 869 */ 870 public boolean disableNdefPush() { 871 try { 872 return sService.disableNdefPush(); 873 } catch (RemoteException e) { 874 attemptDeadServiceRecovery(e); 875 return false; 876 } 877 } 878 879 /** 880 * Return true if NDEF Push feature is enabled. 881 * <p>This function can return true even if NFC is currently turned-off. 882 * This indicates that NDEF Push is not currently active, but it has 883 * been requested by the user and will be active as soon as NFC is turned 884 * on. 885 * <p>If you want to check if NDEF PUsh sharing is currently active, use 886 * <code>{@link #isEnabled()} && {@link #isNdefPushEnabled()}</code> 887 * 888 * @return true if NDEF Push feature is enabled 889 * @hide 890 */ 891 public boolean isNdefPushEnabled() { 892 try { 893 return sService.isNdefPushEnabled(); 894 } catch (RemoteException e) { 895 attemptDeadServiceRecovery(e); 896 return false; 897 } 898 } 899 900 /** 901 * @hide 902 */ 903 public INfcAdapterExtras getNfcAdapterExtrasInterface() { 904 if (mContext == null) { 905 throw new UnsupportedOperationException("You need a context on NfcAdapter to use the " 906 + " NFC extras APIs"); 907 } 908 try { 909 return sService.getNfcAdapterExtrasInterface(mContext.getPackageName()); 910 } catch (RemoteException e) { 911 attemptDeadServiceRecovery(e); 912 return null; 913 } 914 } 915 916 void enforceResumed(Activity activity) { 917 if (!activity.isResumed()) { 918 throw new IllegalStateException("API cannot be called while activity is paused"); 919 } 920 } 921} 922