Package com.chilkatsoft.chilkat2

Class SCard

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.SCard
All Implemented Interfaces:
AutoCloseable
public class SCard extends ChilkatObject
<section class="scard-summary">

Communicate directly with smart card readers and cards through PC/SC.

Chilkat.SCard is the low-level PC/SC smart card interface for applications that need direct reader and card communication. It supports reader discovery, reader connection, card status checking, APDU transmission, reader-control commands, status-change monitoring, transactions, and diagnostic access to underlying PC/SC errors. Use this class when the application needs APDU-level control rather than a higher-level certificate, minidriver, or PKCS#11 abstraction.

Reader discovery

Enumerate available PC/SC smart card readers and identify the reader the application should use.

Connect to cards

Connect to a reader/card, check card presence and status, and manage the active PC/SC connection.

Transmit APDUs

Send APDU commands directly to the card and receive the raw response bytes and status words.

Reader-control commands

Issue lower-level reader control commands when supported by the reader driver and PC/SC environment.

Status monitoring

Monitor reader or card status changes so applications can detect card insertion, removal, or state changes.

Transactions and diagnostics

Use PC/SC transactions for coordinated card access and inspect detailed error information when reader or card operations fail.

Common pattern: Establish the PC/SC context, list readers, connect to the selected reader, check card status, transmit APDU commands, process the response bytes, and disconnect when finished. Use Chilkat.SCard for direct PC/SC reader and APDU-level work; use Chilkat.ScMinidriver for card-minidriver certificate and key-container operations, and Chilkat.Pkcs11 for PKCS#11 token or HSM sessions.

