/* * Copyright (c) 2005, 2006, Oracle and/or its affiliates. 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.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.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; }