CardEmulation
class CardEmulation
kotlin.Any | |
↳ | 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 | |
---|---|
static String |
Activity action: ask the user to change the default card emulation service for a certain category. |
static String |
Category that can be used for all other card emulation services. |
static String |
Category used for NFC payment services. |
static String |
The category extra for |
static String |
The service |
static Int |
Return value for |
static Int |
Return value for |
static Int |
Return value for |
Public methods | |
---|---|
Boolean |
categoryAllowsForegroundPreference(category: String!) 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. |
MutableList<String!>? |
Retrieves the registered AIDs for the preferred payment service. |
MutableList<String!>! |
getAidsForService(service: ComponentName!, category: String!) Retrieves the currently registered AIDs for the specified category for a service. |
CharSequence? |
Returns a user-visible description of the preferred payment service. |
static CardEmulation! |
getInstance(adapter: NfcAdapter!) Helper to get an instance of this class. |
String? |
Retrieves the route destination for the preferred payment service. |
Int |
getSelectionModeForCategory(category: String!) Returns the service selection mode for the passed in category. |
Boolean |
isDefaultServiceForAid(service: ComponentName!, aid: String!) Allows an application to query whether a service is currently the default handler for a specified ISO7816-4 Application ID. |
Boolean |
isDefaultServiceForCategory(service: ComponentName!, category: String!) Allows an application to query whether a service is currently the default service to handle a card emulation category. |
Boolean |
registerAidsForService(service: ComponentName!, category: String!, aids: MutableList<String!>!) Registers a list of AIDs for a specific category for the specified service. |
Boolean |
registerPollingLoopFilterForService(service: ComponentName, pollingLoopFilter: String, autoTransact: Boolean) Register a polling loop filter (PLF) for a HostApduService and indicate whether it should auto-transact or not. |
Boolean |
registerPollingLoopPatternFilterForService(service: ComponentName, pollingLoopPatternFilter: String, autoTransact: Boolean) Register a polling loop pattern filter (PLPF) for a HostApduService and indicate whether it should auto-transact or not. |
Boolean |
removeAidsForService(service: ComponentName!, category: String!) Removes a previously registered list of AIDs for the specified category for the service provided. |
Boolean |
removePollingLoopFilterForService(service: ComponentName, pollingLoopFilter: String) Unregister a polling loop filter (PLF) for a HostApduService. |
Boolean |
removePollingLoopPatternFilterForService(service: ComponentName, pollingLoopPatternFilter: String) Unregister a polling loop pattern filter (PLPF) for a HostApduService. |
Boolean |
setOffHostForService(service: ComponentName, offHostSecureElement: String) Sets the off-host Secure Element for the given service. |
Boolean |
setPreferredService(activity: Activity!, service: ComponentName!) Allows a foreground application to specify which card emulation service should be preferred while a specific Activity is in the foreground. |
Boolean |
setShouldDefaultToObserveModeForService(service: ComponentName, enable: Boolean) Sets whether when this service becomes the preferred service, if the NFC stack should enable observe mode or disable observe mode. |
Boolean |
Some devices may allow an application to register all AIDs that starts with a certain prefix, e. |
Boolean |
unsetOffHostForService(service: ComponentName) Unsets the off-host Secure Element for the given service. |
Boolean |
unsetPreferredService(activity: Activity!) Unsets the preferred service for the specified Activity. |
Constants
ACTION_CHANGE_DEFAULT
static valACTION_CHANGE_DEFAULT: String
Deprecated: Please use android.app.role.RoleManager#createRequestRoleIntent(String)
with android.app.role.RoleManager#ROLE_WALLET
parameter and Activity#startActivityForResult(Intent, int)
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 EXTRA_SERVICE_COMPONENT
, for the category specified in EXTRA_CATEGORY
. There is an optional extra field using Intent#EXTRA_USER
to specify the UserHandle
of the user that owns the app.
Value: "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT"
CATEGORY_OTHER
static val CATEGORY_OTHER: String
Category that can be used for all other card emulation services.
Value: "other"
CATEGORY_PAYMENT
static val CATEGORY_PAYMENT: String
Category used for NFC payment services.
Value: "payment"
EXTRA_CATEGORY
static val EXTRA_CATEGORY: String
The category extra for ACTION_CHANGE_DEFAULT
.
Value: "category"
See Also
EXTRA_SERVICE_COMPONENT
static val EXTRA_SERVICE_COMPONENT: String
The service ComponentName
object passed in as an extra for ACTION_CHANGE_DEFAULT
.
Value: "component"
See Also
SELECTION_MODE_ALWAYS_ASK
static val SELECTION_MODE_ALWAYS_ASK: Int
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.
Value: 1
SELECTION_MODE_ASK_IF_CONFLICT
static val SELECTION_MODE_ASK_IF_CONFLICT: Int
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.
Value: 2
SELECTION_MODE_PREFER_DEFAULT
static val SELECTION_MODE_PREFER_DEFAULT: Int
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.
Value: 0
Public methods
categoryAllowsForegroundPreference
fun categoryAllowsForegroundPreference(category: String!): Boolean
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.
Starting with Build.VERSION_CODES#VANILLA_ICE_CREAM
, this method will always return true.
Parameters | |
---|---|
category |
String!: The category, e.g. CATEGORY_PAYMENT |
Return | |
---|---|
Boolean |
whether AIDs in the category can be handled by a service specified by the foreground app. |
getAidsForPreferredPaymentService
fun getAidsForPreferredPaymentService(): MutableList<String!>?
Retrieves the registered AIDs for the preferred payment service.
Requires android.Manifest.permission#NFC_PREFERRED_PAYMENT_INFO
Return | |
---|---|
MutableList<String!>? |
The list of AIDs registered for this category, or null if it couldn't be found. |
getAidsForService
fun getAidsForService(
service: ComponentName!,
category: String!
): MutableList<String!>!
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 |
Return | |
---|---|
MutableList<String!>! |
The list of AIDs registered for this category, or null if it couldn't be found. |
getDescriptionForPreferredPaymentService
fun getDescriptionForPreferredPaymentService(): CharSequence?
Returns a user-visible description of the preferred payment service.
Starting with Build.VERSION_CODES#VANILLA_ICE_CREAM
, the preferred payment service no longer exists and is replaced by 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 android.Manifest.permission#NFC_PREFERRED_PAYMENT_INFO
Return | |
---|---|
CharSequence? |
the preferred payment service description This value may be null . |
getInstance
static fun getInstance(adapter: NfcAdapter!): CardEmulation!
Helper to get an instance of this class.
Parameters | |
---|---|
adapter |
NfcAdapter!: A reference to an NfcAdapter object. |
Return | |
---|---|
CardEmulation! |
getRouteDestinationForPreferredPaymentService
fun getRouteDestinationForPreferredPaymentService(): String?
Retrieves the route destination for the preferred payment service.
Starting with Build.VERSION_CODES#VANILLA_ICE_CREAM
, the preferred payment service no longer exists and is replaced by 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 android.Manifest.permission#NFC_PREFERRED_PAYMENT_INFO
Return | |
---|---|
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
fun getSelectionModeForCategory(category: String!): Int
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.
Starting with Build.VERSION_CODES#VANILLA_ICE_CREAM
, the default service defined by the holder of android.app.role.RoleManager#ROLE_WALLET
and is category agnostic.
Parameters | |
---|---|
category |
String!: The category, for example CATEGORY_PAYMENT |
Return | |
---|---|
Int |
the selection mode for the passed in category |
isDefaultServiceForAid
fun isDefaultServiceForAid(
service: ComponentName!,
aid: String!
): Boolean
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 |
Return | |
---|---|
Boolean |
whether the service is the default handler for the specified AID
Requires the |
isDefaultServiceForCategory
fun isDefaultServiceForCategory(
service: ComponentName!,
category: String!
): Boolean
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 |
Return | |
---|---|
Boolean |
whether service is currently the default service for the category.
Requires the |
registerAidsForService
fun registerAidsForService(
service: ComponentName!,
category: String!,
aids: MutableList<String!>!
): Boolean
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 |
MutableList<String!>!: A list containing the AIDs to be registered |
Return | |
---|---|
Boolean |
whether the registration was successful. |
registerPollingLoopFilterForService
fun registerPollingLoopFilterForService(
service: ComponentName,
pollingLoopFilter: String,
autoTransact: Boolean
): Boolean
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 HostApduService#processPollingFrames(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.
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 |
Return | |
---|---|
Boolean |
true if the filter was registered, false otherwise |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the passed in string doesn't parse to at least one byte |
registerPollingLoopPatternFilterForService
fun registerPollingLoopPatternFilterForService(
service: ComponentName,
pollingLoopPatternFilter: String,
autoTransact: Boolean
): Boolean
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 `*`. When the beginning of anon-standard polling loop frame matches this sequence exactly, it may be delivered to HostApduService#processPollingFrames(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.
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 java.util.regex.Pattern#compile(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 |
Return | |
---|---|
Boolean |
true if the filter was registered, false otherwise |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the filter containst elements other than hexadecimal numbers and `.`, `?` and `*` operators |
java.util.regex.PatternSyntaxException |
if the regex syntax is invalid |
removeAidsForService
fun removeAidsForService(
service: ComponentName!,
category: String!
): Boolean
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 |
Return | |
---|---|
Boolean |
whether the group was successfully removed. |
removePollingLoopFilterForService
fun removePollingLoopFilterForService(
service: ComponentName,
pollingLoopFilter: String
): Boolean
Unregister a polling loop filter (PLF) for a HostApduService. If the PLF had previously been registered via registerPollingLoopFilterForService(android.content.ComponentName,java.lang.String,boolean)
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 . |
Return | |
---|---|
Boolean |
true if the filter was removed, false otherwise |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the passed in string doesn't parse to at least one byte |
removePollingLoopPatternFilterForService
fun removePollingLoopPatternFilterForService(
service: ComponentName,
pollingLoopPatternFilter: String
): Boolean
Unregister a polling loop pattern filter (PLPF) for a HostApduService. If the PLF had previously been registered via registerPollingLoopFilterForService(android.content.ComponentName,java.lang.String,boolean)
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 java.util.regex.Pattern#compile(String) and only contain hexadecimal numbers and`.`, `?` and `*` operators This value cannot be null . |
Return | |
---|---|
Boolean |
true if the filter was removed, false otherwise |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the filter containst elements other than hexadecimal numbers and `.`, `?` and `*` operators |
java.util.regex.PatternSyntaxException |
if the regex syntax is invalid |
setOffHostForService
fun setOffHostForService(
service: ComponentName,
offHostSecureElement: String
): Boolean
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 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… 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 . |
Return | |
---|---|
Boolean |
whether the registration was successful. This value cannot be null . |
setPreferredService
fun setPreferredService(
activity: Activity!,
service: ComponentName!
): Boolean
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 |
Return | |
---|---|
Boolean |
whether the registration was successful |
setShouldDefaultToObserveModeForService
fun setShouldDefaultToObserveModeForService(
service: ComponentName,
enable: Boolean
): Boolean
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 |
Return | |
---|---|
Boolean |
whether the change was successful. |
supportsAidPrefixRegistration
fun supportsAidPrefixRegistration(): Boolean
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.
Return | |
---|---|
Boolean |
whether AID prefix registering is supported on this device. |
unsetOffHostForService
fun unsetOffHostForService(service: ComponentName): Boolean
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 android.Manifest.permission#NFC
Parameters | |
---|---|
service |
ComponentName: The component name of the service This value cannot be null . |
Return | |
---|---|
Boolean |
whether the registration was successful. This value cannot be null . |
unsetPreferredService
fun unsetPreferredService(activity: Activity!): Boolean
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 |
Return | |
---|---|
Boolean |
true when successful |