--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/smartcardio/CardChannel.java Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,184 @@
+/*
+ * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+
+package javax.smartcardio;
+
+import java.nio.*;
+
+/**
+ * A logical channel connection to a Smart Card. It is used to exchange APDUs
+ * with a Smart Card.
+ * A CardChannel object can be obtained by calling the method
+ * {@linkplain Card#getBasicChannel} or {@linkplain Card#openLogicalChannel}.
+ *
+ * @see Card
+ * @see CommandAPDU
+ * @see ResponseAPDU
+ *
+ * @since 1.6
+ * @author Andreas Sterbenz
+ * @author JSR 268 Expert Group
+ */
+public abstract class CardChannel {
+
+ /**
+ * Constructs a new CardChannel object.
+ *
+ * <p>This constructor is called by subclasses only. Application should
+ * call the {@linkplain Card#getBasicChannel} and
+ * {@linkplain Card#openLogicalChannel} methods to obtain a CardChannel
+ * object.
+ */
+ protected CardChannel() {
+ // empty
+ }
+
+ /**
+ * Returns the Card this channel is associated with.
+ *
+ * @return the Card this channel is associated with
+ */
+ public abstract Card getCard();
+
+ /**
+ * Returns the channel number of this CardChannel. A channel number of
+ * 0 indicates the basic logical channel.
+ *
+ * @return the channel number of this CardChannel.
+ *
+ * @throws IllegalStateException if this channel has been
+ * {@linkplain #close closed} or if the corresponding Card has been
+ * {@linkplain Card#disconnect disconnected}.
+ */
+ public abstract int getChannelNumber();
+
+ /**
+ * Transmits the specified command APDU to the Smart Card and returns the
+ * response APDU.
+ *
+ * <p>The CLA byte of the command APDU is automatically adjusted to
+ * match the channel number of this CardChannel.
+ *
+ * <p>Note that this method cannot be used to transmit
+ * <code>MANAGE CHANNEL</code> APDUs. Logical channels should be managed
+ * using the {@linkplain Card#openLogicalChannel} and {@linkplain
+ * CardChannel#close CardChannel.close()} methods.
+ *
+ * <p>Implementations should transparently handle artifacts
+ * of the transmission protocol.
+ * For example, when using the T=0 protocol, the following processing
+ * should occur as described in ISO/IEC 7816-4:
+ *
+ * <ul>
+ * <li><p>if the response APDU has an SW1 of <code>61</code>, the
+ * implementation should issue a <code>GET RESPONSE</code> command
+ * using <code>SW2</code> as the <code>Le</code>field.
+ * This process is repeated as long as an SW1 of <code>61</code> is
+ * received. The response body of these exchanges is concatenated
+ * to form the final response body.
+ *
+ * <li><p>if the response APDU is <code>6C XX</code>, the implementation
+ * should reissue the command using <code>XX</code> as the
+ * <code>Le</code> field.
+ * </ul>
+ *
+ * <p>The ResponseAPDU returned by this method is the result
+ * after this processing has been performed.
+ *
+ * @param command the command APDU
+ * @return the response APDU received from the card
+ *
+ * @throws IllegalStateException if this channel has been
+ * {@linkplain #close closed} or if the corresponding Card has been
+ * {@linkplain Card#disconnect disconnected}.
+ * @throws IllegalArgumentException if the APDU encodes a
+ * <code>MANAGE CHANNEL</code> command
+ * @throws NullPointerException if command is null
+ * @throws CardException if the card operation failed
+ */
+ public abstract ResponseAPDU transmit(CommandAPDU command) throws CardException;
+
+ /**
+ * Transmits the command APDU stored in the command ByteBuffer and receives
+ * the reponse APDU in the response ByteBuffer.
+ *
+ * <p>The command buffer must contain valid command APDU data starting
+ * at <code>command.position()</code> and the APDU must be
+ * <code>command.remaining()</code> bytes long.
+ * Upon return, the command buffer's position will be equal
+ * to its limit; its limit will not have changed. The output buffer
+ * will have received the response APDU bytes. Its position will have
+ * advanced by the number of bytes received, which is also the return
+ * value of this method.
+ *
+ * <p>The CLA byte of the command APDU is automatically adjusted to
+ * match the channel number of this CardChannel.
+ *
+ * <p>Note that this method cannot be used to transmit
+ * <code>MANAGE CHANNEL</code> APDUs. Logical channels should be managed
+ * using the {@linkplain Card#openLogicalChannel} and {@linkplain
+ * CardChannel#close CardChannel.close()} methods.
+ *
+ * <p>See {@linkplain #transmit transmit()} for a discussion of the handling
+ * of response APDUs with the SW1 values <code>61</code> or <code>6C</code>.
+ *
+ * @param command the buffer containing the command APDU
+ * @param response the buffer that shall receive the response APDU from
+ * the card
+ * @return the length of the received response APDU
+ *
+ * @throws IllegalStateException if this channel has been
+ * {@linkplain #close closed} or if the corresponding Card has been
+ * {@linkplain Card#disconnect disconnected}.
+ * @throws NullPointerException if command or response is null
+ * @throws ReadOnlyBufferException if the response buffer is read-only
+ * @throws IllegalArgumentException if command and response are the
+ * same object, if <code>response</code> may not have
+ * sufficient space to receive the response APDU
+ * or if the APDU encodes a <code>MANAGE CHANNEL</code> command
+ * @throws CardException if the card operation failed
+ */
+ public abstract int transmit(ByteBuffer command, ByteBuffer response)
+ throws CardException;
+
+ /**
+ * Closes this CardChannel. The logical channel is closed by issuing
+ * a <code>MANAGE CHANNEL</code> command that should use the format
+ * <code>[xx 70 80 0n]</code> where <code>n</code> is the channel number
+ * of this channel and <code>xx</code> is the <code>CLA</code>
+ * byte that encodes this logical channel and has all other bits set to 0.
+ * After this method returns, calling other
+ * methods in this class will raise an IllegalStateException.
+ *
+ * <p>Note that the basic logical channel cannot be closed using this
+ * method. It can be closed by calling {@link Card#disconnect}.
+ *
+ * @throws CardException if the card operation failed
+ * @throws IllegalStateException if this CardChannel represents a
+ * connection the basic logical channel
+ */
+ public abstract void close() throws CardException;
+
+}