1/*
2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package javax.smartcardio;
27
28import java.nio.*;
29
30/**
31 * A logical channel connection to a Smart Card. It is used to exchange APDUs
32 * with a Smart Card.
33 * A CardChannel object can be obtained by calling the method
34 * {@linkplain Card#getBasicChannel} or {@linkplain Card#openLogicalChannel}.
35 *
36 * @see Card
37 * @see CommandAPDU
38 * @see ResponseAPDU
39 *
40 * @since   1.6
41 * @author  Andreas Sterbenz
42 * @author  JSR 268 Expert Group
43 */
44public abstract class CardChannel {
45
46    /**
47     * Constructs a new CardChannel object.
48     *
49     * <p>This constructor is called by subclasses only. Application should
50     * call the {@linkplain Card#getBasicChannel} and
51     * {@linkplain Card#openLogicalChannel} methods to obtain a CardChannel
52     * object.
53     */
54    protected CardChannel() {
55        // empty
56    }
57
58    /**
59     * Returns the Card this channel is associated with.
60     *
61     * @return the Card this channel is associated with
62     */
63    public abstract Card getCard();
64
65    /**
66     * Returns the channel number of this CardChannel. A channel number of
67     * 0 indicates the basic logical channel.
68     *
69     * @return the channel number of this CardChannel.
70     *
71     * @throws IllegalStateException if this channel has been
72     *   {@linkplain #close closed} or if the corresponding Card has been
73     *   {@linkplain Card#disconnect disconnected}.
74     */
75    public abstract int getChannelNumber();
76
77    /**
78     * Transmits the specified command APDU to the Smart Card and returns the
79     * response APDU.
80     *
81     * <p>The CLA byte of the command APDU is automatically adjusted to
82     * match the channel number of this CardChannel.
83     *
84     * <p>Note that this method cannot be used to transmit
85     * <code>MANAGE CHANNEL</code> APDUs. Logical channels should be managed
86     * using the {@linkplain Card#openLogicalChannel} and {@linkplain
87     * CardChannel#close CardChannel.close()} methods.
88     *
89     * <p>Implementations should transparently handle artifacts
90     * of the transmission protocol.
91     * For example, when using the T=0 protocol, the following processing
92     * should occur as described in ISO/IEC 7816-4:
93     *
94     * <ul>
95     * <li><p>if the response APDU has an SW1 of <code>61</code>, the
96     * implementation should issue a <code>GET RESPONSE</code> command
97     * using <code>SW2</code> as the <code>Le</code>field.
98     * This process is repeated as long as an SW1 of <code>61</code> is
99     * received. The response body of these exchanges is concatenated
100     * to form the final response body.
101     *
102     * <li><p>if the response APDU is <code>6C XX</code>, the implementation
103     * should reissue the command using <code>XX</code> as the
104     * <code>Le</code> field.
105     * </ul>
106     *
107     * <p>The ResponseAPDU returned by this method is the result
108     * after this processing has been performed.
109     *
110     * @param command the command APDU
111     * @return the response APDU received from the card
112     *
113     * @throws IllegalStateException if this channel has been
114     *   {@linkplain #close closed} or if the corresponding Card has been
115     *   {@linkplain Card#disconnect disconnected}.
116     * @throws IllegalArgumentException if the APDU encodes a
117     *   <code>MANAGE CHANNEL</code> command
118     * @throws NullPointerException if command is null
119     * @throws CardException if the card operation failed
120     */
121    public abstract ResponseAPDU transmit(CommandAPDU command) throws CardException;
122
123    /**
124     * Transmits the command APDU stored in the command ByteBuffer and receives
125     * the response APDU in the response ByteBuffer.
126     *
127     * <p>The command buffer must contain valid command APDU data starting
128     * at <code>command.position()</code> and the APDU must be
129     * <code>command.remaining()</code> bytes long.
130     * Upon return, the command buffer's position will be equal
131     * to its limit; its limit will not have changed. The output buffer
132     * will have received the response APDU bytes. Its position will have
133     * advanced by the number of bytes received, which is also the return
134     * value of this method.
135     *
136     * <p>The CLA byte of the command APDU is automatically adjusted to
137     * match the channel number of this CardChannel.
138     *
139     * <p>Note that this method cannot be used to transmit
140     * <code>MANAGE CHANNEL</code> APDUs. Logical channels should be managed
141     * using the {@linkplain Card#openLogicalChannel} and {@linkplain
142     * CardChannel#close CardChannel.close()} methods.
143     *
144     * <p>See {@linkplain #transmit transmit()} for a discussion of the handling
145     * of response APDUs with the SW1 values <code>61</code> or <code>6C</code>.
146     *
147     * @param command the buffer containing the command APDU
148     * @param response the buffer that shall receive the response APDU from
149     *   the card
150     * @return the length of the received response APDU
151     *
152     * @throws IllegalStateException if this channel has been
153     *   {@linkplain #close closed} or if the corresponding Card has been
154     *   {@linkplain Card#disconnect disconnected}.
155     * @throws NullPointerException if command or response is null
156     * @throws ReadOnlyBufferException if the response buffer is read-only
157     * @throws IllegalArgumentException if command and response are the
158     *   same object, if <code>response</code> may not have
159     *   sufficient space to receive the response APDU
160     *   or if the APDU encodes a <code>MANAGE CHANNEL</code> command
161     * @throws CardException if the card operation failed
162     */
163    public abstract int transmit(ByteBuffer command, ByteBuffer response)
164        throws CardException;
165
166    /**
167     * Closes this CardChannel. The logical channel is closed by issuing
168     * a <code>MANAGE CHANNEL</code> command that should use the format
169     * <code>[xx 70 80 0n]</code> where <code>n</code> is the channel number
170     * of this channel and <code>xx</code> is the <code>CLA</code>
171     * byte that encodes this logical channel and has all other bits set to 0.
172     * After this method returns, calling other
173     * methods in this class will raise an IllegalStateException.
174     *
175     * <p>Note that the basic logical channel cannot be closed using this
176     * method. It can be closed by calling {@link Card#disconnect}.
177     *
178     * @throws CardException if the card operation failed
179     * @throws IllegalStateException if this CardChannel represents a
180     *   connection the basic logical channel
181     */
182    public abstract void close() throws CardException;
183
184}
185