NfcAdapter.java revision a356bf1cd81614a94ef6c720998792480ade4c84
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 if (context == null) { 361 throw new IllegalArgumentException( 362 "context not associated with any application (using a mock context?)"); 363 } 364 /* use getSystemService() for consistency */ 365 NfcManager manager = (NfcManager) context.getSystemService(Context.NFC_SERVICE); 366 if (manager == null) { 367 // NFC not available 368 return null; 369 } 370 return manager.getDefaultAdapter(); 371 } 372 373 /** 374 * Legacy NfcAdapter getter, always use {@link #getDefaultAdapter(Context)} instead.<p> 375 * This method was deprecated at API level 10 (Gingerbread MR1) because a context is required 376 * for many NFC API methods. Those methods will fail when called on an NfcAdapter 377 * object created from this method.<p> 378 * @deprecated use {@link #getDefaultAdapter(Context)} 379 * @hide 380 */ 381 @Deprecated 382 public static NfcAdapter getDefaultAdapter() { 383 // introduce in API version 9 (GB 2.3) 384 // deprecated in API version 10 (GB 2.3.3) 385 // removed from public API in version 16 (ICS MR2) 386 // will need to maintain this as a hidden API for a while longer... 387 Log.w(TAG, "WARNING: NfcAdapter.getDefaultAdapter() is deprecated, use " + 388 "NfcAdapter.getDefaultAdapter(Context) instead", new Exception()); 389 390 return NfcAdapter.getNfcAdapter(null); 391 } 392 393 NfcAdapter(Context context) { 394 mContext = context; 395 mNfcActivityManager = new NfcActivityManager(this); 396 } 397 398 /** 399 * @hide 400 */ 401 public Context getContext() { 402 return mContext; 403 } 404 405 /** 406 * Returns the binder interface to the service. 407 * @hide 408 */ 409 public INfcAdapter getService() { 410 isEnabled(); // NOP call to recover sService if it is stale 411 return sService; 412 } 413 414 /** 415 * Returns the binder interface to the tag service. 416 * @hide 417 */ 418 public INfcTag getTagService() { 419 isEnabled(); // NOP call to recover sTagService if it is stale 420 return sTagService; 421 } 422 423 /** 424 * NFC service dead - attempt best effort recovery 425 * @hide 426 */ 427 public void attemptDeadServiceRecovery(Exception e) { 428 Log.e(TAG, "NFC service dead - attempting to recover", e); 429 INfcAdapter service = getServiceInterface(); 430 if (service == null) { 431 Log.e(TAG, "could not retrieve NFC service during service recovery"); 432 // nothing more can be done now, sService is still stale, we'll hit 433 // this recovery path again later 434 return; 435 } 436 // assigning to sService is not thread-safe, but this is best-effort code 437 // and on a well-behaved system should never happen 438 sService = service; 439 try { 440 sTagService = service.getNfcTagInterface(); 441 } catch (RemoteException ee) { 442 Log.e(TAG, "could not retrieve NFC tag service during service recovery"); 443 // nothing more can be done now, sService is still stale, we'll hit 444 // this recovery path again later 445 } 446 447 return; 448 } 449 450 /** 451 * Return true if this NFC Adapter has any features enabled. 452 * 453 * <p>If this method returns false, the NFC hardware is guaranteed not to 454 * generate or respond to any NFC communication over its NFC radio. 455 * <p>Applications can use this to check if NFC is enabled. Applications 456 * can request Settings UI allowing the user to toggle NFC using: 457 * <p><pre>startActivity(new Intent(Settings.ACTION_NFC_SETTINGS))</pre> 458 * 459 * @see android.provider.Settings#ACTION_NFC_SETTINGS 460 * @return true if this NFC Adapter has any features enabled 461 */ 462 public boolean isEnabled() { 463 try { 464 return sService.getState() == STATE_ON; 465 } catch (RemoteException e) { 466 attemptDeadServiceRecovery(e); 467 return false; 468 } 469 } 470 471 /** 472 * Return the state of this NFC Adapter. 473 * 474 * <p>Returns one of {@link #STATE_ON}, {@link #STATE_TURNING_ON}, 475 * {@link #STATE_OFF}, {@link #STATE_TURNING_OFF}. 476 * 477 * <p>{@link #isEnabled()} is equivalent to 478 * <code>{@link #getAdapterState()} == {@link #STATE_ON}</code> 479 * 480 * @return the current state of this NFC adapter 481 * 482 * @hide 483 */ 484 public int getAdapterState() { 485 try { 486 return sService.getState(); 487 } catch (RemoteException e) { 488 attemptDeadServiceRecovery(e); 489 return NfcAdapter.STATE_OFF; 490 } 491 } 492 493 /** 494 * Enable NFC hardware. 495 * 496 * <p>This call is asynchronous. Listen for 497 * {@link #ACTION_ADAPTER_STATE_CHANGED} broadcasts to find out when the 498 * operation is complete. 499 * 500 * <p>If this returns true, then either NFC is already on, or 501 * a {@link #ACTION_ADAPTER_STATE_CHANGED} broadcast will be sent 502 * to indicate a state transition. If this returns false, then 503 * there is some problem that prevents an attempt to turn 504 * NFC on (for example we are in airplane mode and NFC is not 505 * toggleable in airplane mode on this platform). 506 * 507 * @hide 508 */ 509 public boolean enable() { 510 try { 511 return sService.enable(); 512 } catch (RemoteException e) { 513 attemptDeadServiceRecovery(e); 514 return false; 515 } 516 } 517 518 /** 519 * Disable NFC hardware. 520 * 521 * <p>No NFC features will work after this call, and the hardware 522 * will not perform or respond to any NFC communication. 523 * 524 * <p>This call is asynchronous. Listen for 525 * {@link #ACTION_ADAPTER_STATE_CHANGED} broadcasts to find out when the 526 * operation is complete. 527 * 528 * <p>If this returns true, then either NFC is already off, or 529 * a {@link #ACTION_ADAPTER_STATE_CHANGED} broadcast will be sent 530 * to indicate a state transition. If this returns false, then 531 * there is some problem that prevents an attempt to turn 532 * NFC off. 533 * 534 * @hide 535 */ 536 public boolean disable() { 537 try { 538 return sService.disable(); 539 } catch (RemoteException e) { 540 attemptDeadServiceRecovery(e); 541 return false; 542 } 543 } 544 545 /** 546 * Set the {@link NdefMessage} to push over NFC during the specified activities. 547 * 548 * <p>This method may be called at any time, but the NDEF message is 549 * only made available for NDEF push when one of the specified activities 550 * is in resumed (foreground) state. 551 * 552 * <p>Only one NDEF message can be pushed by the currently resumed activity. 553 * If both {@link #setNdefPushMessage} and 554 * {@link #setNdefPushMessageCallback} are set then 555 * the callback will take priority. 556 * 557 * <p>Pass a null NDEF message to disable foreground NDEF push in the 558 * specified activities. 559 * 560 * <p>At least one activity must be specified, and usually only one is necessary. 561 * 562 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 563 * 564 * @param message NDEF message to push over NFC, or null to disable 565 * @param activity an activity in which NDEF push should be enabled to share the provided 566 * NDEF message 567 * @param activities optional additional activities that should also enable NDEF push with 568 * the provided NDEF message 569 */ 570 public void setNdefPushMessage(NdefMessage message, Activity activity, 571 Activity ... activities) { 572 if (activity == null) { 573 throw new NullPointerException("activity cannot be null"); 574 } 575 mNfcActivityManager.setNdefPushMessage(activity, message); 576 for (Activity a : activities) { 577 if (a == null) { 578 throw new NullPointerException("activities cannot contain null"); 579 } 580 mNfcActivityManager.setNdefPushMessage(a, message); 581 } 582 } 583 584 /** 585 * Set the callback to create a {@link NdefMessage} to push over NFC. 586 * 587 * <p>This method may be called at any time, but this callback is 588 * only made if one of the specified activities 589 * is in resumed (foreground) state. 590 * 591 * <p>Only one NDEF message can be pushed by the currently resumed activity. 592 * If both {@link #setNdefPushMessage} and 593 * {@link #setNdefPushMessageCallback} are set then 594 * the callback will take priority. 595 * 596 * <p>Pass a null callback to disable the callback in the 597 * specified activities. 598 * 599 * <p>At least one activity must be specified, and usually only one is necessary. 600 * 601 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 602 * 603 * @param callback callback, or null to disable 604 * @param activity an activity in which NDEF push should be enabled to share an NDEF message 605 * that's retrieved from the provided callback 606 * @param activities optional additional activities that should also enable NDEF push using 607 * the provided callback 608 */ 609 public void setNdefPushMessageCallback(CreateNdefMessageCallback callback, Activity activity, 610 Activity ... activities) { 611 if (activity == null) { 612 throw new NullPointerException("activity cannot be null"); 613 } 614 mNfcActivityManager.setNdefPushMessageCallback(activity, callback); 615 for (Activity a : activities) { 616 if (a == null) { 617 throw new NullPointerException("activities cannot contain null"); 618 } 619 mNfcActivityManager.setNdefPushMessageCallback(a, callback); 620 } 621 } 622 623 /** 624 * Set the callback on a successful NDEF push over NFC. 625 * 626 * <p>This method may be called at any time, but NDEF push and this callback 627 * can only occur when one of the specified activities is in resumed 628 * (foreground) state. 629 * 630 * <p>One or more activities must be specified. 631 * 632 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 633 * 634 * @param callback callback, or null to disable 635 * @param activity an activity to enable the callback (at least one is required) 636 * @param activities zero or more additional activities to enable to callback 637 */ 638 public void setOnNdefPushCompleteCallback(OnNdefPushCompleteCallback callback, 639 Activity activity, Activity ... activities) { 640 if (activity == null) { 641 throw new NullPointerException("activity cannot be null"); 642 } 643 mNfcActivityManager.setOnNdefPushCompleteCallback(activity, callback); 644 for (Activity a : activities) { 645 if (a == null) { 646 throw new NullPointerException("activities cannot contain null"); 647 } 648 mNfcActivityManager.setOnNdefPushCompleteCallback(a, callback); 649 } 650 } 651 652 /** 653 * Enable foreground dispatch to the given Activity. 654 * 655 * <p>This will give give priority to the foreground activity when 656 * dispatching a discovered {@link Tag} to an application. 657 * 658 * <p>If any IntentFilters are provided to this method they are used to match dispatch Intents 659 * for both the {@link NfcAdapter#ACTION_NDEF_DISCOVERED} and 660 * {@link NfcAdapter#ACTION_TAG_DISCOVERED}. Since {@link NfcAdapter#ACTION_TECH_DISCOVERED} 661 * relies on meta data outside of the IntentFilter matching for that dispatch Intent is handled 662 * by passing in the tech lists separately. Each first level entry in the tech list represents 663 * an array of technologies that must all be present to match. If any of the first level sets 664 * match then the dispatch is routed through the given PendingIntent. In other words, the second 665 * level is ANDed together and the first level entries are ORed together. 666 * 667 * <p>If you pass {@code null} for both the {@code filters} and {@code techLists} parameters 668 * that acts a wild card and will cause the foreground activity to receive all tags via the 669 * {@link NfcAdapter#ACTION_TAG_DISCOVERED} intent. 670 * 671 * <p>This method must be called from the main thread, and only when the activity is in the 672 * foreground (resumed). Also, activities must call {@link #disableForegroundDispatch} before 673 * the completion of their {@link Activity#onPause} callback to disable foreground dispatch 674 * after it has been enabled. 675 * 676 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 677 * 678 * @param activity the Activity to dispatch to 679 * @param intent the PendingIntent to start for the dispatch 680 * @param filters the IntentFilters to override dispatching for, or null to always dispatch 681 * @param techLists the tech lists used to perform matching for dispatching of the 682 * {@link NfcAdapter#ACTION_TECH_DISCOVERED} intent 683 * @throws IllegalStateException if the Activity is not currently in the foreground 684 */ 685 public void enableForegroundDispatch(Activity activity, PendingIntent intent, 686 IntentFilter[] filters, String[][] techLists) { 687 if (activity == null || intent == null) { 688 throw new NullPointerException(); 689 } 690 if (!activity.isResumed()) { 691 throw new IllegalStateException("Foreground dispatch can only be enabled " + 692 "when your activity is resumed"); 693 } 694 try { 695 TechListParcel parcel = null; 696 if (techLists != null && techLists.length > 0) { 697 parcel = new TechListParcel(techLists); 698 } 699 ActivityThread.currentActivityThread().registerOnActivityPausedListener(activity, 700 mForegroundDispatchListener); 701 sService.setForegroundDispatch(intent, filters, parcel); 702 } catch (RemoteException e) { 703 attemptDeadServiceRecovery(e); 704 } 705 } 706 707 /** 708 * Disable foreground dispatch to the given activity. 709 * 710 * <p>After calling {@link #enableForegroundDispatch}, an activity 711 * must call this method before its {@link Activity#onPause} callback 712 * completes. 713 * 714 * <p>This method must be called from the main thread. 715 * 716 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 717 * 718 * @param activity the Activity to disable dispatch to 719 * @throws IllegalStateException if the Activity has already been paused 720 */ 721 public void disableForegroundDispatch(Activity activity) { 722 ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity, 723 mForegroundDispatchListener); 724 disableForegroundDispatchInternal(activity, false); 725 } 726 727 OnActivityPausedListener mForegroundDispatchListener = new OnActivityPausedListener() { 728 @Override 729 public void onPaused(Activity activity) { 730 disableForegroundDispatchInternal(activity, true); 731 } 732 }; 733 734 void disableForegroundDispatchInternal(Activity activity, boolean force) { 735 try { 736 sService.setForegroundDispatch(null, null, null); 737 if (!force && !activity.isResumed()) { 738 throw new IllegalStateException("You must disable foreground dispatching " + 739 "while your activity is still resumed"); 740 } 741 } catch (RemoteException e) { 742 attemptDeadServiceRecovery(e); 743 } 744 } 745 746 /** 747 * Enable NDEF message push over NFC while this Activity is in the foreground. 748 * 749 * <p>You must explicitly call this method every time the activity is 750 * resumed, and you must call {@link #disableForegroundNdefPush} before 751 * your activity completes {@link Activity#onPause}. 752 * 753 * <p>Strongly recommend to use the new {@link #setNdefPushMessage} 754 * instead: it automatically hooks into your activity life-cycle, 755 * so you do not need to call enable/disable in your onResume/onPause. 756 * 757 * <p>For NDEF push to function properly the other NFC device must 758 * support either NFC Forum's SNEP (Simple Ndef Exchange Protocol), or 759 * Android's "com.android.npp" (Ndef Push Protocol). This was optional 760 * on Gingerbread level Android NFC devices, but SNEP is mandatory on 761 * Ice-Cream-Sandwich and beyond. 762 * 763 * <p>This method must be called from the main thread. 764 * 765 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 766 * 767 * @param activity foreground activity 768 * @param message a NDEF Message to push over NFC 769 * @throws IllegalStateException if the activity is not currently in the foreground 770 * @deprecated use {@link #setNdefPushMessage} instead 771 */ 772 @Deprecated 773 public void enableForegroundNdefPush(Activity activity, NdefMessage message) { 774 if (activity == null || message == null) { 775 throw new NullPointerException(); 776 } 777 enforceResumed(activity); 778 mNfcActivityManager.setNdefPushMessage(activity, message); 779 } 780 781 /** 782 * Disable NDEF message push over P2P. 783 * 784 * <p>After calling {@link #enableForegroundNdefPush}, an activity 785 * must call this method before its {@link Activity#onPause} callback 786 * completes. 787 * 788 * <p>Strongly recommend to use the new {@link #setNdefPushMessage} 789 * instead: it automatically hooks into your activity life-cycle, 790 * so you do not need to call enable/disable in your onResume/onPause. 791 * 792 * <p>This method must be called from the main thread. 793 * 794 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 795 * 796 * @param activity the Foreground activity 797 * @throws IllegalStateException if the Activity has already been paused 798 * @deprecated use {@link #setNdefPushMessage} instead 799 */ 800 public void disableForegroundNdefPush(Activity activity) { 801 if (activity == null) { 802 throw new NullPointerException(); 803 } 804 enforceResumed(activity); 805 mNfcActivityManager.setNdefPushMessage(activity, null); 806 mNfcActivityManager.setNdefPushMessageCallback(activity, null); 807 mNfcActivityManager.setOnNdefPushCompleteCallback(activity, null); 808 } 809 810 /** 811 * Enable NDEF Push feature. 812 * <p>This API is for the Settings application. 813 * @hide 814 */ 815 public boolean enableNdefPush() { 816 try { 817 return sService.enableNdefPush(); 818 } catch (RemoteException e) { 819 attemptDeadServiceRecovery(e); 820 return false; 821 } 822 } 823 824 /** 825 * Disable NDEF Push feature. 826 * <p>This API is for the Settings application. 827 * @hide 828 */ 829 public boolean disableNdefPush() { 830 try { 831 return sService.disableNdefPush(); 832 } catch (RemoteException e) { 833 attemptDeadServiceRecovery(e); 834 return false; 835 } 836 } 837 838 /** 839 * Return true if the NDEF Push (Android Beam) feature is enabled. 840 * <p>This function will return true only if both NFC is enabled, and the 841 * NDEF Push feature is enabled. 842 * <p>Note that if NFC is enabled but NDEF Push is disabled then this 843 * device can still <i>receive</i> NDEF messages, it just cannot send them. 844 * <p>Applications cannot directly toggle the NDEF Push feature, but they 845 * can request Settings UI allowing the user to toggle NDEF Push using 846 * <code>startActivity(new Intent(Settings.ACTION_NFCSHARING_SETTINGS))</code> 847 * <p>Example usage in an Activity that requires NDEF Push: 848 * <p><pre> 849 * protected void onResume() { 850 * super.onResume(); 851 * if (!nfcAdapter.isEnabled()) { 852 * startActivity(new Intent(Settings.ACTION_NFC_SETTINGS)); 853 * } else if (!nfcAdapter.isNdefPushEnabled()) { 854 * startActivity(new Intent(Settings.ACTION_NFCSHARING_SETTINGS)); 855 * } 856 * } 857 * </pre> 858 * 859 * @see android.provider.Settings#ACTION_NFCSHARING_SETTINGS 860 * @return true if NDEF Push feature is enabled 861 */ 862 public boolean isNdefPushEnabled() { 863 try { 864 return sService.isNdefPushEnabled(); 865 } catch (RemoteException e) { 866 attemptDeadServiceRecovery(e); 867 return false; 868 } 869 } 870 871 /** 872 * @hide 873 */ 874 public INfcAdapterExtras getNfcAdapterExtrasInterface() { 875 if (mContext == null) { 876 throw new UnsupportedOperationException("You need a context on NfcAdapter to use the " 877 + " NFC extras APIs"); 878 } 879 try { 880 return sService.getNfcAdapterExtrasInterface(mContext.getPackageName()); 881 } catch (RemoteException e) { 882 attemptDeadServiceRecovery(e); 883 return null; 884 } 885 } 886 887 void enforceResumed(Activity activity) { 888 if (!activity.isResumed()) { 889 throw new IllegalStateException("API cannot be called while activity is paused"); 890 } 891 } 892} 893