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 * @throws SecurityException if a SecurityManager exists and the 73 * caller does not have the required 74 * {@linkplain CardPermission permission} 75 * @throws IllegalStateException if this card object has been disposed of 76 * via the {@linkplain #disconnect disconnect()} method 77 */ 78 public abstract CardChannel getBasicChannel(); 79 80 /** 81 * Opens a new logical channel to the card and returns it. The channel is 82 * opened by issuing a <code>MANAGE CHANNEL</code> command that should use 83 * the format <code>[00 70 00 00 01]</code>. 84 * 85 * @throws SecurityException if a SecurityManager exists and the 86 * caller does not have the required 87 * {@linkplain CardPermission permission} 88 * @throws CardException is a new logical channel could not be opened 89 * @throws IllegalStateException if this card object has been disposed of 90 * via the {@linkplain #disconnect disconnect()} method 91 */ 92 public abstract CardChannel openLogicalChannel() throws CardException; 93 94 /** 95 * Requests exclusive access to this card. 96 * 97 * <p>Once a thread has invoked <code>beginExclusive</code>, only this 98 * thread is allowed to communicate with this card until it calls 99 * <code>endExclusive</code>. Other threads attempting communication 100 * will receive a CardException. 101 * 102 * <p>Applications have to ensure that exclusive access is correctly 103 * released. This can be achieved by executing 104 * the <code>beginExclusive()</code> and <code>endExclusive</code> calls 105 * in a <code>try ... finally</code> block. 106 * 107 * @throws SecurityException if a SecurityManager exists and the 108 * caller does not have the required 109 * {@linkplain CardPermission permission} 110 * @throws CardException if exclusive access has already been set 111 * or if exclusive access could not be established 112 * @throws IllegalStateException if this card object has been disposed of 113 * via the {@linkplain #disconnect disconnect()} method 114 */ 115 public abstract void beginExclusive() throws CardException; 116 117 /** 118 * Releases the exclusive access previously established using 119 * <code>beginExclusive</code>. 120 * 121 * @throws SecurityException if a SecurityManager exists and the 122 * caller does not have the required 123 * {@linkplain CardPermission permission} 124 * @throws IllegalStateException if the active Thread does not currently have 125 * exclusive access to this card or 126 * if this card object has been disposed of 127 * via the {@linkplain #disconnect disconnect()} method 128 * @throws CardException if the operation failed 129 */ 130 public abstract void endExclusive() throws CardException; 131 132 /** 133 * Transmits a control command to the terminal device. 134 * 135 * <p>This can be used to, for example, control terminal functions like 136 * a built-in PIN pad or biometrics. 137 * 138 * @param controlCode the control code of the command 139 * @param command the command data 140 * 141 * @throws SecurityException if a SecurityManager exists and the 142 * caller does not have the required 143 * {@linkplain CardPermission permission} 144 * @throws NullPointerException if command is null 145 * @throws CardException if the card operation failed 146 * @throws IllegalStateException if this card object has been disposed of 147 * via the {@linkplain #disconnect disconnect()} method 148 */ 149 public abstract byte[] transmitControlCommand(int controlCode, 150 byte[] command) throws CardException; 151 152 /** 153 * Disconnects the connection with this card. After this method returns, 154 * calling methods on this object or in CardChannels associated with this 155 * object that require interaction with the card will raise an 156 * IllegalStateException. 157 * 158 * @param reset whether to reset the card after disconnecting. 159 * 160 * @throws CardException if the card operation failed 161 * @throws SecurityException if a SecurityManager exists and the 162 * caller does not have the required 163 * {@linkplain CardPermission permission} 164 */ 165 public abstract void disconnect(boolean reset) throws CardException; 166 167 }