diff options
| -rw-r--r-- | api/current.txt | 14 | ||||
| -rw-r--r-- | api/system-current.txt | 14 | ||||
| -rw-r--r-- | api/test-current.txt | 14 | ||||
| -rw-r--r-- | core/java/android/nfc/cardemulation/HostNfcFService.java | 62 | ||||
| -rw-r--r-- | core/java/android/nfc/cardemulation/NfcFCardEmulation.java | 29 |
5 files changed, 102 insertions, 31 deletions
diff --git a/api/current.txt b/api/current.txt index 9787f51bf16b..58e92208a18f 100644 --- a/api/current.txt +++ b/api/current.txt @@ -25078,14 +25078,14 @@ package android.nfc.cardemulation { } public final class NfcFCardEmulation { - method public boolean disableNfcFForegroundService(android.app.Activity); - method public boolean enableNfcFForegroundService(android.app.Activity, android.content.ComponentName); + method public boolean disableService(android.app.Activity) throws java.lang.RuntimeException; + method public boolean enableService(android.app.Activity, android.content.ComponentName) throws java.lang.RuntimeException; method public static synchronized android.nfc.cardemulation.NfcFCardEmulation getInstance(android.nfc.NfcAdapter); - method public java.lang.String getNfcid2ForService(android.content.ComponentName); - method public java.lang.String getSystemCodeForService(android.content.ComponentName); - method public boolean registerSystemCodeForService(android.content.ComponentName, java.lang.String); - method public boolean removeSystemCodeForService(android.content.ComponentName); - method public boolean setNfcid2ForService(android.content.ComponentName, java.lang.String); + method public java.lang.String getNfcid2ForService(android.content.ComponentName) throws java.lang.RuntimeException; + method public java.lang.String getSystemCodeForService(android.content.ComponentName) throws java.lang.RuntimeException; + method public boolean registerSystemCodeForService(android.content.ComponentName, java.lang.String) throws java.lang.RuntimeException; + method public boolean setNfcid2ForService(android.content.ComponentName, java.lang.String) throws java.lang.RuntimeException; + method public boolean unregisterSystemCodeForService(android.content.ComponentName) throws java.lang.RuntimeException; } public abstract class OffHostApduService extends android.app.Service { diff --git a/api/system-current.txt b/api/system-current.txt index dc1f3ee9d055..342d29b2a792 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -27520,14 +27520,14 @@ package android.nfc.cardemulation { } public final class NfcFCardEmulation { - method public boolean disableNfcFForegroundService(android.app.Activity); - method public boolean enableNfcFForegroundService(android.app.Activity, android.content.ComponentName); + method public boolean disableService(android.app.Activity) throws java.lang.RuntimeException; + method public boolean enableService(android.app.Activity, android.content.ComponentName) throws java.lang.RuntimeException; method public static synchronized android.nfc.cardemulation.NfcFCardEmulation getInstance(android.nfc.NfcAdapter); - method public java.lang.String getNfcid2ForService(android.content.ComponentName); - method public java.lang.String getSystemCodeForService(android.content.ComponentName); - method public boolean registerSystemCodeForService(android.content.ComponentName, java.lang.String); - method public boolean removeSystemCodeForService(android.content.ComponentName); - method public boolean setNfcid2ForService(android.content.ComponentName, java.lang.String); + method public java.lang.String getNfcid2ForService(android.content.ComponentName) throws java.lang.RuntimeException; + method public java.lang.String getSystemCodeForService(android.content.ComponentName) throws java.lang.RuntimeException; + method public boolean registerSystemCodeForService(android.content.ComponentName, java.lang.String) throws java.lang.RuntimeException; + method public boolean setNfcid2ForService(android.content.ComponentName, java.lang.String) throws java.lang.RuntimeException; + method public boolean unregisterSystemCodeForService(android.content.ComponentName) throws java.lang.RuntimeException; } public abstract class OffHostApduService extends android.app.Service { diff --git a/api/test-current.txt b/api/test-current.txt index ac2fedb8aa10..50db2b2d5811 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -25147,14 +25147,14 @@ package android.nfc.cardemulation { } public final class NfcFCardEmulation { - method public boolean disableNfcFForegroundService(android.app.Activity); - method public boolean enableNfcFForegroundService(android.app.Activity, android.content.ComponentName); + method public boolean disableService(android.app.Activity) throws java.lang.RuntimeException; + method public boolean enableService(android.app.Activity, android.content.ComponentName) throws java.lang.RuntimeException; method public static synchronized android.nfc.cardemulation.NfcFCardEmulation getInstance(android.nfc.NfcAdapter); - method public java.lang.String getNfcid2ForService(android.content.ComponentName); - method public java.lang.String getSystemCodeForService(android.content.ComponentName); - method public boolean registerSystemCodeForService(android.content.ComponentName, java.lang.String); - method public boolean removeSystemCodeForService(android.content.ComponentName); - method public boolean setNfcid2ForService(android.content.ComponentName, java.lang.String); + method public java.lang.String getNfcid2ForService(android.content.ComponentName) throws java.lang.RuntimeException; + method public java.lang.String getSystemCodeForService(android.content.ComponentName) throws java.lang.RuntimeException; + method public boolean registerSystemCodeForService(android.content.ComponentName, java.lang.String) throws java.lang.RuntimeException; + method public boolean setNfcid2ForService(android.content.ComponentName, java.lang.String) throws java.lang.RuntimeException; + method public boolean unregisterSystemCodeForService(android.content.ComponentName) throws java.lang.RuntimeException; } public abstract class OffHostApduService extends android.app.Service { diff --git a/core/java/android/nfc/cardemulation/HostNfcFService.java b/core/java/android/nfc/cardemulation/HostNfcFService.java index 273ddeb965a3..1d4baf4849cf 100644 --- a/core/java/android/nfc/cardemulation/HostNfcFService.java +++ b/core/java/android/nfc/cardemulation/HostNfcFService.java @@ -19,6 +19,7 @@ package android.nfc.cardemulation; import android.annotation.SdkConstant; import android.annotation.SdkConstant.SdkConstantType; import android.app.Service; +import android.content.ComponentName; import android.content.Intent; import android.os.Bundle; import android.os.Handler; @@ -31,6 +32,67 @@ import android.util.Log; /** * <p>HostNfcFService is a convenience {@link Service} class that can be * extended to emulate an NFC-F card inside an Android service component. + * + * <h3>NFC Protocols</h3> + * <p>Cards emulated by this class are based on the NFC-Forum NFC-F + * protocol (based on the JIS-X 6319-4 specification.)</p> + * + * <h3>System Code and NFCID2 registration</h3> + * <p>A {@link HostNfcFService HostNfcFService service} can register + * exactly one System Code and one NFCID2. For details about the use of + * System Code and NFCID2, see the NFC Forum Digital specification.</p> + * <p>To statically register a System Code and NFCID2 with the service, a {@link #SERVICE_META_DATA} + * entry must be included in the declaration of the service. An example of a HostNfcFService + * manifest declaration is shown below: + * + * <pre> <service android:name=".MyHostNfcFService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE"> + * <intent-filter> + * <action android:name="android.nfc.cardemulation.action.HOST_NFCF_SERVICE"/> + * </intent-filter> + * <meta-data android:name="android.nfc.cardemulation.host_nfcf_service" android:resource="@xml/nfcfservice"/> + * </service></pre> + * + * This meta-data tag points to an nfcfservice.xml file. + * An example of this file with a System Code and NFCID2 declaration is shown below: + * <pre> + * <host-nfcf-service xmlns:android="http://schemas.android.com/apk/res/android" + * android:description="@string/servicedesc"> + * <system-code-filter android:name="4000"/> + * <nfcid2-filter android:name="02FE000000000000"/> + * </host-nfcf-service> + * </pre> + * + * <p>The {@link android.R.styleable#HostNfcFService <host-nfcf-service>} is required + * to contain a + * {@link android.R.styleable#HostApduService_description <android:description>} + * attribute that contains a user-friendly description of the service that may be shown in UI. + * <p>The {@link android.R.styleable#HostNfcFService <host-nfcf-service>} must + * contain: + * <ul> + * <li>Exactly one {@link android.R.styleable#SystemCodeFilter <system-code-filter>} tag.</li> + * <li>Exactly one {@link android.R.styleable#Nfcid2Filter <nfcid2-filter>} tag.</li> + * </ul> + * </p> + * + * <p>Alternatively, the System Code and NFCID2 can be dynamically registererd for a service + * by using the {@link NfcFCardEmulation#registerSystemCodeForService(ComponentName, String)} and + * {@link NfcFCardEmulation#setNfcid2ForService(ComponentName, String)} methods. + * </p> + * + * <h3>Service selection</h3> + * <p>When a remote NFC devices wants to communicate with your service, it + * sends a SENSF_REQ command to the NFC controller, requesting a System Code. + * If a {@link NfcFCardEmulation NfcFCardEmulation service} has registered + * this system code and has been enabled by the foreground application, the + * NFC controller will respond with the NFCID2 that is registered for this service. + * The reader can then continue data exchange with this service by using the NFCID2.</p> + * + * <h3>Data exchange</h3> + * <p>After service selection, all frames addressed to the NFCID2 of this service will + * be sent through {@link #processNfcFPacket(byte[], Bundle)}, until the NFC link is + * broken.<p> + * + * <p>When the NFC link is broken, {@link #onDeactivated(int)} will be called.</p> */ public abstract class HostNfcFService extends Service { /** diff --git a/core/java/android/nfc/cardemulation/NfcFCardEmulation.java b/core/java/android/nfc/cardemulation/NfcFCardEmulation.java index a50650481a73..6bb5d8e6253c 100644 --- a/core/java/android/nfc/cardemulation/NfcFCardEmulation.java +++ b/core/java/android/nfc/cardemulation/NfcFCardEmulation.java @@ -108,12 +108,12 @@ public final class NfcFCardEmulation { * the System Code contained in the Manifest file is returned. After calling * {@link #registerSystemCodeForService(ComponentName, String)}, the System Code * registered there is returned. After calling - * {@link #removeSystemCodeForService(ComponentName)}, "null" is returned. + * {@link #unregisterSystemCodeForService(ComponentName)}, "null" is returned. * * @param service The component name of the service * @return the current System Code */ - public String getSystemCodeForService(ComponentName service) { + public String getSystemCodeForService(ComponentName service) throws RuntimeException { if (service == null) { throw new NullPointerException("service is null"); } @@ -130,6 +130,7 @@ public final class NfcFCardEmulation { return sService.getSystemCodeForService(UserHandle.myUserId(), service); } catch (RemoteException ee) { Log.e(TAG, "Failed to reach CardEmulationService."); + ee.rethrowAsRuntimeException(); return null; } } @@ -157,7 +158,8 @@ public final class NfcFCardEmulation { * @param systemCode The System Code to be registered * @return whether the registration was successful. */ - public boolean registerSystemCodeForService(ComponentName service, String systemCode) { + public boolean registerSystemCodeForService(ComponentName service, String systemCode) + throws RuntimeException { if (service == null || systemCode == null) { throw new NullPointerException("service or systemCode is null"); } @@ -176,6 +178,7 @@ public final class NfcFCardEmulation { service, systemCode); } catch (RemoteException ee) { Log.e(TAG, "Failed to reach CardEmulationService."); + ee.rethrowAsRuntimeException(); return false; } } @@ -187,7 +190,7 @@ public final class NfcFCardEmulation { * @param service The component name of the service * @return whether the System Code was successfully removed. */ - public boolean removeSystemCodeForService(ComponentName service) { + public boolean unregisterSystemCodeForService(ComponentName service) throws RuntimeException { if (service == null) { throw new NullPointerException("service is null"); } @@ -204,6 +207,7 @@ public final class NfcFCardEmulation { return sService.removeSystemCodeForService(UserHandle.myUserId(), service); } catch (RemoteException ee) { Log.e(TAG, "Failed to reach CardEmulationService."); + ee.rethrowAsRuntimeException(); return false; } } @@ -221,7 +225,7 @@ public final class NfcFCardEmulation { * @param service The component name of the service * @return the current NFCID2 */ - public String getNfcid2ForService(ComponentName service) { + public String getNfcid2ForService(ComponentName service) throws RuntimeException { if (service == null) { throw new NullPointerException("service is null"); } @@ -238,6 +242,7 @@ public final class NfcFCardEmulation { return sService.getNfcid2ForService(UserHandle.myUserId(), service); } catch (RemoteException ee) { Log.e(TAG, "Failed to reach CardEmulationService."); + ee.rethrowAsRuntimeException(); return null; } } @@ -262,7 +267,8 @@ public final class NfcFCardEmulation { * @param nfcid2 The NFCID2 to be registered * @return whether the setting was successful. */ - public boolean setNfcid2ForService(ComponentName service, String nfcid2) { + public boolean setNfcid2ForService(ComponentName service, String nfcid2) + throws RuntimeException { if (service == null || nfcid2 == null) { throw new NullPointerException("service or nfcid2 is null"); } @@ -281,6 +287,7 @@ public final class NfcFCardEmulation { service, nfcid2); } catch (RemoteException ee) { Log.e(TAG, "Failed to reach CardEmulationService."); + ee.rethrowAsRuntimeException(); return false; } } @@ -292,12 +299,12 @@ public final class NfcFCardEmulation { * * <p>The specified HCE-F service is only enabled when the corresponding application is * in the foreground and this method has been called. When the application is moved to - * the background, {@link #disableNfcFForegroundService(Activity)} is called, or + * the background, {@link #disableService(Activity)} is called, or * NFCID2 or System Code is replaced, the HCE-F service is disabled. * * <p>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 #disableNfcFForegroundService(Activity)} in your {@link Activity#onPause}. + * {@link #disableService(Activity)} in your {@link Activity#onPause}. * * <p>Note that this preference is not persisted by the OS, and hence must be * called every time the Activity is resumed. @@ -306,7 +313,7 @@ public final class NfcFCardEmulation { * @param service The service to be preferred while this activity is in the foreground * @return whether the registration was successful */ - public boolean enableNfcFForegroundService(Activity activity, ComponentName service) { + public boolean enableService(Activity activity, ComponentName service) throws RuntimeException { if (activity == null || service == null) { throw new NullPointerException("activity or service is null"); } @@ -327,6 +334,7 @@ public final class NfcFCardEmulation { return sService.enableNfcFForegroundService(service); } catch (RemoteException ee) { Log.e(TAG, "Failed to reach CardEmulationService."); + ee.rethrowAsRuntimeException(); return false; } } @@ -342,7 +350,7 @@ public final class NfcFCardEmulation { * @param activity The activity which the service was registered for * @return true when successful */ - public boolean disableNfcFForegroundService(Activity activity) { + public boolean disableService(Activity activity) throws RuntimeException { if (activity == null) { throw new NullPointerException("activity is null"); } @@ -362,6 +370,7 @@ public final class NfcFCardEmulation { return sService.disableNfcFForegroundService(); } catch (RemoteException ee) { Log.e(TAG, "Failed to reach CardEmulationService."); + ee.rethrowAsRuntimeException(); return false; } } |