1package android.nfc.cardemulation;
2
3import android.annotation.SdkConstant;
4import android.annotation.SdkConstant.SdkConstantType;
5import android.app.Service;
6import android.content.Intent;
7import android.content.pm.PackageManager;
8import android.os.IBinder;
9
10/**
11 * <p>OffHostApduService is a convenience {@link Service} class that can be
12 * extended to describe one or more NFC applications that are residing
13 * off-host, for example on an embedded secure element or a UICC.
14 *
15 * <div class="special reference">
16 * <h3>Developer Guide</h3>
17 * For a general introduction into the topic of card emulation,
18 * please read the <a href="{@docRoot}guide/topics/nfc/ce.html">
19 * NFC card emulation developer guide.</a></p>
20 * </div>
21 *
22 * <h3>NFC Protocols</h3>
23 * <p>Off-host applications represented by this class are based on the NFC-Forum ISO-DEP
24 * protocol (based on ISO/IEC 14443-4) and support processing
25 * command Application Protocol Data Units (APDUs) as
26 * defined in the ISO/IEC 7816-4 specification.
27 *
28 * <h3>Service selection</h3>
29 * <p>When a remote NFC device wants to talk to your
30 * off-host NFC application, it sends a so-called
31 * "SELECT AID" APDU as defined in the ISO/IEC 7816-4 specification.
32 * The AID is an application identifier defined in ISO/IEC 7816-4.
33 *
34 * <p>The registration procedure for AIDs is defined in the
35 * ISO/IEC 7816-5 specification. If you don't want to register an
36 * AID, you are free to use AIDs in the proprietary range:
37 * bits 8-5 of the first byte must each be set to '1'. For example,
38 * "0xF00102030405" is a proprietary AID. If you do use proprietary
39 * AIDs, it is recommended to choose an AID of at least 6 bytes,
40 * to reduce the risk of collisions with other applications that
41 * might be using proprietary AIDs as well.
42 *
43 * <h3>AID groups</h3>
44 * <p>In some cases, an off-host environment may need to register multiple AIDs
45 * to implement a certain application, and it needs to be sure
46 * that it is the default handler for all of these AIDs (as opposed
47 * to some AIDs in the group going to another service).
48 *
49 * <p>An AID group is a list of AIDs that should be considered as
50 * belonging together by the OS. For all AIDs in an AID group, the
51 * OS will guarantee one of the following:
52 * <ul>
53 * <li>All AIDs in the group are routed to the off-host execution environment
54 * <li>No AIDs in the group are routed to the off-host execution environment
55 * </ul>
56 * In other words, there is no in-between state, where some AIDs
57 * in the group can be routed to this off-host execution environment,
58 * and some to another or a host-based {@link HostApduService}.
59 * <h3>AID groups and categories</h3>
60 * <p>Each AID group can be associated with a category. This allows
61 * the Android OS to classify services, and it allows the user to
62 * set defaults at the category level instead of the AID level.
63 *
64 * <p>You can use
65 * {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)}
66 * to determine if your off-host service is the default handler for a category.
67 *
68 * <p>In this version of the platform, the only known categories
69 * are {@link CardEmulation#CATEGORY_PAYMENT} and {@link CardEmulation#CATEGORY_OTHER}.
70 * AID groups without a category, or with a category that is not recognized
71 * by the current platform version, will automatically be
72 * grouped into the {@link CardEmulation#CATEGORY_OTHER} category.
73 *
74 * <h3>Service AID registration</h3>
75 * <p>To tell the platform which AIDs
76 * reside off-host and are managed by this service, a {@link #SERVICE_META_DATA}
77 * entry must be included in the declaration of the service. An
78 * example of a OffHostApduService manifest declaration is shown below:
79 * <pre> &lt;service android:name=".MyOffHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE"&gt;
80 *     &lt;intent-filter&gt;
81 *         &lt;action android:name="android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"/&gt;
82 *     &lt;/intent-filter&gt;
83 *     &lt;meta-data android:name="android.nfc.cardemulation.off_host_apdu_ervice" android:resource="@xml/apduservice"/&gt;
84 * &lt;/service&gt;</pre>
85 *
86 * This meta-data tag points to an apduservice.xml file.
87 * An example of this file with a single AID group declaration is shown below:
88 * <pre>
89 * &lt;offhost-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
90 *           android:description="@string/servicedesc"&gt;
91 *       &lt;aid-group android:description="@string/subscription" android:category="other">
92 *           &lt;aid-filter android:name="F0010203040506"/&gt;
93 *           &lt;aid-filter android:name="F0394148148100"/&gt;
94 *       &lt;/aid-group&gt;
95 * &lt;/offhost-apdu-service&gt;
96 * </pre>
97 *
98 * <p>The {@link android.R.styleable#OffHostApduService &lt;offhost-apdu-service&gt;} is required
99 * to contain a
100 * {@link android.R.styleable#OffHostApduService_description &lt;android:description&gt;}
101 * attribute that contains a user-friendly description of the service that may be shown in UI.
102 *
103 * <p>The {@link android.R.styleable#OffHostApduService &lt;offhost-apdu-service&gt;} must
104 * contain one or more {@link android.R.styleable#AidGroup &lt;aid-group&gt;} tags.
105 * Each {@link android.R.styleable#AidGroup &lt;aid-group&gt;} must contain one or
106 * more {@link android.R.styleable#AidFilter &lt;aid-filter&gt;} tags, each of which
107 * contains a single AID. The AID must be specified in hexadecimal format, and contain
108 * an even number of characters.
109 *
110 * <p>This registration will allow the service to be included
111 * as an option for being the default handler for categories.
112 * The Android OS will take care of correctly
113 * routing the AIDs to the off-host execution environment,
114 * based on which service the user has selected to be the handler for a certain category.
115 *
116 * <p>The service may define additional actions outside of the
117 * Android namespace that provide further interaction with
118 * the off-host execution environment.
119 *
120 * <p class="note">Use of this class requires the
121 * {@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present
122 * on the device.
123 */
124public abstract class OffHostApduService extends Service {
125    /**
126     * The {@link Intent} action that must be declared as handled by the service.
127     */
128    @SdkConstant(SdkConstantType.SERVICE_ACTION)
129    public static final String SERVICE_INTERFACE =
130            "android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE";
131
132    /**
133     * The name of the meta-data element that contains
134     * more information about this service.
135     */
136    public static final String SERVICE_META_DATA =
137            "android.nfc.cardemulation.off_host_apdu_service";
138
139    /**
140     * The Android platform itself will not bind to this service,
141     * but merely uses its declaration to keep track of what AIDs
142     * the service is interested in. This information is then used
143     * to present the user with a list of applications that can handle
144     * an AID, as well as correctly route those AIDs either to the host (in case
145     * the user preferred a {@link HostApduService}), or to an off-host
146     * execution environment (in case the user preferred a {@link OffHostApduService}.
147     *
148     * Implementers may define additional actions outside of the
149     * Android namespace that allow further interactions with
150     * the off-host execution environment. Such implementations
151     * would need to override this method.
152     */
153    public abstract IBinder onBind(Intent intent);
154}
155