Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Nested Classes](https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#nestedclasses) \| [Constants](https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#constants) \| [Methods](https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#inhmethods) # CardEmulation *** ** * ** *** ` public final class CardEmulation ` ` extends https://developer.android.com/reference/java/lang/Object ` ` ` |---|---| | [java.lang.Object](https://developer.android.com/reference/java/lang/Object) || | ↳ | android.nfc.cardemulation.CardEmulation |
*** ** * ** *** This class can be used to query the state of NFC card emulation services. For a general introduction into NFC card emulation, please read the [NFC card emulation developer guide](https://developer.android.com/guide/topics/connectivity/nfc/hce). Use of this class requires the `https://developer.android.com/reference/android/content/pm/PackageManager#FEATURE_NFC_HOST_CARD_EMULATION` to be present on the device. ## Summary | ### Nested classes || |---|---| | ` interface` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.NfcEventCallback` Callback interface for NFC-related events. | | ### Constants || |---|---| | `https://developer.android.com/reference/java/lang/String` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#ACTION_CHANGE_DEFAULT` *This constant was deprecated in API level 35. Please use `https://developer.android.com/reference/android/app/role/RoleManager#createRequestRoleIntent(java.lang.String)` with `https://developer.android.com/reference/android/app/role/RoleManager#ROLE_WALLET` parameter and `https://developer.android.com/reference/android/app/Activity#startActivityForResult(android.content.Intent,%20int)` instead.* | | `https://developer.android.com/reference/java/lang/String` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#CATEGORY_OTHER` Category that can be used for all other card emulation services. | | `https://developer.android.com/reference/java/lang/String` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#CATEGORY_PAYMENT` Category used for NFC payment services. | | `https://developer.android.com/reference/java/lang/String` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#EXTRA_CATEGORY` The category extra for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#ACTION_CHANGE_DEFAULT`. | | `https://developer.android.com/reference/java/lang/String` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#EXTRA_SERVICE_COMPONENT` The service `https://developer.android.com/reference/android/content/ComponentName` object passed in as an extra for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#ACTION_CHANGE_DEFAULT`. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#NFC_INTERNAL_ERROR_COMMAND_TIMEOUT` This error is reported when the NFC stack times out while waiting for a response to a command sent to the NFC hardware. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#NFC_INTERNAL_ERROR_NFC_CRASH_RESTART` This error is reported when the NFC command watchdog restarts the NFC stack. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#NFC_INTERNAL_ERROR_NFC_HARDWARE_ERROR` This error is reported when the NFC controller does not respond or there's an NCI transport error. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#NFC_INTERNAL_ERROR_UNKNOWN` | | `https://developer.android.com/reference/java/lang/String` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#PROPERTY_ALLOW_SHARED_ROLE_PRIORITY` Property name used to indicate that an application wants to allow associated services to share the same AID routing priority when this application is the role holder. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#PROTOCOL_AND_TECHNOLOGY_ROUTE_DEFAULT` Route to the default value in config file. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#PROTOCOL_AND_TECHNOLOGY_ROUTE_DH` Route to Device Host (DH). | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#PROTOCOL_AND_TECHNOLOGY_ROUTE_ESE` Route to eSE. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#PROTOCOL_AND_TECHNOLOGY_ROUTE_NDEF_NFCEE` Route to T4T NDEF-NCEE emulation. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#PROTOCOL_AND_TECHNOLOGY_ROUTE_UICC` Route to UICC. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#PROTOCOL_AND_TECHNOLOGY_ROUTE_UNSET` Route unset. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_ALWAYS_ASK` Return value for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getSelectionModeForCategory(java.lang.String)`. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_ASK_IF_CONFLICT` Return value for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getSelectionModeForCategory(java.lang.String)`. | | `int` | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_PREFER_DEFAULT` Return value for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getSelectionModeForCategory(java.lang.String)`. | | ### Public methods || |---|---| | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#categoryAllowsForegroundPreference(java.lang.String)(https://developer.android.com/reference/java/lang/String category) `
Returns whether the user has allowed AIDs registered in the specified category to be handled by a service that is preferred by the foreground application, instead of by a pre-configured default. | | ` https://developer.android.com/reference/java/util/List` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getAidsForPreferredPaymentService()() ` Retrieves the registered AIDs for the preferred payment service. | | ` https://developer.android.com/reference/java/util/List` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getAidsForService(android.content.ComponentName,%20java.lang.String)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String category) ` Retrieves the currently registered AIDs for the specified category for a service. | | ` int` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getDefaultNfcSubscriptionId()() ` Returns the system's default NFC subscription id. | | ` https://developer.android.com/reference/java/lang/CharSequence` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getDescriptionForPreferredPaymentService()() ` Returns a user-visible description of the preferred payment service. | | ` static https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getInstance(android.nfc.NfcAdapter)(https://developer.android.com/reference/android/nfc/NfcAdapter adapter) ` Helper to get an instance of this class. | | ` https://developer.android.com/reference/java/util/List` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getPollingLoopFiltersForService(android.content.ComponentName)(https://developer.android.com/reference/android/content/ComponentName service) ` Retrieve all the polling loop filters registered for a `https://developer.android.com/reference/android/nfc/cardemulation/HostApduService`. | | ` https://developer.android.com/reference/java/util/List` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getPollingLoopPatternFiltersForService(android.content.ComponentName)(https://developer.android.com/reference/android/content/ComponentName service) ` Retrieve all the polling loop pattern filters registered for a `https://developer.android.com/reference/android/nfc/cardemulation/HostApduService`. | | ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getRouteDestinationForPreferredPaymentService()() ` Retrieves the route destination for the preferred payment service. | | ` int` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getSelectionModeForCategory(java.lang.String)(https://developer.android.com/reference/java/lang/String category) ` Returns the service selection mode for the passed in category. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#isDefaultServiceForAid(android.content.ComponentName,%20java.lang.String)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String aid) ` Allows an application to query whether a service is currently the default handler for a specified ISO7816-4 Application ID. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#isDefaultServiceForCategory(android.content.ComponentName,%20java.lang.String)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String category) ` Allows an application to query whether a service is currently the default service to handle a card emulation category. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#isDeviceScreenOnRequiredForService(android.content.ComponentName)(https://developer.android.com/reference/android/content/ComponentName service) ` Checks whether the device must have its screen on for the service to be activated. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#isDeviceUnlockRequiredForService(android.content.ComponentName)(https://developer.android.com/reference/android/content/ComponentName service) ` Checks whether the device must be unlocked for the service to be activated. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#isEuiccSupported()() ` Is EUICC supported as a Secure Element EE which supports off host card emulation. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerAidsForService(android.content.ComponentName,%20java.lang.String,%20java.util.List)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String category, https://developer.android.com/reference/java/util/List aids) ` Registers a list of AIDs for a specific category for the specified service. | | ` void` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerNfcEventCallback(java.util.concurrent.Executor,%20android.nfc.cardemulation.CardEmulation.NfcEventCallback)(https://developer.android.com/reference/java/util/concurrent/Executor executor, https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.NfcEventCallback callback) ` Register a callback for NFC events. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerPollingLoopFilterForService(android.content.ComponentName,%20java.lang.String,%20boolean)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String pollingLoopFilter, boolean autoTransact) ` Register a polling loop filter (PLF) for a HostApduService and indicate whether it should auto-transact or not. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerPollingLoopPatternFilterForService(android.content.ComponentName,%20java.lang.String,%20boolean)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String pollingLoopPatternFilter, boolean autoTransact) ` Register a polling loop pattern filter (PLPF) for a HostApduService and indicate whether it should auto-transact or not. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#removeAidsForService(android.content.ComponentName,%20java.lang.String)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String category) ` Removes a previously registered list of AIDs for the specified category for the service provided. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#removePollingLoopFilterForService(android.content.ComponentName,%20java.lang.String)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String pollingLoopFilter) ` Unregister a polling loop filter (PLF) for a HostApduService. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#removePollingLoopPatternFilterForService(android.content.ComponentName,%20java.lang.String)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String pollingLoopPatternFilter) ` Unregister a polling loop pattern filter (PLPF) for a HostApduService. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#setOffHostForService(android.content.ComponentName,%20java.lang.String)(https://developer.android.com/reference/android/content/ComponentName service, https://developer.android.com/reference/java/lang/String offHostSecureElement) ` Sets the off-host Secure Element for the given service. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#setPreferredService(android.app.Activity,%20android.content.ComponentName)(https://developer.android.com/reference/android/app/Activity activity, https://developer.android.com/reference/android/content/ComponentName service) ` Allows a foreground application to specify which card emulation service should be preferred while a specific Activity is in the foreground. | | ` void` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#setRequireDeviceScreenOnForService(android.content.ComponentName,%20boolean)(https://developer.android.com/reference/android/content/ComponentName service, boolean enable) ` Sets whether the device must have its screen on for the service to be activated. | | ` void` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#setRequireDeviceUnlockForService(android.content.ComponentName,%20boolean)(https://developer.android.com/reference/android/content/ComponentName service, boolean enable) ` Sets whether the device must be unlocked for the service to be activated. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#setShouldDefaultToObserveModeForService(android.content.ComponentName,%20boolean)(https://developer.android.com/reference/android/content/ComponentName service, boolean enable) ` Sets whether when this service becomes the preferred service, if the NFC stack should enable observe mode or disable observe mode. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#supportsAidPrefixRegistration()() ` Some devices may allow an application to register all AIDs that starts with a certain prefix, e.g. | | ` void` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#unregisterNfcEventCallback(android.nfc.cardemulation.CardEmulation.NfcEventCallback)(https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation.NfcEventCallback callback) ` Unregister an NFC event callback that was previously registered with `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerNfcEventCallback(java.util.concurrent.Executor,%20android.nfc.cardemulation.CardEmulation.NfcEventCallback)`. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#unsetOffHostForService(android.content.ComponentName)(https://developer.android.com/reference/android/content/ComponentName service) ` Unsets the off-host Secure Element for the given service. | | ` boolean` | ` https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#unsetPreferredService(android.app.Activity)(https://developer.android.com/reference/android/app/Activity activity) ` Unsets the preferred service for the specified Activity. | | ### Inherited methods | |---|---| | From class ` https://developer.android.com/reference/java/lang/Object ` |---|---| | ` https://developer.android.com/reference/java/lang/Object` | ` https://developer.android.com/reference/java/lang/Object#clone()() ` Creates and returns a copy of this object. | | ` boolean` | ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` https://developer.android.com/reference/java/lang/Object#finalize()() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final https://developer.android.com/reference/java/lang/Class` | ` https://developer.android.com/reference/java/lang/Object#getClass()() ` Returns the runtime class of this `Object`. | | ` int` | ` https://developer.android.com/reference/java/lang/Object#hashCode()() ` Returns a hash code value for the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notify()() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notifyAll()() ` Wakes up all threads that are waiting on this object's monitor. | | ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/lang/Object#toString()() ` Returns a string representation of the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait()() ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*. | || ## Constants ### ACTION_CHANGE_DEFAULT Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Deprecated in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final String ACTION_CHANGE_DEFAULT ``` **This constant was deprecated in API level 35.** Please use `https://developer.android.com/reference/android/app/role/RoleManager#createRequestRoleIntent(java.lang.String)` with `https://developer.android.com/reference/android/app/role/RoleManager#ROLE_WALLET` parameter and `https://developer.android.com/reference/android/app/Activity#startActivityForResult(android.content.Intent,%20int)` instead. Activity action: ask the user to change the default card emulation service for a certain category. This will show a dialog that asks the user whether they want to replace the current default service with the service identified with the ComponentName specified in `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#EXTRA_SERVICE_COMPONENT`, for the category specified in `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#EXTRA_CATEGORY`. There is an optional extra field using `https://developer.android.com/reference/android/content/Intent#EXTRA_USER` to specify the `https://developer.android.com/reference/android/os/UserHandle` of the user that owns the app.
Constant Value: "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT" ### CATEGORY_OTHER Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final String CATEGORY_OTHER ``` Category that can be used for all other card emulation services.
Constant Value: "other" ### CATEGORY_PAYMENT Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final String CATEGORY_PAYMENT ``` Category used for NFC payment services.
Constant Value: "payment" ### EXTRA_CATEGORY Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final String EXTRA_CATEGORY ``` The category extra for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#ACTION_CHANGE_DEFAULT`.
**See also:** - `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#ACTION_CHANGE_DEFAULT` Constant Value: "category" ### EXTRA_SERVICE_COMPONENT Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final String EXTRA_SERVICE_COMPONENT ``` The service `https://developer.android.com/reference/android/content/ComponentName` object passed in as an extra for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#ACTION_CHANGE_DEFAULT`.
**See also:** - `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#ACTION_CHANGE_DEFAULT` Constant Value: "component" ### NFC_INTERNAL_ERROR_COMMAND_TIMEOUT Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int NFC_INTERNAL_ERROR_COMMAND_TIMEOUT ``` This error is reported when the NFC stack times out while waiting for a response to a command sent to the NFC hardware.
Constant Value: 3 (0x00000003) ### NFC_INTERNAL_ERROR_NFC_CRASH_RESTART Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int NFC_INTERNAL_ERROR_NFC_CRASH_RESTART ``` This error is reported when the NFC command watchdog restarts the NFC stack.
Constant Value: 1 (0x00000001) ### NFC_INTERNAL_ERROR_NFC_HARDWARE_ERROR Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int NFC_INTERNAL_ERROR_NFC_HARDWARE_ERROR ``` This error is reported when the NFC controller does not respond or there's an NCI transport error.
Constant Value: 2 (0x00000002) ### NFC_INTERNAL_ERROR_UNKNOWN Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int NFC_INTERNAL_ERROR_UNKNOWN ```

Constant Value: 0 (0x00000000) ### PROPERTY_ALLOW_SHARED_ROLE_PRIORITY Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final String PROPERTY_ALLOW_SHARED_ROLE_PRIORITY ``` Property name used to indicate that an application wants to allow associated services to share the same AID routing priority when this application is the role holder. Wallet role holder can either: - Set "android:value" to "true". This will allow any package signed by the same certificate to request for role holder priority. - Set "android:value" to some other package name. This will only allow this package to request for role holder priority (can be signed by different certificates). - Example: ... ... - Constant Value: "android.nfc.cardemulation.PROPERTY_ALLOW_SHARED_ROLE_PRIORITY" ### PROTOCOL_AND_TECHNOLOGY_ROUTE_DEFAULT Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int PROTOCOL_AND_TECHNOLOGY_ROUTE_DEFAULT ``` Route to the default value in config file.
Constant Value: 3 (0x00000003) ### PROTOCOL_AND_TECHNOLOGY_ROUTE_DH Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int PROTOCOL_AND_TECHNOLOGY_ROUTE_DH ``` Route to Device Host (DH).
Constant Value: 0 (0x00000000) ### PROTOCOL_AND_TECHNOLOGY_ROUTE_ESE Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int PROTOCOL_AND_TECHNOLOGY_ROUTE_ESE ``` Route to eSE.
Constant Value: 1 (0x00000001) ### PROTOCOL_AND_TECHNOLOGY_ROUTE_NDEF_NFCEE Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions) ``` public static final int PROTOCOL_AND_TECHNOLOGY_ROUTE_NDEF_NFCEE ``` Route to T4T NDEF-NCEE emulation.
**See also:** - `https://developer.android.com/` Constant Value: 4 (0x00000004) ### PROTOCOL_AND_TECHNOLOGY_ROUTE_UICC Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int PROTOCOL_AND_TECHNOLOGY_ROUTE_UICC ``` Route to UICC.
Constant Value: 2 (0x00000002) ### PROTOCOL_AND_TECHNOLOGY_ROUTE_UNSET Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int PROTOCOL_AND_TECHNOLOGY_ROUTE_UNSET ``` Route unset.
Constant Value: -1 (0xffffffff) ### SELECTION_MODE_ALWAYS_ASK Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int SELECTION_MODE_ALWAYS_ASK ``` Return value for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getSelectionModeForCategory(java.lang.String)`. In this mode, when using ISO-DEP card emulation with `https://developer.android.com/reference/android/nfc/cardemulation/HostApduService` or `https://developer.android.com/reference/android/nfc/cardemulation/OffHostApduService`, whenever an Application ID (AID) of this category is selected, the user is asked which service they want to use to handle the transaction, even if there is only one matching service.
Constant Value: 1 (0x00000001) ### SELECTION_MODE_ASK_IF_CONFLICT Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int SELECTION_MODE_ASK_IF_CONFLICT ``` Return value for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getSelectionModeForCategory(java.lang.String)`. In this mode, when using ISO-DEP card emulation with `https://developer.android.com/reference/android/nfc/cardemulation/HostApduService` or `https://developer.android.com/reference/android/nfc/cardemulation/OffHostApduService`, the user will only be asked to select a service if the Application ID (AID) selected by the reader has been registered by multiple services. If there is only one service that has registered for the AID, that service will be invoked directly.
Constant Value: 2 (0x00000002) ### SELECTION_MODE_PREFER_DEFAULT Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static final int SELECTION_MODE_PREFER_DEFAULT ``` Return value for `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getSelectionModeForCategory(java.lang.String)`. In this mode, the user has set a default service for this category. When using ISO-DEP card emulation with `https://developer.android.com/reference/android/nfc/cardemulation/HostApduService` or `https://developer.android.com/reference/android/nfc/cardemulation/OffHostApduService`, if a remote NFC device selects any of the Application IDs (AIDs) that the default service has registered in this category, that service will automatically be bound to to handle the transaction.
Constant Value: 0 (0x00000000) ## Public methods ### categoryAllowsForegroundPreference Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean categoryAllowsForegroundPreference (String category) ```
Returns whether the user has allowed AIDs registered in the specified category to be handled by a service that is preferred by the foreground application, instead of by a pre-configured default. Foreground applications can set such preferences using the `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#setPreferredService(android.app.Activity,%20android.content.ComponentName)` method. Starting with `https://developer.android.com/reference/android/os/Build.VERSION_CODES#VANILLA_ICE_CREAM`, this method will always return true.
| Parameters || |---|---| | `category` | `String`: The category, e.g. `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#CATEGORY_PAYMENT`
| | Returns || |---|---| | `boolean` | whether AIDs in the category can be handled by a service specified by the foreground app.
| ### getAidsForPreferredPaymentService Added in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public List getAidsForPreferredPaymentService () ``` Retrieves the registered AIDs for the preferred payment service. Requires `https://developer.android.com/reference/android/Manifest.permission#NFC_PREFERRED_PAYMENT_INFO`
| Returns || |---|---| | `https://developer.android.com/reference/java/util/List` | The list of AIDs registered for this category, or null if it couldn't be found.
| ### getAidsForService Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public List getAidsForService (ComponentName service, String category) ``` Retrieves the currently registered AIDs for the specified category for a service. Note that this will only return AIDs that were dynamically registered using `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerAidsForService(android.content.ComponentName,%20java.lang.String,%20java.util.List)` method. It will \*not\* return AIDs that were statically registered in the manifest.
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service
| | `category` | `String`: The category for which the AIDs were registered, e.g. `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#CATEGORY_PAYMENT`
| | Returns || |---|---| | `https://developer.android.com/reference/java/util/List` | The list of AIDs registered for this category, or null if it couldn't be found.
| ### getDefaultNfcSubscriptionId Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public int getDefaultNfcSubscriptionId () ``` Returns the system's default NFC subscription id. For devices with multiple UICC/EUICC that is configured to be NFCEE, this returns the default UICC NFCEE that will handle NFC offhost CE transactions If the device has no UICC that can serve as NFCEE, this will return `https://developer.android.com/reference/android/telephony/SubscriptionManager#INVALID_SUBSCRIPTION_ID`. . Requires the `https://developer.android.com/reference/android/content/pm/PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION` feature which can be detected using `https://developer.android.com/reference/android/content/pm/PackageManager#hasSystemFeature(java.lang.String)`.

| Returns || |---|---| | `int` | the default NFC subscription Id if set, `https://developer.android.com/reference/android/telephony/SubscriptionManager#INVALID_SUBSCRIPTION_ID` otherwise.
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | If the device does not have `https://developer.android.com/reference/android/content/pm/PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION`. | ### getDescriptionForPreferredPaymentService Added in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public CharSequence getDescriptionForPreferredPaymentService () ``` Returns a user-visible description of the preferred payment service. Starting with `https://developer.android.com/reference/android/os/Build.VERSION_CODES#VANILLA_ICE_CREAM`, the preferred payment service no longer exists and is replaced by `https://developer.android.com/reference/android/app/role/RoleManager#ROLE_WALLET`. This will return the description for one of the services registered by the role holder (if any). If there are multiple services registered, it is unspecified which of those will be used to obtain the service description here. Requires `https://developer.android.com/reference/android/Manifest.permission#NFC_PREFERRED_PAYMENT_INFO`
| Returns || |---|---| | `https://developer.android.com/reference/java/lang/CharSequence` | the preferred payment service description. This value may be `null`.
| ### getInstance Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public static CardEmulation getInstance (NfcAdapter adapter) ``` Helper to get an instance of this class.
| Parameters || |---|---| | `adapter` | `NfcAdapter`: A reference to an NfcAdapter object.
| | Returns || |---|---| | `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation` |
| ### getPollingLoopFiltersForService Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions) ``` public List getPollingLoopFiltersForService (ComponentName service) ``` Retrieve all the polling loop filters registered for a `https://developer.android.com/reference/android/nfc/cardemulation/HostApduService`.
| Parameters || |---|---| | `service` | `ComponentName`: The HostApduService to retrieve the filter for. This value cannot be `null`.
| | Returns || |---|---| | `https://developer.android.com/reference/java/util/List` | List of polling loop filters, will be empty if there are none registered. This value cannot be `null`.
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the service is not valid. | **See also:** - `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerPollingLoopFilterForService(android.content.ComponentName,%20java.lang.String,%20boolean)` ### getPollingLoopPatternFiltersForService Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions) ``` public List getPollingLoopPatternFiltersForService (ComponentName service) ``` Retrieve all the polling loop pattern filters registered for a `https://developer.android.com/reference/android/nfc/cardemulation/HostApduService`.
| Parameters || |---|---| | `service` | `ComponentName`: The HostApduService to retrieve the filter for. This value cannot be `null`.
| | Returns || |---|---| | `https://developer.android.com/reference/java/util/List` | List of polling loop pattern filters, will be empty if there are none registered. This value cannot be `null`.
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the service is not valid. | **See also:** - `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerPollingLoopPatternFilterForService(android.content.ComponentName,%20java.lang.String,%20boolean)` ### getRouteDestinationForPreferredPaymentService Added in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public String getRouteDestinationForPreferredPaymentService () ``` Retrieves the route destination for the preferred payment service. Starting with `https://developer.android.com/reference/android/os/Build.VERSION_CODES#VANILLA_ICE_CREAM`, the preferred payment service no longer exists and is replaced by `https://developer.android.com/reference/android/app/role/RoleManager#ROLE_WALLET`. This will return the route for one of the services registered by the role holder (if any). If there are multiple services registered, it is unspecified which of those will be used to determine the route. Requires `https://developer.android.com/reference/android/Manifest.permission#NFC_PREFERRED_PAYMENT_INFO`
| Returns || |---|---| | `https://developer.android.com/reference/java/lang/String` | The route destination secure element name of the preferred payment service. HCE payment: "Host" OffHost payment: 1. String with prefix SIM or prefix eSE string. Ref: GSMA TS.26 - NFC Handset Requirements TS26_NFC_REQ_069: For UICC, Secure Element Name SHALL be SIM\[smartcard slot\] (e.g. SIM/SIM1, SIM2\\u2026 SIMn). TS26_NFC_REQ_070: For embedded SE, Secure Element Name SHALL be eSE\[number\] (e.g. eSE/eSE1, eSE2, etc.). 2. "OffHost" if the payment service does not specify secure element name. This value may be `null`.
| ### getSelectionModeForCategory Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public int getSelectionModeForCategory (String category) ``` Returns the service selection mode for the passed in category. Valid return values are: `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_PREFER_DEFAULT` the user has requested a default service for this category, which will be preferred. `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_ALWAYS_ASK` the user has requested to be asked every time what service they would like to use in this category. `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_ASK_IF_CONFLICT` the user will only be asked to pick a service if there is a conflict. Starting with `https://developer.android.com/reference/android/os/Build.VERSION_CODES#VANILLA_ICE_CREAM`, the default service defined by the holder of `https://developer.android.com/reference/android/app/role/RoleManager#ROLE_WALLET` and is category agnostic.
| Parameters || |---|---| | `category` | `String`: The category, for example `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#CATEGORY_PAYMENT`
| | Returns || |---|---| | `int` | the selection mode for the passed in category
| ### isDefaultServiceForAid Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean isDefaultServiceForAid (ComponentName service, String aid) ``` Allows an application to query whether a service is currently the default handler for a specified ISO7816-4 Application ID.
| Parameters || |---|---| | `service` | `ComponentName`: The ComponentName of the service
| | `aid` | `String`: The ISO7816-4 Application ID
| | Returns || |---|---| | `boolean` | whether the service is the default handler for the specified AID Requires the `https://developer.android.com/reference/android/Manifest.permission#NFC` permission. | ### isDefaultServiceForCategory Added in [API level 19](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean isDefaultServiceForCategory (ComponentName service, String category) ``` Allows an application to query whether a service is currently the default service to handle a card emulation category. Note that if `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#getSelectionModeForCategory(java.lang.String)` returns `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_ALWAYS_ASK` or `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_ASK_IF_CONFLICT`, this method will always return false. That is because in these selection modes a default can't be set at the category level. For categories where the selection mode is `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_ALWAYS_ASK` or `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#SELECTION_MODE_ASK_IF_CONFLICT`, use `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#isDefaultServiceForAid(android.content.ComponentName,%20java.lang.String)` to determine whether a service is the default for a specific AID.
| Parameters || |---|---| | `service` | `ComponentName`: The ComponentName of the service
| | `category` | `String`: The category
| | Returns || |---|---| | `boolean` | whether service is currently the default service for the category. Requires the `https://developer.android.com/reference/android/Manifest.permission#NFC` permission. | ### isDeviceScreenOnRequiredForService Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions) ``` public boolean isDeviceScreenOnRequiredForService (ComponentName service) ``` Checks whether the device must have its screen on for the service to be activated.
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service. This value cannot be `null`.
| | Returns || |---|---| | `boolean` | True if the device must have its screen on for the service to be activated, false otherwise
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | If the provided service has not been registered | ### isDeviceUnlockRequiredForService Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions) ``` public boolean isDeviceUnlockRequiredForService (ComponentName service) ``` Checks whether the device must be unlocked for the service to be activated.
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service. This value cannot be `null`.
| | Returns || |---|---| | `boolean` | True if the device must be unlocked for the service to be activated, false otherwise
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | If the provided service has not been registered | ### isEuiccSupported Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean isEuiccSupported () ``` Is EUICC supported as a Secure Element EE which supports off host card emulation.
| Returns || |---|---| | `boolean` | true if the device supports EUICC for off host card emulation, false otherwise.
| ### registerAidsForService Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean registerAidsForService (ComponentName service, String category, List aids) ``` Registers a list of AIDs for a specific category for the specified service. If a list of AIDs for that category was previously registered for this service (either statically through the manifest, or dynamically by using this API), that list of AIDs will be replaced with this one. Note that you can only register AIDs for a service that is running under the same UID as the caller of this API. Typically this means you need to call this from the same package as the service itself, though UIDs can also be shared between packages using shared UIDs.
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service
| | `category` | `String`: The category of AIDs to be registered
| | `aids` | `List`: A list containing the AIDs to be registered
| | Returns || |---|---| | `boolean` | whether the registration was successful.
| ### registerNfcEventCallback Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public void registerNfcEventCallback (Executor executor, CardEmulation.NfcEventCallback callback) ``` Register a callback for NFC events.
| Parameters || |---|---| | `executor` | `Executor`: The Executor to run the call back with. This value cannot be `null`. Callback and listener events are dispatched through this `https://developer.android.com/reference/java/util/concurrent/Executor`, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use `https://developer.android.com/reference/android/content/Context#getMainExecutor()`. Otherwise, provide an `https://developer.android.com/reference/java/util/concurrent/Executor` that dispatches to an appropriate thread.
| | `callback` | `CardEmulation.NfcEventCallback`: The callback to register. This value cannot be `null`.
| ### registerPollingLoopFilterForService Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean registerPollingLoopFilterForService (ComponentName service, String pollingLoopFilter, boolean autoTransact) ``` Register a polling loop filter (PLF) for a HostApduService and indicate whether it should auto-transact or not. The PLF can be sequence of an even number of at least 2 hexadecimal numbers (0-9, A-F or a-f), representing a series of bytes. When non-standard polling loop frame matches this sequence exactly, it may be delivered to `https://developer.android.com/reference/android/nfc/cardemulation/HostApduService#processPollingFrames(java.util.List)`. If auto-transact is set to true and this service is currently preferred or there are no other services registered for this filter then observe mode will also be disabled. When auto-transact is set to true, if the filter matches the following requirements, it will be considered to be included in the firmware filtering list (if the device supports exit frames). Filters not matching these requirements will be handled via the NFC stack software auto-transact functionality. - The filter must not exceed 16 bytes (32 hexadecimal characters).

| Parameters || |---|---| | `service` | `ComponentName`: The HostApduService to register the filter for. This value cannot be `null`.
| | `pollingLoopFilter` | `String`: The filter to register. This value cannot be `null`.
| | `autoTransact` | `boolean`: true to have the NFC stack automatically disable observe mode and allow transactions to proceed when this filter matches, false otherwise
| | Returns || |---|---| | `boolean` | true if the filter was registered, false otherwise
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the passed in string doesn't parse to at least one byte | ### registerPollingLoopPatternFilterForService Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean registerPollingLoopPatternFilterForService (ComponentName service, String pollingLoopPatternFilter, boolean autoTransact) ``` Register a polling loop pattern filter (PLPF) for a HostApduService and indicate whether it should auto-transact or not. The pattern may include the characters 0-9 and A-F as well as the regular expression operators \`.\`, \`?\` and \`\*\` after the first byte. When the beginning of a non-standard polling loop frame matches this sequence exactly, it may be delivered to `https://developer.android.com/reference/android/nfc/cardemulation/HostApduService#processPollingFrames(java.util.List)`. If auto-transact is set to true and this service is currently preferred or there are no other services registered for this filter then observe mode will also be disabled. When auto-transact is set to true, if the pattern matches the following requirements, it will be considered to be included in the firmware filtering list (if the device supports exit frames). Patterns not matching these requirements will be handled via the NFC stack software auto-transact functionality. - The pattern must not include the \`?\` operator. - The \`\*\` operator is only supported if it is the only character or if it is preceded by a \`.\` and is at the end of the pattern (e.g. \`.\*\`). - The pattern must have an even number of characters unless it ends with the \`.\*\` suffix. - The pattern must not exceed 32 characters (excluding the \`.\*\` suffix).

| Parameters || |---|---| | `service` | `ComponentName`: The HostApduService to register the filter for. This value cannot be `null`.
| | `pollingLoopPatternFilter` | `String`: The pattern filter to register, must to be compatible with `https://developer.android.com/reference/java/util/regex/Pattern#compile(java.lang.String)` and only contain hexadecimal numbers and \`.\`, \`?\` and \`\*\` operators. This value cannot be `null`.
| | `autoTransact` | `boolean`: true to have the NFC stack automatically disable observe mode and allow transactions to proceed when this filter matches, false otherwise
| | Returns || |---|---| | `boolean` | true if the filter was registered, false otherwise
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the filter contains elements other than hexadecimal numbers and \`.\`, \`?\` and \`\*\` operators | | `https://developer.android.com/reference/java/util/regex/PatternSyntaxException` | if the regex syntax is invalid | ### removeAidsForService Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean removeAidsForService (ComponentName service, String category) ``` Removes a previously registered list of AIDs for the specified category for the service provided. Note that this will only remove AIDs that were dynamically registered using the `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerAidsForService(android.content.ComponentName,%20java.lang.String,%20java.util.List)` method. It will \*not\* remove AIDs that were statically registered in the manifest. If dynamically registered AIDs are removed using this method, and a statically registered AID group for the same category exists in the manifest, the static AID group will become active again.
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service
| | `category` | `String`: The category of the AIDs to be removed, e.g. `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#CATEGORY_PAYMENT`
| | Returns || |---|---| | `boolean` | whether the group was successfully removed.
| ### removePollingLoopFilterForService Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean removePollingLoopFilterForService (ComponentName service, String pollingLoopFilter) ``` Unregister a polling loop filter (PLF) for a HostApduService. If the PLF had previously been registered via `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerPollingLoopFilterForService(android.content.ComponentName,%20java.lang.String,%20boolean)` for this service it will be removed.
| Parameters || |---|---| | `service` | `ComponentName`: The HostApduService to unregister the filter for. This value cannot be `null`.
| | `pollingLoopFilter` | `String`: The filter to unregister. This value cannot be `null`.
| | Returns || |---|---| | `boolean` | true if the filter was removed, false otherwise
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the passed in string doesn't parse to at least one byte | ### removePollingLoopPatternFilterForService Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean removePollingLoopPatternFilterForService (ComponentName service, String pollingLoopPatternFilter) ``` Unregister a polling loop pattern filter (PLPF) for a HostApduService. If the PLF had previously been registered via `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerPollingLoopFilterForService(android.content.ComponentName,%20java.lang.String,%20boolean)` for this service it will be removed.
| Parameters || |---|---| | `service` | `ComponentName`: The HostApduService to unregister the filter for. This value cannot be `null`.
| | `pollingLoopPatternFilter` | `String`: The filter to unregister, must to be compatible with `https://developer.android.com/reference/java/util/regex/Pattern#compile(java.lang.String)` and only contain hexadecimal numbers and\`.\`, \`?\` and \`\*\` operators. This value cannot be `null`.
| | Returns || |---|---| | `boolean` | true if the filter was removed, false otherwise
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the filter containst elements other than hexadecimal numbers and \`.\`, \`?\` and \`\*\` operators | | `https://developer.android.com/reference/java/util/regex/PatternSyntaxException` | if the regex syntax is invalid | ### setOffHostForService Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean setOffHostForService (ComponentName service, String offHostSecureElement) ``` Sets the off-host Secure Element for the given service. If off-host SE was initially set (either statically through the manifest, or dynamically by using this API), it will be replaced with this one. All AIDs registered by this service will be re-routed to this Secure Element if successful. AIDs that was statically assigned using manifest will re-route to off-host SE that stated in manifest after NFC toggle. Note that you can only set off-host SE for a service that is running under the same UID as the caller of this API. Typically this means you need to call this from the same package as the service itself, though UIDs can also be shared between packages using shared UIDs. Registeration will be successful only if the Secure Element exists on the device. Requires `https://developer.android.com/reference/android/Manifest.permission#NFC`
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service. This value cannot be `null`.
| | `offHostSecureElement` | `String`: Secure Element to register the AID to. Only accept strings with prefix SIM or prefix eSE. Ref: GSMA TS.26 - NFC Handset Requirements TS26_NFC_REQ_069: For UICC, Secure Element Name SHALL be SIM\[smartcard slot\] (e.g. SIM/SIM1, SIM2\\u2026 SIMn). TS26_NFC_REQ_070: For embedded SE, Secure Element Name SHALL be eSE\[number\] (e.g. eSE/eSE1, eSE2, etc.). This value cannot be `null`.
| | Returns || |---|---| | `boolean` | whether the registration was successful. This value cannot be `null`.
| ### setPreferredService Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean setPreferredService (Activity activity, ComponentName service) ``` Allows a foreground application to specify which card emulation service should be preferred while a specific Activity is in the foreground. The specified Activity must currently be in resumed state. A good paradigm is to call this method in your `https://developer.android.com/reference/android/app/Activity#onResume()`, and to call `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#unsetPreferredService(android.app.Activity)` in your `https://developer.android.com/reference/android/app/Activity#onPause()`. This method call will fail in two specific scenarios: - If the service registers one or more AIDs in the `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#CATEGORY_PAYMENT` category, but the user has indicated that foreground apps are not allowed to override the default payment service. - If the service registers one or more AIDs in the `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#CATEGORY_OTHER` category that are also handled by the default payment service, and the user has indicated that foreground apps are not allowed to override the default payment service. Use `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#categoryAllowsForegroundPreference(java.lang.String)` to determine whether foreground apps can override the default payment service. Note that this preference is not persisted by the OS, and hence must be called every time the Activity is resumed. Starting with `https://developer.android.com/reference/android/os/Build.VERSION_CODES#CINNAMON_BUN`, this method will prefer all services matching the package name of the activity.
| Parameters || |---|---| | `activity` | `Activity`: The activity which prefers this service to be invoked
| | `service` | `ComponentName`: The service to be preferred while this activity is in the foreground
| | Returns || |---|---| | `boolean` | whether the registration was successful
| ### setRequireDeviceScreenOnForService Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions) ``` public void setRequireDeviceScreenOnForService (ComponentName service, boolean enable) ``` Sets whether the device must have its screen on for the service to be activated. This API overrides the `android:requireDeviceScreenOn` attribute declared in the service's manifest.
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service. This value cannot be `null`.
| | `enable` | `boolean`: Whether the service should only be activated when the device's screen is on
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | If the provided service has not been registered | ### setRequireDeviceUnlockForService Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions) ``` public void setRequireDeviceUnlockForService (ComponentName service, boolean enable) ``` Sets whether the device must be unlocked for the service to be activated. This API overrides the `android:requireDeviceUnlock` attribute declared in the service's manifest.
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service. This value cannot be `null`.
| | `enable` | `boolean`: Whether the service should only be activated when the device is unlocked
| | Throws || |---|---| | `https://developer.android.com/reference/java/lang/IllegalArgumentException` | If the provided service has not been registered | ### setShouldDefaultToObserveModeForService Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean setShouldDefaultToObserveModeForService (ComponentName service, boolean enable) ``` Sets whether when this service becomes the preferred service, if the NFC stack should enable observe mode or disable observe mode. The default is to not enable observe mode when a service either the foreground default service or the default payment service so not calling this method will preserve that behavior.
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service. This value cannot be `null`.
| | `enable` | `boolean`: Whether the service should default to observe mode or not
| | Returns || |---|---| | `boolean` | whether the change was successful.
| ### supportsAidPrefixRegistration Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean supportsAidPrefixRegistration () ``` Some devices may allow an application to register all AIDs that starts with a certain prefix, e.g. "A000000004\*" to register all MasterCard AIDs. Use this method to determine whether this device supports registering AID prefixes.
| Returns || |---|---| | `boolean` | whether AID prefix registering is supported on this device.
| ### unregisterNfcEventCallback Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public void unregisterNfcEventCallback (CardEmulation.NfcEventCallback callback) ``` Unregister an NFC event callback that was previously registered with `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#registerNfcEventCallback(java.util.concurrent.Executor,%20android.nfc.cardemulation.CardEmulation.NfcEventCallback)`.
| Parameters || |---|---| | `callback` | `CardEmulation.NfcEventCallback`: The previously registered callback to unregister. This value cannot be `null`.
| ### unsetOffHostForService Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean unsetOffHostForService (ComponentName service) ``` Unsets the off-host Secure Element for the given service. Note that this will only remove Secure Element that was dynamically set using the `https://developer.android.com/reference/android/nfc/cardemulation/CardEmulation#setOffHostForService(android.content.ComponentName,%20java.lang.String)` and resets it to a value that was statically assigned using manifest. Note that you can only unset off-host SE for a service that is running under the same UID as the caller of this API. Typically this means you need to call this from the same package as the service itself, though UIDs can also be shared between packages using shared UIDs. Requires `https://developer.android.com/reference/android/Manifest.permission#NFC`
| Parameters || |---|---| | `service` | `ComponentName`: The component name of the service. This value cannot be `null`.
| | Returns || |---|---| | `boolean` | whether the registration was successful. This value cannot be `null`.
| ### unsetPreferredService Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) ``` public boolean unsetPreferredService (Activity activity) ``` Unsets the preferred service for the specified Activity. Note that the specified Activity must still be in resumed state at the time of this call. A good place to call this method is in your `https://developer.android.com/reference/android/app/Activity#onPause()` implementation.
| Parameters || |---|---| | `activity` | `Activity`: The activity which the service was registered for
| | Returns || |---|---| | `boolean` | true when successful
|