1 /* 2 * Copyright (c) 2005, 2006, 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 26 package javax.smartcardio; 27 28 import java.nio.ByteBuffer; 29 30 /** 31 * A Smart Card with which a connection has been established. Card objects 32 * are obtained by calling {@link CardTerminal#connect CardTerminal.connect()}. 33 * 34 * @see CardTerminal 35 * 36 * @since 1.6 37 * @author Andreas Sterbenz 38 * @author JSR 268 Expert Group 39 */ 40 public abstract class Card { 41 42 /** 43 * Constructs a new Card object. 44 * 45 * <p>This constructor is called by subclasses only. Application should 46 * call the {@linkplain CardTerminal#connect CardTerminal.connect()} 47 * method to obtain a Card 48 * object. 49 */ 50 protected Card() { 51 // empty 52 } 53 54 /** 55 * Returns the ATR of this card. 56 * 57 * @return the ATR of this card. 58 */ 59 public abstract ATR getATR(); 60 61 /** 62 * Returns the protocol in use for this card. 63 * 64 * @return the protocol in use for this card, for example "T=0" or "T=1" 65 */ 66 public abstract String getProtocol(); 67 68 /** 69 * Returns the CardChannel for the basic logical channel. The basic 70 * logical channel has a channel number of 0. 71 * 72 * @return the CardChannel for the basic logical channel 73 * @throws SecurityException if a SecurityManager exists and the 74 * caller does not have the required 75 * {@linkplain CardPermission permission} 76 * @throws IllegalStateException if this card object has been disposed of 77 * via the {@linkplain #disconnect disconnect()} method 78 */ 79 public abstract CardChannel getBasicChannel(); 80 81 /** 82 * Opens a new logical channel to the card and returns it. The channel is 83 * opened by issuing a <code>MANAGE CHANNEL</code> command that should use 84 * the format <code>[00 70 00 00 01]</code>. 85 * 86 * @return the card to which a logical channel has been opened 87 * @throws SecurityException if a SecurityManager exists and the 88 * caller does not have the required 89 * {@linkplain CardPermission permission} 90 * @throws CardException is a new logical channel could not be opened 91 * @throws IllegalStateException if this card object has been disposed of 92 * via the {@linkplain #disconnect disconnect()} method 93 */ 94 public abstract CardChannel openLogicalChannel() throws CardException; 95 96 /** 97 * Requests exclusive access to this card. 98 * 99 * <p>Once a thread has invoked <code>beginExclusive</code>, only this 100 * thread is allowed to communicate with this card until it calls 101 * <code>endExclusive</code>. Other threads attempting communication 102 * will receive a CardException. 103 * 104 * <p>Applications have to ensure that exclusive access is correctly 105 * released. This can be achieved by executing 106 * the <code>beginExclusive()</code> and <code>endExclusive</code> calls 107 * in a <code>try ... finally</code> block. 108 * 109 * @throws SecurityException if a SecurityManager exists and the 110 * caller does not have the required 111 * {@linkplain CardPermission permission} 112 * @throws CardException if exclusive access has already been set 113 * or if exclusive access could not be established 114 * @throws IllegalStateException if this card object has been disposed of 115 * via the {@linkplain #disconnect disconnect()} method 116 */ 117 public abstract void beginExclusive() throws CardException; 118 119 /** 120 * Releases the exclusive access previously established using 121 * <code>beginExclusive</code>. 122 * 123 * @throws SecurityException if a SecurityManager exists and the 124 * caller does not have the required 125 * {@linkplain CardPermission permission} 126 * @throws IllegalStateException if the active Thread does not currently have 127 * exclusive access to this card or 128 * if this card object has been disposed of 129 * via the {@linkplain #disconnect disconnect()} method 130 * @throws CardException if the operation failed 131 */ 132 public abstract void endExclusive() throws CardException; 133 134 /** 135 * Transmits a control command to the terminal device. 136 * 137 * <p>This can be used to, for example, control terminal functions like 138 * a built-in PIN pad or biometrics. 139 * 140 * @param controlCode the control code of the command 141 * @param command the command data 142 * @return the response from the terminal device 143 * 144 * @throws SecurityException if a SecurityManager exists and the 145 * caller does not have the required 146 * {@linkplain CardPermission permission} 147 * @throws NullPointerException if command is null 148 * @throws CardException if the card operation failed 149 * @throws IllegalStateException if this card object has been disposed of 150 * via the {@linkplain #disconnect disconnect()} method 151 */ 152 public abstract byte[] transmitControlCommand(int controlCode, 153 byte[] command) throws CardException; 154 155 /** 156 * Disconnects the connection with this card. After this method returns, 157 * calling methods on this object or in CardChannels associated with this 158 * object that require interaction with the card will raise an 159 * IllegalStateException. 160 * 161 * @param reset whether to reset the card after disconnecting. 162 * 163 * @throws CardException if the card operation failed 164 * @throws SecurityException if a SecurityManager exists and the 165 * caller does not have the required 166 * {@linkplain CardPermission permission} 167 */ 168 public abstract void disconnect(boolean reset) throws CardException; 169 170 }