For an extended overview, see SCard Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • SCard

      public SCard()
      Creates a new SCard object.

  • Method Details

    • getActiveProtocol

      public String getActiveProtocol()
      The name of the active protocol if connected smart card reader, or an empty string if not connected. Possible values are T0, T1, raw, undefined, or if not connected to a reader.
      Returns:
      the value of the ActiveProtocol property (read-only)

    • getCardAtr

      public String getCardAtr()
      This is the Current ATR of a card in the connected reader.
      Returns:
      the value of the CardAtr property (read-only)

    • getConnectedReader

      public String getConnectedReader()
      The name of the currently connected smart card reader, or an empty string if not connected.
      Returns:
      the value of the ConnectedReader property (read-only)

    • getContext

      public String getContext()
      Contains the string user or system if this object has established a context (by calling EstablishContext). Contains the empty string if no context is established.
      Returns:
      the value of the Context property (read-only)

    • getPcscLibPath

      public String getPcscLibPath()
      For Linux systems only. Specifies the full path of the libpcsclite.so shared lib. This property should only be used if the libpcsclite.so is in a non-standard location or if Chilkat cannot automatically located it.
      Returns:
      the value of the PcscLibPath property

    • setPcscLibPath

      public void setPcscLibPath​(String value)
      Sets the PcscLibPath property; see getPcscLibPath().
      Parameters:
      value - the new value (not null)

    • getReaderStatus

      public String getReaderStatus()
      The current status of the connected reader. Possible values are:
      • absent - There is no card in the reader.
      • present - There is a card in the reader, but it has not been moved into position for use.
      • swallowed - There is a card in the reader in position for use. The card is not powered.
      • powered - Power is being provided to the card, but the reader driver is unaware of the mode of the card.
      • negotiable - The card has been reset and is awaiting PTS negotiation.
      • specific - The card has been reset and specific communication protocols have been established.

      Returns:
      the value of the ReaderStatus property (read-only)

    • getScardError

      public String getScardError()
      The last error returned by an underlying PC/SC function. Can be one of the following:
      • SCARD_W_REMOVED_CARD - The smart card has been removed, so that further communication is not possible.
      • SCARD_W_RESET_CARD - The smart card has been reset, so any shared state information is invalid. ...

      Returns:
      the value of the ScardError property (read-only)

    • beginTransaction

      public void beginTransaction()
      Establishes a temporary exclusive access mode for doing a series of commands in a transaction.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • checkStatus

      public boolean checkStatus()
      Check the current status of the currently connected reader. Calling this method updates the ReaderStatus, ActiveProtocol, and CardAtr properties. If this method returns false, none of the properties are updated.
      Returns:
      the result; this method never throws ChilkatException

    • connect

      public boolean connect​(String reader, String shareMode, String preferredProtocol)
      Establish a connection to a reader. The reader is the name of a reader returned from ListReaders. The shareMode can be shared, exclusive, or direct. The preferredProtocol can be 0 (valid only if the shareMode = direct), T0, T1, raw, or no_preference. (No preference is effectively T0 or T1.)

      If successful, the state of this object instance is that it's connected to the reader.

      Parameters:
      reader - the reader argument (not null)
      shareMode - the shareMode argument (not null)
      preferredProtocol - the preferredProtocol argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • disconnect

      public void disconnect​(String disposition)
      Terminates a connection with a reader. The disposition can be one of the following values:
      • leave: Do nothing.
      • reset: Reset the card (warm reset).
      • unpower: Power down the card (cold reset).
      • eject: Eject the card.

      Parameters:
      disposition - the disposition argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • endTransaction

      public void endTransaction​(String disposition)
      Ends a previously begun transaction. The disposition is the action to be taken on the reader, and can be leave which is to do nothing, reset, unpower, or eject.
      Parameters:
      disposition - the disposition argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • establishContext

      public void establishContext​(String scope)
      Creates an Application Context to the PC/SC Resource Manager. This must be the first WinSCard function called in a PC/SC application. The scope can be user or system. After calling, this object will have context and all other methods will use the established context. The Context property will hold the value user or system if context was established, or will be empty if no context was established.
      Parameters:
      scope - the scope argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • findSmartcards

      public void findSmartcards​(JsonObject json)
      Returns JSON containing information about the smartcards currently inserted into readers.
      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getAttrib

      public void getAttrib​(String attr, BinData bd)
      Get an attribute from the IFD Handler (reader driver).

      The attr can be one of the following:

      • ASYNC_PROTOCOL_TYPES
      • ATR_STRING
      • CHANNEL_ID
      • CHARACTERISTICS
      • CURRENT_BWT
      • CURRENT_CLK
      • CURRENT_CWT
      • CURRENT_D
      • CURRENT_EBC_ENCODING
      • CURRENT_F
      • CURRENT_IFSC
      • CURRENT_IFSD
      • CURRENT_IO_STATE
      • CURRENT_N
      • CURRENT_PROTOCOL_TYPE
      • CURRENT_W
      • DEFAULT_CLK
      • DEFAULT_DATA_RATE
      • DEVICE_FRIENDLY_NAME
      • DEVICE_IN_USE
      • DEVICE_SYSTEM_NAME
      • DEVICE_UNIT
      • ESC_AUTHREQUEST
      • ESC_CANCEL
      • ESC_RESET
      • EXTENDED_BWT
      • ICC_INTERFACE_STATUS
      • ICC_PRESENCE
      • ICC_TYPE_PER_ATR
      • MAX_CLK
      • MAX_DATA_RATE
      • MAX_IFSD
      • MAXINPUT
      • POWER_MGMT_SUPPORT
      • SUPRESS_T1_IFS_REQUEST
      • SYNC_PROTOCOL_TYPES
      • USER_AUTH_INPUT_DEVICE
      • USER_TO_CARD_AUTH_DEVICE
      • VENDOR_IFD_SERIAL_NO
      • VENDOR_IFD_TYPE
      • VENDOR_IFD_VERSION
      • VENDOR_NAME

      The attribute data is returned in bd.

      Parameters:
      attr - the attr argument (not null)
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getAttribStr

      public String getAttribStr​(String attr)
      Get a string typed attribute from the IFD Handler (reader driver).

      The attr can be one of the following, but should be limited to the particular attributes that return string values.

      • ASYNC_PROTOCOL_TYPES
      • ATR_STRING
      • CHANNEL_ID
      • CHARACTERISTICS
      • CURRENT_BWT
      • CURRENT_CLK
      • CURRENT_CWT
      • CURRENT_D
      • CURRENT_EBC_ENCODING
      • CURRENT_F
      • CURRENT_IFSC
      • CURRENT_IFSD
      • CURRENT_IO_STATE
      • CURRENT_N
      • CURRENT_PROTOCOL_TYPE
      • CURRENT_W
      • DEFAULT_CLK
      • DEFAULT_DATA_RATE
      • DEVICE_FRIENDLY_NAME
      • DEVICE_IN_USE
      • DEVICE_SYSTEM_NAME
      • DEVICE_UNIT
      • ESC_AUTHREQUEST
      • ESC_CANCEL
      • ESC_RESET
      • EXTENDED_BWT
      • ICC_INTERFACE_STATUS
      • ICC_PRESENCE
      • ICC_TYPE_PER_ATR
      • MAX_CLK
      • MAX_DATA_RATE
      • MAX_IFSD
      • MAXINPUT
      • POWER_MGMT_SUPPORT
      • SUPRESS_T1_IFS_REQUEST
      • SYNC_PROTOCOL_TYPES
      • USER_AUTH_INPUT_DEVICE
      • USER_TO_CARD_AUTH_DEVICE
      • VENDOR_IFD_SERIAL_NO
      • VENDOR_IFD_TYPE
      • VENDOR_IFD_VERSION
      • VENDOR_NAME

      Parameters:
      attr - the attr argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getAttribUint

      public long getAttribUint​(String attr)
      Get an unsigned integer typed attribute from the IFD Handler (reader driver).

      The attr can be one of the following, but should be limited to the particular attributes that return unsigned integer values.

      • ASYNC_PROTOCOL_TYPES
      • ATR_STRING
      • CHANNEL_ID
      • CHARACTERISTICS
      • CURRENT_BWT
      • CURRENT_CLK
      • CURRENT_CWT
      • CURRENT_D
      • CURRENT_EBC_ENCODING
      • CURRENT_F
      • CURRENT_IFSC
      • CURRENT_IFSD
      • CURRENT_IO_STATE
      • CURRENT_N
      • CURRENT_PROTOCOL_TYPE
      • CURRENT_W
      • DEFAULT_CLK
      • DEFAULT_DATA_RATE
      • DEVICE_FRIENDLY_NAME
      • DEVICE_IN_USE
      • DEVICE_SYSTEM_NAME
      • DEVICE_UNIT
      • ESC_AUTHREQUEST
      • ESC_CANCEL
      • ESC_RESET
      • EXTENDED_BWT
      • ICC_INTERFACE_STATUS
      • ICC_PRESENCE
      • ICC_TYPE_PER_ATR
      • MAX_CLK
      • MAX_DATA_RATE
      • MAX_IFSD
      • MAXINPUT
      • POWER_MGMT_SUPPORT
      • SUPRESS_T1_IFS_REQUEST
      • SYNC_PROTOCOL_TYPES
      • USER_AUTH_INPUT_DEVICE
      • USER_TO_CARD_AUTH_DEVICE
      • VENDOR_IFD_SERIAL_NO
      • VENDOR_IFD_TYPE
      • VENDOR_IFD_VERSION
      • VENDOR_NAME

      Returns 0xFFFFFFFF on failure.

      Parameters:
      attr - the attr argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getStatusChange

      public void getStatusChange​(int maxWaitMs, StringTable stReaderNames, JsonObject json)
      Blocks execution until the current availability of the cards in a specific set of readers changes.

      This function receives a list of reader names in stReaderNames. It then blocks waiting for a change in state to occur for a maximum blocking time of maxWaitMs (in milliseconds) or forever if 0 is used.

      Information about the current reader states and which reader(s) changed is returned in json. See the example below for more information.

      To wait for a reader event (reader added or removed) you may use the special reader name \\?PnP?\Notification.

      To cancel the ongoing call, call Cancel().

      The stReaderNames contains the reader names to check. The json is empty on input, and if the call returns success contains information about the state (after the event change) of each reader.

      Parameters:
      maxWaitMs - the maxWaitMs argument
      stReaderNames - the stReaderNames argument (not null)
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getStatusChangeCancel

      public void getStatusChangeCancel()
      Cancels an ongoing GetStatusChange method call. This would be called from a separate thread in your application if GetStatusChange was called synchronously.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • listReaderGroups

      public void listReaderGroups​(StringTable readerGroups)
      Returns a list of currently available reader groups on the system. The reader groups are returned in readerGroups.
      Parameters:
      readerGroups - the readerGroups argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • listReaders

      public void listReaders​(StringTable st)
      Returns a list of currently available readers on the system.
      Parameters:
      st - the st argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • reconnect

      public void reconnect​(String shareMode, String preferredProtocol, String action)
      Reestablishes a connection to a reader that was previously connected to using Connect().

      In a multi application environment it is possible for an application to reset the card in shared mode. When this occurs any other application trying to access certain commands will be returned the value SCARD_W_RESET_CARD. When this occurs Reconnect() must be called in order to acknowledge that the card was reset and allow it to change its state accordingly.

      The shareMode can be shared, exclusive, or direct. The preferredProtocol can be 0 (valid only if the shareMode = direct), T0, T1, raw, or no_preference. (No preference is effectively T0 or T1.) The action is the desired action taken on the card/reader. It can be leave, reset, unpower, or eject.

      If successful, the state of this object instance is that it's connected to the reader.

      Parameters:
      shareMode - the shareMode argument (not null)
      preferredProtocol - the preferredProtocol argument (not null)
      action - the action argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • releaseContext

      public void releaseContext()
      Destroys a communication context to the PC/SC Resource Manager. This must be the last function called in a PC/SC application.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendControl

      public void sendControl​(long controlCode, BinData bdSend, BinData bdRecv)
      Sends a command directly to the IFD Handler (reader driver) to be processed by the reader.

      This is useful for creating client side reader drivers for functions like PIN pads, biometrics, or other extensions to the normal smart card reader that are not normally handled by PC/SC.

      The command data is sent in bdSend. The response is written to bdRecv.

      Parameters:
      controlCode - the controlCode argument (0 .. 4294967295)
      bdSend - the bdSend argument (not null)
      bdRecv - the bdRecv argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendControlHex

      public void sendControlHex​(long controlCode, String sendData, BinData bdRecv)
      Sends a command directly to the IFD Handler (reader driver) to be processed by the reader.

      This is useful for creating client side reader drivers for functions like PIN pads, biometrics, or other extensions to the normal smart card reader that are not normally handled by PC/SC.

      The command data is provided as a hex string in sendData. The response is written to bdRecv.

      Parameters:
      controlCode - the controlCode argument (0 .. 4294967295)
      sendData - the sendData argument (not null)
      bdRecv - the bdRecv argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • transmit

      public void transmit​(String protocolName, BinData bdSend, BinData bdRecv, int maxRecvLen)
      Sends an APDU to the smart card contained in the currently connected reader. The protocolName can be T0, T1, or raw. The APDU to be sent is contained in bdSend. The response from the card is contained in bdRecv. The maxRecvLen is the maximum response size (in bytes) willing to be accepted.
      Parameters:
      protocolName - the protocolName argument (not null)
      bdSend - the bdSend argument (not null)
      bdRecv - the bdRecv argument (not null)
      maxRecvLen - the maxRecvLen argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • transmitHex

      public void transmitHex​(String protocolName, String apduHex, BinData bdRecv, int maxRecvLen)
      Sends an APDU to the smart card contained in the currently connected reader. The protocolName can be T0, T1, or raw. The APDU (in hexadecimal) to be sent is passed in apduHex. The response from the card is contained in bdRecv. The maxRecvLen is the maximum response size (in bytes) willing to be accepted.
      Parameters:
      protocolName - the protocolName argument (not null)
      apduHex - the apduHex argument (not null)
      bdRecv - the bdRecv argument (not null)
      maxRecvLen - the maxRecvLen argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener