1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15package ohos.hdi.secure_element.sim_secure_element.v1_0;
16
17import ohos.hdi.secure_element.sim_secure_element.v1_0.ISecureElementCallback;
18import ohos.hdi.secure_element.sim_secure_element.v1_0.SecureElementTypes;
19
20/**
21 * @brief Declares the APIs provided by the SecureElement module for obtaining SecureElement operations,
22 * see "Open Mobile API Specification".
23 *
24 * @since 5.0
25 * @version 1.0
26 */
27interface ISecureElementInterface {
28
29    /**
30     * Initializes the secure element.
31     *
32     * @param callback The callback used to notify the secure element status changed.
33     * @param status The status code to initialize the secure element.
34     * @since 5.0
35     * @version 1.0
36     */
37    init([in] ISecureElementCallback clientCallback, [out] enum SecureElementStatus status);
38
39    /**
40     * Get the ATR of this SE.
41     *
42     * @return response The ATR or empty array SHALL be returned if the ATR for this SE is not available.
43     * @since 5.0
44     * @version 1.0
45     */
46    getAtr([out] List<unsigned char> response);
47
48    /**
49     * Checks if a SE is present in this reader.
50     *
51     * @param present True if the SE is present, false otherwise.
52     * @since 5.0
53     * @version 1.0
54     */
55    isSecureElementPresent([out] boolean present);
56
57    /**
58     * Open a logical channel with the SE, selecting the applet represented by the given AID (when the AID is not
59     * Null and the length of the AID is not 0).
60     *
61     * @param aid The AID of the applet to be selected on this channel, as a byte array.
62     * @param p2 The P2 parameter of the SELECT APDU executed on this channel.
63     * @param response The response to SELECT command, or empty if failure.
64     * @param channelNumber The channel number of new logical channel.
65     * @param status The status code to open logical channel.
66     * @since 5.0
67     * @version 1.0
68     */
69    openLogicalChannel([in] List<unsigned char> aid, [in] unsigned char p2, [out] List<unsigned char> response,
70        [out] unsigned char channelNumber, [out] enum SecureElementStatus status);
71
72    /**
73     * Get access to the basic channel, as defined in [ISO 7816-4] (the one that has number 0). The obtained object
74     * is an instance of the channel class.
75     *
76     * @param aid The AID of the applet to be selected on this channel, as a byte array.
77     * @param p2 The P2 parameter of the SELECT APDU executed on this channel.
78     * @param response The response to SELECT command, or empty if failure.
79     * @param status The status code to open basic channel.
80     * @since 5.0
81     * @version 1.0
82     */
83    openBasicChannel([in] List<unsigned char> aid, [in] unsigned char p2, [out] List<unsigned char> response,
84        [out] enum SecureElementStatus status);
85
86    /**
87     * Closes this logical channel to the SE.
88     * Closing a basic channel must return SecureElementStatus::FAILED.
89     *
90     * @param channelNumber The logical channel number to be closed
91     * @param status The status code to close the logical channel.
92     * @since 5.0
93     * @version 1.0
94     */
95    closeChannel([in] unsigned char channelNumber, [out] enum SecureElementStatus status);
96
97    /**
98     * Transmit an APDU command (as per ISO/IEC 7816) to the SE.
99     *
100     * @param command The APDU command to be transmitted, as a byte array.
101     * @param response The response received, as a byte array.
102     * @param status The status code to transmit command.
103     * @since 5.0
104     * @version 1.0
105     */
106     transmit([in] List<unsigned char> command, [out] List<unsigned char> response, [out] enum SecureElementStatus status);
107
108    /**
109     * Transmit an APDU command (as per ISO/IEC 7816) to the SE.
110     *
111     * @param status The status code to reset the secure element.
112     * @since 5.0
113     * @version 1.0
114     */
115     reset([out] enum SecureElementStatus status);
116}
117