/* |
|
* Copyright (c) 2005, 2013, 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 response 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; |
|
} |