# Print output for @column tags ?>
Developers

- Design
- Develop
- Distribute

Developer Console

## Most visited

## Recently visited

## Results for

Summary: Constants | Methods | Inherited Methods

# CardEmulation

`public final class CardEmulation`
`extends Object` ``

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.

Use of this class requires the `PackageManager#FEATURE_NFC_HOST_CARD_EMULATION` to be present on the device.

## Summary

### Constants
`String` | `ACTION_CHANGE_DEFAULT` Activity action: ask the user to change the default card emulation service for a certain category.
`String` | `CATEGORY_OTHER` Category that can be used for all other card emulation services.
`String` | `CATEGORY_PAYMENT` Category used for NFC payment services.
`String` | `EXTRA_CATEGORY` The category extra for `ACTION_CHANGE_DEFAULT`.
`String` | `EXTRA_SERVICE_COMPONENT` The service `ComponentName` object passed in as an extra for `ACTION_CHANGE_DEFAULT`.
`int` | `SELECTION_MODE_ALWAYS_ASK` Return value for `getSelectionModeForCategory(java.lang.String)`.
`int` | `SELECTION_MODE_ASK_IF_CONFLICT` Return value for `getSelectionModeForCategory(java.lang.String)`.
`int` | `SELECTION_MODE_PREFER_DEFAULT` Return value for `getSelectionModeForCategory(java.lang.String)`.

### Public methods
`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.
`List<String>` | `getAidsForPreferredPaymentService()` Retrieves the registered AIDs for the preferred payment service.
`List<String>` | `getAidsForService(ComponentName service, String category)` Retrieves the currently registered AIDs for the specified category for a service.
`CharSequence` | `getDescriptionForPreferredPaymentService()` Returns a user-visible description of the preferred payment service.
`static CardEmulation` | `getInstance(NfcAdapter adapter)` Helper to get an instance of this class.
`String` | `getRouteDestinationForPreferredPaymentService()` Retrieves the route destination for the preferred payment service.
`int` | `getSelectionModeForCategory(String category)` Returns the service selection mode for the passed in category.
`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.
`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.
`boolean` | `registerAidsForService(ComponentName service, String category, List<String> aids)` Registers a list of AIDs for a specific category for the specified service.
`boolean` | `removeAidsForService(ComponentName service, String category)` Removes a previously registered list of AIDs for the specified category for the service provided.
`boolean` | `setOffHostForService(ComponentName service, String offHostSecureElement)` Sets the off-host Secure Element for the given service.
`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.
`boolean` | `supportsAidPrefixRegistration()` Some devices may allow an application to register all AIDs that starts with a certain prefix, e.g.
`boolean` | `unsetOffHostForService(ComponentName service)` Unsets the off-host Secure Element for the given service.
`boolean` | `unsetPreferredService(Activity activity)` Unsets the preferred service for the specified Activity.

### Inherited methods
From class `java.lang.Object`
`Object` | `clone()` Creates and returns a copy of this object.
`boolean` | `equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void` | `finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>` | `getClass()` Returns the runtime class of this `Object`.
`int` | `hashCode()` Returns a hash code value for the object.
`final void` | `notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void` | `notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String` | `toString()` Returns a string representation of the object.
`final void` | `wait(long timeout, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void` | `wait(long timeout)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void` | `wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.

## Constants

### ACTION_CHANGE_DEFAULT

    public static final String ACTION_CHANGE_DEFAULT

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 `EXTRA_SERVICE_COMPONENT`, for the category specified in `EXTRA_CATEGORY`

Constant Value: "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT"

### CATEGORY_OTHER

    public static final String CATEGORY_OTHER

Category that can be used for all other card emulation services.

Constant Value: "other"

### CATEGORY_PAYMENT

    public static final String CATEGORY_PAYMENT

Category used for NFC payment services.

Constant Value: "payment"

### EXTRA_CATEGORY

    public static final String EXTRA_CATEGORY

The category extra for `ACTION_CHANGE_DEFAULT`.

See also:

- `ACTION_CHANGE_DEFAULT`

Constant Value: "category"

### EXTRA_SERVICE_COMPONENT

    public static final String EXTRA_SERVICE_COMPONENT

The service `ComponentName` object passed in as an extra for `ACTION_CHANGE_DEFAULT`.

See also:

- `ACTION_CHANGE_DEFAULT`

Constant Value: "component"

### SELECTION_MODE_ALWAYS_ASK

    public static final int SELECTION_MODE_ALWAYS_ASK

Return value for `getSelectionModeForCategory(java.lang.String)`.

In this mode, when using ISO-DEP card emulation with `HostApduService` or `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

    public static final int SELECTION_MODE_ASK_IF_CONFLICT

