| /* |
| * 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; |
| |
| } |
