OffHostApduService.java revision 52246087f4e2b5ad62b9cd6ea8c2cb58f624d4e7 
1package android.nfc.cardemulation;
2
3import android.annotation.SdkConstant;
4import android.annotation.SdkConstant.SdkConstantType;
5import android.app.Service;
6import android.content.Intent;
7import android.os.IBinder;
8
9/**
10 * <p>A convenience class that can be extended to implement
11 * a service that registers ISO7814-4 AIDs that reside off-host,
12 * for example on an embedded secure element or UICC.
13 *
14 * <p>This registration will allow the service to be included
15 * as an option for handling these AIDs on non-host execution
16 * environments. The Operating System will take care of correctly
17 * routing the AIDs, based on which service the user has selected
18 * to be the handler for an AID.
19 *
20 * <p>The service may define additional actions outside of the
21 * Android namespace that provide further interaction with
22 * the off-host execution environment.
23 *
24 * <p>To tell the platform which ISO7816 application ID (AIDs)
25 * are present and handled by the app containing this service,
26 * a {@link #SERVICE_META_DATA} entry must be included in the declaration
27 * of the service. An example of such a service declaration is shown below:
28 * <pre> &lt;service android:name=".MyOffHostApduService"&gt;
29 *     &lt;intent-filter&gt;
30 *         &lt;action android:name="android.nfc.OffHostApduService"/&gt;
31 *     &lt;/intent-filter&gt;
32 *     &lt;meta-data android:name="android.nfc.OffHostApduService" android:resource="@xml/apduservice.xml"/&gt;
33 * &lt;/service&gt;</pre>
34 * <p>For more details refer to {@link #SERVICE_META_DATA},
35 * <code>&lt;{@link android.R.styleable#OffHostApduService offhost-apdu-service}&gt;</code>,
36 * <code>&lt;{@link android.R.styleable#AidGroup aid-group}&gt;</code> and
37 * <code>&lt;{@link android.R.styleable#AidFilter aid-filter}&gt;</code>.
38 */
39public abstract class OffHostApduService extends Service {
40    /**
41     * The {@link Intent} that must be declared as handled by the service.
42     */
43    @SdkConstant(SdkConstantType.SERVICE_ACTION)
44    public static final String SERVICE_INTERFACE =
45            "android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE";
46
47    /**
48     * The name of the meta-data element that contains
49     * more information about this service.
50     */
51    public static final String SERVICE_META_DATA =
52            "android.nfc.cardemulation.off_host_apdu_service";
53
54    /**
55     * The Android platform itself will not bind to this service,
56     * but merely uses its declaration to keep track of what AIDs
57     * the service is interested in. This information is then used
58     * to present the user with a list of applications that can handle
59     * an AID, as well as correctly route those AIDs either to the host (in case
60     * the user preferred a {@link HostApduService}), or to an off-host
61     * execution environment (in case the user preferred a {@link OffHostApduService}.
62     *
63     * Implementers may define additional actions outside of the
64     * Android namespace that allow further interactions with
65     * the off-host execution environment. Such implementations
66     * would need to override this method.
67     */
68    public abstract IBinder onBind(Intent intent);
69}
70