Return value for `getSelectionModeForCategory(java.lang.String)`.

In this mode, when using ISO-DEP card emulation with `HostApduService` or `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

    public static final int SELECTION_MODE_PREFER_DEFAULT

Return value for `getSelectionModeForCategory(java.lang.String)`.

In this mode, the user has set a default service for this category.

When using ISO-DEP card emulation with `HostApduService` or `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

    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 `setPreferredService(android.app.Activity, android.content.ComponentName)` method.

Parameters
`category` | `String`: The category, e.g. `CATEGORY_PAYMENT`

Returns
`boolean` | whether AIDs in the category can be handled by a service specified by the foreground app.

### getAidsForPreferredPaymentService

    public List<String> getAidsForPreferredPaymentService ()

Retrieves the registered AIDs for the preferred payment service.
Requires `Manifest.permission.NFC_PREFERRED_PAYMENT_INFO`

Returns
`List<String>` | The list of AIDs registered for this category, or null if it couldn't be found.

### getAidsForService

    public List<String> 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 `registerAidsForService(android.content.ComponentName, java.lang.String, java.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. `CATEGORY_PAYMENT`

Returns
`List<String>` | The list of AIDs registered for this category, or null if it couldn't be found.

### getDescriptionForPreferredPaymentService

    public CharSequence getDescriptionForPreferredPaymentService ()

Returns a user-visible description of the preferred payment service.
Requires `Manifest.permission.NFC_PREFERRED_PAYMENT_INFO`

Returns
`CharSequence` | the preferred payment service description This value may be `null`.

### getInstance

    public static CardEmulation getInstance (NfcAdapter adapter)

Helper to get an instance of this class.

Parameters
`adapter` | `NfcAdapter`: A reference to an NfcAdapter object.

Returns
`CardEmulation` |

### getRouteDestinationForPreferredPaymentService

    public String getRouteDestinationForPreferredPaymentService ()

Retrieves the route destination for the preferred payment service.
Requires `Manifest.permission.NFC_PREFERRED_PAYMENT_INFO`

Returns
`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… 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

    public int getSelectionModeForCategory (String category)

Returns the service selection mode for the passed in category. Valid return values are:

`SELECTION_MODE_PREFER_DEFAULT` the user has requested a default service for this category, which will be preferred.

`SELECTION_MODE_ALWAYS_ASK` the user has requested to be asked every time what service they would like to use in this category.

`SELECTION_MODE_ASK_IF_CONFLICT` the user will only be asked to pick a service if there is a conflict.

Parameters
`category` | `String`: The category, for example `CATEGORY_PAYMENT`

Returns
`int` | the selection mode for the passed in category

### isDefaultServiceForAid

    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 `Manifest.permission.NFC` permission.

### isDefaultServiceForCategory

    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 `getSelectionModeForCategory(java.lang.String)` returns `SELECTION_MODE_ALWAYS_ASK` or `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 `SELECTION_MODE_ALWAYS_ASK` or `SELECTION_MODE_ASK_IF_CONFLICT`, use `isDefaultServiceForAid(android.content.ComponentName, java.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 `Manifest.permission.NFC` permission.

### registerAidsForService

    public boolean registerAidsForService (ComponentName service,
                    String category,
                    List<String> 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.

### removeAidsForService

    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 `registerAidsForService(android.content.ComponentName, java.lang.String, java.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. `CATEGORY_PAYMENT`

Returns
`boolean` | whether the group was successfully removed.

### setOffHostForService

    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 `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… 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

    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 `Activity#onResume`, and to call `unsetPreferredService(android.app.Activity)` in your `Activity#onPause`.

This method call will fail in two specific scenarios:

- If the service registers one or more AIDs in the `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 `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 `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.

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

### supportsAidPrefixRegistration

    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.

### unsetOffHostForService

    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 `setOffHostForService(android.content.ComponentName, java.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 `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

    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 `Activity#onPause` implementation.

Parameters
`activity` | `Activity`: The activity which the service was registered for

Returns
`boolean` | true when successful

Full name *
Email address *
Company / developer name
One of your Play Store app URLs *
Which best describes your business:*
Apps
Games
Apps & Games
*
*