CardEmulationpublic final class CardEmulation extends Object 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
{@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present
on the device. |
Fields Summary |
---|
static final String | TAG | public static final String | ACTION_CHANGE_DEFAULTActivity 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
{@link #EXTRA_SERVICE_COMPONENT}, for the category
specified in {@link #EXTRA_CATEGORY} | public static final String | EXTRA_CATEGORYThe category extra for {@link #ACTION_CHANGE_DEFAULT}. | public static final String | EXTRA_SERVICE_COMPONENTThe service {@link ComponentName} object passed in as an
extra for {@link #ACTION_CHANGE_DEFAULT}. | public static final String | CATEGORY_PAYMENTCategory used for NFC payment services. | public static final String | CATEGORY_OTHERCategory that can be used for all other card emulation
services. | public static final int | SELECTION_MODE_PREFER_DEFAULTReturn value for {@link #getSelectionModeForCategory(String)}.
In this mode, the user has set a default service for this
category.
When using ISO-DEP card emulation with {@link HostApduService}
or {@link 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. | public static final int | SELECTION_MODE_ALWAYS_ASKReturn value for {@link #getSelectionModeForCategory(String)}.
In this mode, when using ISO-DEP card emulation with {@link HostApduService}
or {@link 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. | public static final int | SELECTION_MODE_ASK_IF_CONFLICTReturn value for {@link #getSelectionModeForCategory(String)}.
In this mode, when using ISO-DEP card emulation with {@link HostApduService}
or {@link 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. | static boolean | sIsInitialized | static HashMap | sCardEmus | static android.nfc.INfcCardEmulation | sService | final android.content.Context | mContext |
Methods Summary |
---|
public boolean | categoryAllowsForegroundPreference(java.lang.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
{@link #setPreferredService(Activity, ComponentName)} method.
if (CATEGORY_PAYMENT.equals(category)) {
boolean preferForeground = false;
try {
preferForeground = Settings.Secure.getInt(mContext.getContentResolver(),
Settings.Secure.NFC_PAYMENT_FOREGROUND) != 0;
} catch (SettingNotFoundException e) {
}
return preferForeground;
} else {
// Allowed for all other categories
return true;
}
| public java.util.List | getAidsForService(android.content.ComponentName service, java.lang.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 {@link #registerAidsForService(ComponentName, String, List)}
method. It will *not* return AIDs that were statically registered
in the manifest.
try {
AidGroup group = sService.getAidGroupForService(UserHandle.myUserId(), service,
category);
return (group != null ? group.getAids() : null);
} catch (RemoteException e) {
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return null;
}
try {
AidGroup group = sService.getAidGroupForService(UserHandle.myUserId(), service,
category);
return (group != null ? group.getAids() : null);
} catch (RemoteException ee) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return null;
}
}
| public static synchronized android.nfc.cardemulation.CardEmulation | getInstance(android.nfc.NfcAdapter adapter)Helper to get an instance of this class.
if (adapter == null) throw new NullPointerException("NfcAdapter is null");
Context context = adapter.getContext();
if (context == null) {
Log.e(TAG, "NfcAdapter context is null.");
throw new UnsupportedOperationException();
}
if (!sIsInitialized) {
IPackageManager pm = ActivityThread.getPackageManager();
if (pm == null) {
Log.e(TAG, "Cannot get PackageManager");
throw new UnsupportedOperationException();
}
try {
if (!pm.hasSystemFeature(PackageManager.FEATURE_NFC_HOST_CARD_EMULATION)) {
Log.e(TAG, "This device does not support card emulation");
throw new UnsupportedOperationException();
}
} catch (RemoteException e) {
Log.e(TAG, "PackageManager query failed.");
throw new UnsupportedOperationException();
}
sIsInitialized = true;
}
CardEmulation manager = sCardEmus.get(context);
if (manager == null) {
// Get card emu service
INfcCardEmulation service = adapter.getCardEmulationService();
if (service == null) {
Log.e(TAG, "This device does not implement the INfcCardEmulation interface.");
throw new UnsupportedOperationException();
}
manager = new CardEmulation(context, service);
sCardEmus.put(context, manager);
}
return manager;
| public int | getSelectionModeForCategory(java.lang.String category)Returns the service selection mode for the passed in category.
Valid return values are:
{@link #SELECTION_MODE_PREFER_DEFAULT} the user has requested a default
service for this category, which will be preferred.
{@link #SELECTION_MODE_ALWAYS_ASK} the user has requested to be asked
every time what service he would like to use in this category.
{@link #SELECTION_MODE_ASK_IF_CONFLICT} the user will only be asked
to pick a service if there is a conflict.
if (CATEGORY_PAYMENT.equals(category)) {
String defaultComponent = Settings.Secure.getString(mContext.getContentResolver(),
Settings.Secure.NFC_PAYMENT_DEFAULT_COMPONENT);
if (defaultComponent != null) {
return SELECTION_MODE_PREFER_DEFAULT;
} else {
return SELECTION_MODE_ALWAYS_ASK;
}
} else {
return SELECTION_MODE_ASK_IF_CONFLICT;
}
| public java.util.List | getServices(java.lang.String category)
try {
return sService.getServices(UserHandle.myUserId(), category);
} catch (RemoteException e) {
// Try one more time
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return null;
}
try {
return sService.getServices(UserHandle.myUserId(), category);
} catch (RemoteException ee) {
Log.e(TAG, "Failed to reach CardEmulationService.");
return null;
}
}
| public boolean | isDefaultServiceForAid(android.content.ComponentName service, java.lang.String aid)Allows an application to query whether a service is currently
the default handler for a specified ISO7816-4 Application ID.
try {
return sService.isDefaultServiceForAid(UserHandle.myUserId(), service, aid);
} catch (RemoteException e) {
// Try one more time
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
try {
return sService.isDefaultServiceForAid(UserHandle.myUserId(), service, aid);
} catch (RemoteException ee) {
Log.e(TAG, "Failed to reach CardEmulationService.");
return false;
}
}
| public boolean | isDefaultServiceForCategory(android.content.ComponentName service, java.lang.String category)Allows an application to query whether a service is currently
the default service to handle a card emulation category.
Note that if {@link #getSelectionModeForCategory(String)}
returns {@link #SELECTION_MODE_ALWAYS_ASK} or {@link #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 {@link #SELECTION_MODE_ALWAYS_ASK} or
{@link #SELECTION_MODE_ASK_IF_CONFLICT}, use
{@link #isDefaultServiceForAid(ComponentName, String)} to determine whether a service
is the default for a specific AID.
try {
return sService.isDefaultServiceForCategory(UserHandle.myUserId(), service, category);
} catch (RemoteException e) {
// Try one more time
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
try {
return sService.isDefaultServiceForCategory(UserHandle.myUserId(), service,
category);
} catch (RemoteException ee) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
}
| public static boolean | isValidAid(java.lang.String aid)A valid AID according to ISO/IEC 7816-4:
- Has >= 5 bytes and <=16 bytes (>=10 hex chars and <= 32 hex chars)
- Consist of only hex characters
- Additionally, we allow an asterisk at the end, to indicate
a prefix
if (aid == null)
return false;
// If a prefix AID, the total length must be odd (even # of AID chars + '*')
if (aid.endsWith("*") && ((aid.length() % 2) == 0)) {
Log.e(TAG, "AID " + aid + " is not a valid AID.");
return false;
}
// If not a prefix AID, the total length must be even (even # of AID chars)
if (!aid.endsWith("*") && ((aid.length() % 2) != 0)) {
Log.e(TAG, "AID " + aid + " is not a valid AID.");
return false;
}
// Verify hex characters
if (!aid.matches("[0-9A-Fa-f]{10,32}\\*?")) {
Log.e(TAG, "AID " + aid + " is not a valid AID.");
return false;
}
return true;
| void | recoverService()
NfcAdapter adapter = NfcAdapter.getDefaultAdapter(mContext);
sService = adapter.getCardEmulationService();
| public boolean | registerAidsForService(android.content.ComponentName service, java.lang.String category, java.util.List 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.
AidGroup aidGroup = new AidGroup(aids, category);
try {
return sService.registerAidGroupForService(UserHandle.myUserId(), service, aidGroup);
} catch (RemoteException e) {
// Try one more time
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
try {
return sService.registerAidGroupForService(UserHandle.myUserId(), service,
aidGroup);
} catch (RemoteException ee) {
Log.e(TAG, "Failed to reach CardEmulationService.");
return false;
}
}
| public boolean | removeAidsForService(android.content.ComponentName service, java.lang.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 {@link #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.
try {
return sService.removeAidGroupForService(UserHandle.myUserId(), service, category);
} catch (RemoteException e) {
// Try one more time
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
try {
return sService.removeAidGroupForService(UserHandle.myUserId(), service, category);
} catch (RemoteException ee) {
Log.e(TAG, "Failed to reach CardEmulationService.");
return false;
}
}
| public boolean | setDefaultForNextTap(android.content.ComponentName service)
try {
return sService.setDefaultForNextTap(UserHandle.myUserId(), service);
} catch (RemoteException e) {
// Try one more time
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
try {
return sService.setDefaultForNextTap(UserHandle.myUserId(), service);
} catch (RemoteException ee) {
Log.e(TAG, "Failed to reach CardEmulationService.");
return false;
}
}
| public boolean | setDefaultServiceForCategory(android.content.ComponentName service, java.lang.String category)
try {
return sService.setDefaultServiceForCategory(UserHandle.myUserId(), service, category);
} catch (RemoteException e) {
// Try one more time
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
try {
return sService.setDefaultServiceForCategory(UserHandle.myUserId(), service,
category);
} catch (RemoteException ee) {
Log.e(TAG, "Failed to reach CardEmulationService.");
return false;
}
}
| public boolean | setPreferredService(android.app.Activity activity, android.content.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 {@link Activity#onResume}, and to call
{@link #unsetPreferredService(Activity)} in your {@link Activity#onPause}.
This method call will fail in two specific scenarios:
- If the service registers one or more AIDs in the {@link #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 {@link #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 {@link #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.
// Verify the activity is in the foreground before calling into NfcService
if (activity == null || service == null) {
throw new NullPointerException("activity or service or category is null");
}
if (!activity.isResumed()) {
throw new IllegalArgumentException("Activity must be resumed.");
}
try {
return sService.setPreferredService(service);
} catch (RemoteException e) {
// Try one more time
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
try {
return sService.setPreferredService(service);
} catch (RemoteException ee) {
Log.e(TAG, "Failed to reach CardEmulationService.");
return false;
}
}
| 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.
try {
return sService.supportsAidPrefixRegistration();
} catch (RemoteException e) {
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
try {
return sService.supportsAidPrefixRegistration();
} catch (RemoteException ee) {
Log.e(TAG, "Failed to reach CardEmulationService.");
return false;
}
}
| public boolean | unsetPreferredService(android.app.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 {@link Activity#onPause} implementation.
if (activity == null) {
throw new NullPointerException("activity is null");
}
if (!activity.isResumed()) {
throw new IllegalArgumentException("Activity must be resumed.");
}
try {
return sService.unsetPreferredService();
} catch (RemoteException e) {
// Try one more time
recoverService();
if (sService == null) {
Log.e(TAG, "Failed to recover CardEmulationService.");
return false;
}
try {
return sService.unsetPreferredService();
} catch (RemoteException ee) {
Log.e(TAG, "Failed to reach CardEmulationService.");
return false;
}
}
|
|