Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public final class

CardEmulation

extends Object
java.lang.Object
   ↳ android.nfc.cardemulation.CardEmulation

Class Overview

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 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(String) .
int SELECTION_MODE_ASK_IF_CONFLICT Return value for getSelectionModeForCategory(String) .
int SELECTION_MODE_PREFER_DEFAULT Return value for getSelectionModeForCategory(String) .
Public Methods
synchronized static CardEmulation getInstance ( NfcAdapter adapter)
Helper to get an instance of this class.
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.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_CHANGE_DEFAULT

Added in API level 19

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 he wants 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"

public static final String CATEGORY_OTHER

Added in API level 19

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

Constant Value: "other"

public static final String CATEGORY_PAYMENT

Added in API level 19

Category used for NFC payment services.

Constant Value: "payment"

public static final String EXTRA_CATEGORY

Added in API level 19

The category extra for ACTION_CHANGE_DEFAULT .

See Also
Constant Value: "category"

public static final String EXTRA_SERVICE_COMPONENT

Added in API level 19

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

See Also
Constant Value: "component"

public static final int SELECTION_MODE_ALWAYS_ASK

Added in API level 19

Return value for getSelectionModeForCategory(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 he wants to use to handle the transaction, even if there is only one matching service.

Constant Value: 1 (0x00000001)

public static final int SELECTION_MODE_ASK_IF_CONFLICT

Added in API level 19

Return value for getSelectionModeForCategory(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)

public static final int SELECTION_MODE_PREFER_DEFAULT

Added in API level 19

Return value for getSelectionModeForCategory(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

public static synchronized CardEmulation getInstance ( NfcAdapter adapter)

Helper to get an instance of this class.

Parameters
adapter A reference to an NfcAdapter object.

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 he 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 The category, for example CATEGORY_PAYMENT
Returns
  • the selection mode for the passed in category

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 The ComponentName of the service
aid The ISO7816-4 Application ID
Returns
  • whether the service is the default handler for the specified AID

    Requires the NFC permission.

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(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(ComponentName, String) to determine whether a service is the default for a specific AID.

Parameters
service The ComponentName of the service
category The category
Returns
  • whether service is currently the default service for the category.

    Requires the NFC permission.