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