Most visited

Recently visited

Added in API level 19

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

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> getAidsForService(ComponentName service, String category)

Retrieves the currently registered AIDs for the specified category for a service.

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.

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 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 unsetPreferredService(Activity activity)

Unsets the preferred service for the specified Activity.

Inherited methods

From class java.lang.Object

Constants

ACTION_CHANGE_DEFAULT

Added in API level 19
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 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"

CATEGORY_OTHER

Added in API level 19
String CATEGORY_OTHER

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

Constant Value: "other"

CATEGORY_PAYMENT

Added in API level 19
String CATEGORY_PAYMENT

Category used for NFC payment services.

Constant Value: "payment"

EXTRA_CATEGORY

Added in API level 19
String EXTRA_CATEGORY

The category extra for ACTION_CHANGE_DEFAULT.

See also:

Constant Value: "category"

EXTRA_SERVICE_COMPONENT

Added in API level 19
String EXTRA_SERVICE_COMPONENT

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

See also:

Constant Value: "component"

SELECTION_MODE_ALWAYS_ASK

Added in API level 19
int SELECTION_MODE_ALWAYS_ASK

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)

SELECTION_MODE_ASK_IF_CONFLICT

Added in API level 19
int SELECTION_MODE_ASK_IF_CONFLICT

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)

SELECTION_MODE_PREFER_DEFAULT

Added in API level 19
int SELECTION_MODE_PREFER_DEFAULT

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

categoryAllowsForegroundPreference

Added in API level 21
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(Activity, 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.

getAidsForService

Added in API level 21
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(ComponentName, String, 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.

getInstance

Added in API level 19
CardEmulation getInstance (NfcAdapter adapter)

Helper to get an instance of this class.

Parameters
adapter NfcAdapter: A reference to an NfcAdapter object.
Returns
CardEmulation

getSelectionModeForCategory

Added in API level 19
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 String: The category, for example CATEGORY_PAYMENT
Returns
int the selection mode for the passed in category

isDefaultServiceForAid

Added in API level 19
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 NFC permission.

isDefaultServiceForCategory

Added in API level 19
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 ComponentName: The ComponentName of the service
category String: The category
Returns
boolean whether service is currently the default service for the category.

Requires the NFC permission.

registerAidsForService

Added in API level 21
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

Added in API level 21
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(ComponentName, String, 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.

setPreferredService

Added in API level 21
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 onResume(), and to call unsetPreferredService(Activity) in your 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(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

Added in API level 21
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.

unsetPreferredService

Added in API level 21
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 onPause() implementation.

Parameters
activity Activity: The activity which the service was registered for
Returns
boolean true when successful

Hooray!