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.
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 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
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.
| |||||||||||
Retrieves the currently registered AIDs for the specified
category for a service.
| |||||||||||
Helper to get an instance of this class.
| |||||||||||
Returns the service selection mode for the passed in category.
| |||||||||||
Allows an application to query whether a service is currently
the default handler for a specified ISO7816-4 Application ID.
| |||||||||||
Allows an application to query whether a service is currently
the default service to handle a card emulation category.
| |||||||||||
Registers a list of AIDs for a specific category for the
specified service.
| |||||||||||
Removes a previously registered list of AIDs for the specified category for the
service provided.
| |||||||||||
Allows a foreground application to specify which card emulation service
should be preferred while a specific Activity is in the foreground.
| |||||||||||
Unsets the preferred service for the specified Activity.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
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
Category that can be used for all other card emulation services.
Category used for NFC payment services.
The service ComponentName
object passed in as an
extra for ACTION_CHANGE_DEFAULT
.
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.
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.
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.
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.
category | The category, e.g. CATEGORY_PAYMENT |
---|
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.
service | The component name of the service |
---|---|
category | The category for which the AIDs were registered,
e.g. CATEGORY_PAYMENT |
Helper to get an instance of this class.
adapter | A reference to an NfcAdapter object. |
---|
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.
category | The category, for example CATEGORY_PAYMENT |
---|
Allows an application to query whether a service is currently the default handler for a specified ISO7816-4 Application ID.
service | The ComponentName of the service |
---|---|
aid | The ISO7816-4 Application ID |
Requires the NFC
permission.
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.
service | The ComponentName of the service |
---|---|
category | The category |
Requires the NFC
permission.
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.
service | The component name of the service |
---|---|
category | The category of AIDs to be registered |
aids | A list containing the AIDs to be registered |
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.
service | The component name of the service |
---|---|
category | The category of the AIDs to be removed, e.g. CATEGORY_PAYMENT |
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:
CATEGORY_PAYMENT
category, but the user has indicated that foreground apps are not allowed
to override the default payment service.
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.
activity | The activity which prefers this service to be invoked |
---|---|
service | The service to be preferred while this activity is in the foreground |
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.
activity | The activity which the service was registered for |
---|