Chilkat.SCard Class Overview
Chilkat.SCard provides a PC/SC interface for working with smart
card readers and inserted smart cards. It can establish a PC/SC context, list
readers, connect to a reader, check card status, monitor reader/card changes,
transmit APDU commands, send reader-control commands, inspect reader attributes,
and manage transactions.
What the Class Is Used For
Use Chilkat.SCard when an application needs direct
PC/SC-level access to smart card readers and cards. It is useful for reader
discovery, APDU communication, reader status monitoring, reader-driver attributes,
direct control commands, and low-level smart card workflows that sit beneath
higher-level classes such as ScMinidriver.
Reader Discovery
List available smart card readers and reader groups, or find smart cards
currently inserted into readers.
PC/SC Context Management
Establish and release the application context used for PC/SC Resource Manager
operations.
Reader Connection
Connect, reconnect, disconnect, check reader status, and inspect the active
protocol and card ATR.
APDU and Control Commands
Transmit APDUs to the card or send direct control commands to the reader driver.
Typical Workflow
-
Call EstablishContext with
user or system to create
a PC/SC application context.
-
Call ListReaders to get available reader names, or
FindSmartcards to discover cards currently inserted
in readers.
-
Call Connect with the reader name, share mode, and
preferred protocol.
-
Call CheckStatus to update
ReaderStatus,
ActiveProtocol, and
CardAtr.
-
Use Transmit or
TransmitHex to send APDU commands to the smart card.
-
Use BeginTransaction and
EndTransaction when a sequence of commands should
have temporary exclusive access.
-
Call Disconnect when finished with the reader.
-
Call ReleaseContext as the final PC/SC operation.
Order matters:
EstablishContext should be the first PC/SC operation,
and ReleaseContext should be the last.
Core Concepts
| Concept |
Meaning |
Important Members |
| PC/SC Context |
An application context to the PC/SC Resource Manager. Most operations require
this context to be established first.
|
EstablishContext,
ReleaseContext,
Context
|
| Reader |
A smart card reader available on the system. A reader may or may not
currently contain a card.
|
ListReaders,
ConnectedReader,
ReaderStatus
|
| Card ATR |
The Answer To Reset value from the card. It identifies card capabilities and
is updated when reader status is checked.
|
CardAtr,
CheckStatus
|
| Active Protocol |
The protocol negotiated or used for the connected reader/card session.
|
ActiveProtocol,
Connect,
Reconnect
|
| APDU Transmission |
Low-level command/response communication with the smart card.
|
Transmit,
TransmitHex
|
| Reader Driver Control |
Commands sent directly to the IFD Handler, useful for reader-specific
functions such as PIN pads or biometric extensions.
|
SendControl,
SendControlHex
|
| Status Change Monitoring |
Blocking wait for card or reader state changes across selected readers.
|
GetStatusChange,
GetStatusChangeCancel
|
Core Properties
| Property |
Purpose |
Guidance |
| Context |
Indicates whether a PC/SC context has been established.
|
Contains user,
system, or an empty string when no context exists.
|
| ConnectedReader |
Name of the currently connected smart card reader.
|
Empty when not connected.
|
| ActiveProtocol |
Current protocol for the connected reader/card.
|
Possible values include T0,
T1, raw,
undefined, or empty when not connected.
|
| CardAtr |
Current ATR of the card in the connected reader.
|
Updated by CheckStatus.
|
| ReaderStatus |
Current status of the connected reader/card.
|
Updated by CheckStatus.
|
| ScardError |
Last error returned by an underlying PC/SC function.
|
Useful when diagnosing low-level smart card or reader failures.
|
| PcscLibPath |
Linux-only override for the full path to
libpcsclite.so.
|
Use only if the library is in a non-standard location or cannot be located
automatically.
|
| LastErrorText |
Detailed information about the last method call or property access.
|
Check after failures or unexpected behavior.
|
Context, Reader Discovery, and Connection
| Task |
Method |
Notes |
| Create PC/SC context |
EstablishContext |
Must be called before other PC/SC operations. The scope can be
user or system.
|
| Release PC/SC context |
ReleaseContext |
Destroys the PC/SC context. This should be the last PC/SC operation.
|
| List reader groups |
ListReaderGroups |
Returns the currently available reader groups in a
StringTable.
|
| List readers |
ListReaders |
Returns currently available smart card readers in a
StringTable.
|
| Find inserted smart cards |
FindSmartcards |
Returns JSON containing information about smart cards currently inserted
into readers.
|
| Connect to a reader |
Connect |
Connects using a reader name, share mode, and preferred protocol.
|
| Reconnect to a reader |
Reconnect |
Used to acknowledge and recover when another application resets the card
and PC/SC reports SCARD_W_RESET_CARD.
|
| Disconnect from reader |
Disconnect |
Terminates the reader connection and applies the requested disposition:
leave, reset, unpower, or eject.
|
Connection Options
| Option |
Allowed Values |
Used By |
| Share mode |
shared,
exclusive,
direct
|
Connect,
Reconnect
|
| Preferred protocol |
0,
T0,
T1,
raw,
no_preference
|
Connect,
Reconnect
|
| Disposition |
leave,
reset,
unpower,
eject
|
Disconnect,
EndTransaction,
Reconnect
|
Direct mode note:
The preferred protocol value 0 is valid only when
the share mode is direct.
Reader Status
CheckStatus updates the reader/card status properties
for the currently connected reader.
| ReaderStatus Value |
Meaning |
| 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 position for use, but the card is not powered. |
| powered |
Power is being provided to the card, but the reader driver is unaware of the card mode. |
| negotiable |
The card has been reset and is awaiting PTS negotiation. |
| specific |
The card has been reset and specific communication protocols have been established. |
Status update rule:
If CheckStatus returns false,
ReaderStatus, ActiveProtocol,
and CardAtr are not updated.
Transactions
Transactions provide temporary exclusive access while a sequence of commands is
performed. This helps prevent other applications from interfering with a multi-step
card operation.
| Task |
Method |
Guidance |
| Begin temporary exclusive access |
BeginTransaction |
Use before a sequence of related APDU or reader operations that should not
be interrupted.
|
| End transaction |
EndTransaction |
Ends the transaction and applies a disposition:
leave, reset,
unpower, or eject.
|
APDU Transmission
The primary smart card communication methods are
Transmit and TransmitHex.
These send APDU commands to the card in the currently connected reader and place
the response bytes in a BinData object.
| Method |
Input Format |
Response |
| Transmit |
APDU bytes provided in a BinData object.
|
Response bytes are written to a BinData object.
|
| TransmitHex |
APDU bytes provided as a hexadecimal string.
|
Response bytes are written to a BinData object.
|
| Argument |
Meaning |
| protocol |
One of T0, T1, or
raw.
|
| bdSend / apduHex |
The APDU command to send, either as binary data or hex text.
|
| bdRecv |
Receives the card response.
|
| maxRecvLen |
Maximum number of response bytes the application is willing to accept.
|
Protocol tip:
After connecting, inspect ActiveProtocol to know
which protocol is active for the current reader/card connection.
Reader Attributes
Attribute methods retrieve information from the IFD Handler, which is the reader
driver. Attributes may be binary, string, or unsigned integer values depending on
the attribute.
| Need |
Method |
Return Type |
| Get binary attribute data |
GetAttrib |
Writes data to a BinData object.
|
| Get string attribute data |
GetAttribStr |
Returns a string value.
|
| Get unsigned integer attribute data |
GetAttribUint |
Returns an unsigned integer, or 0xFFFFFFFF on failure.
|
| Common Attribute Category |
Examples |
| Device identity |
DEVICE_FRIENDLY_NAME,
DEVICE_SYSTEM_NAME,
VENDOR_NAME,
VENDOR_IFD_TYPE,
VENDOR_IFD_VERSION
|
| Card presence and interface |
ATR_STRING,
ICC_PRESENCE,
ICC_INTERFACE_STATUS,
ICC_TYPE_PER_ATR
|
| Current protocol settings |
CURRENT_PROTOCOL_TYPE,
CURRENT_CLK,
CURRENT_F,
CURRENT_D,
CURRENT_N,
CURRENT_W
|
| Reader capability limits |
MAX_CLK,
MAX_DATA_RATE,
MAX_IFSD,
MAXINPUT
|
| User-authentication devices |
USER_AUTH_INPUT_DEVICE,
USER_TO_CARD_AUTH_DEVICE
|
Type reminder:
Use GetAttribStr only for attributes that actually
return string values, and GetAttribUint only for
attributes that return unsigned integer values.
Status Change Monitoring
GetStatusChange blocks until one or more selected
readers change state, or until the specified timeout expires.
| Need |
Method / Value |
Notes |
| Wait for reader/card state changes |
GetStatusChange |
Takes a list of reader names in a StringTable
and writes updated reader state information to a
JsonObject.
|
| Wait indefinitely |
maxWaitMs = 0 |
Blocks forever until a state change occurs or the call is cancelled.
|
| Monitor reader arrival/removal |
\\?PnP?\Notification |
Special reader name used to wait for reader events, such as a reader being
added or removed.
|
| Cancel a blocking wait |
GetStatusChangeCancel |
Call from another thread to cancel an ongoing synchronous
GetStatusChange.
|
Reader Control Commands
SendControl and
SendControlHex send commands directly to the IFD
Handler, which is the reader driver. These are useful for reader-specific features
that are outside normal smart card APDU communication.
| Method |
Input Format |
Typical Use |
| SendControl |
Command data in a BinData object.
|
Sends binary control data to the reader driver.
|
| SendControlHex |
Command data as a hexadecimal string.
|
Convenient when reader control commands are documented as hex bytes.
|
Reader-driver feature area:
Control commands are useful for reader-side extensions such as PIN pads,
biometrics, or other reader-specific functionality not normally handled by PC/SC.
Diagnostics and Troubleshooting
| Problem Area |
Member |
What to Check |
| General method failure |
LastErrorText |
Provides detailed information about the last method call or property access.
|
| Underlying PC/SC failure |
ScardError |
Contains the last error returned by an underlying PC/SC function, such as
SCARD_W_REMOVED_CARD or
SCARD_W_RESET_CARD.
|
| No context established |
Context,
EstablishContext
|
Confirm that context was established before listing readers, connecting,
or transmitting APDUs.
|
| No readers found |
ListReaders,
ListReaderGroups
|
Verify reader installation, driver availability, and PC/SC service state.
On Linux, check whether PcscLibPath is needed.
|
| Card removed or reset |
ScardError,
Reconnect
|
If another application reset the card and
SCARD_W_RESET_CARD is reported, call
Reconnect.
|
| APDU response too large or missing |
Transmit,
TransmitHex,
maxRecvLen
|
Confirm the protocol, APDU bytes, and maximum receive length.
|
| Status wait needs cancellation |
GetStatusChangeCancel |
Call from a separate thread to cancel an ongoing blocking
GetStatusChange.
|
Best Practices
| Recommendation |
Reason |
| Call EstablishContext before any other PC/SC operation. |
The PC/SC Resource Manager context is required for reader discovery,
connection, status, APDU, and control operations.
|
| Call ReleaseContext when finished. |
It cleanly destroys the PC/SC context and should be the final PC/SC call.
|
| Use ListReaders or FindSmartcards before connecting. |
Reader names must match the names returned by the system.
|
| Use CheckStatus after connecting. |
It updates ReaderStatus,
ActiveProtocol, and
CardAtr.
|
| Use transactions for multi-step command sequences. |
BeginTransaction and
EndTransaction help prevent other applications
from interfering during related card commands.
|
| Use TransmitHex when APDUs are documented as hex. |
It avoids manual conversion to binary data and makes examples easier to read.
|
| Use Reconnect after SCARD_W_RESET_CARD. |
It acknowledges that the card was reset and allows the object to update its
state accordingly.
|
| Check both LastErrorText and ScardError after failures. |
LastErrorText gives Chilkat diagnostic detail,
while ScardError exposes the underlying PC/SC
error.
|
Summary
Chilkat.SCard is the low-level PC/SC smart card
interface for reader discovery, reader connection, status checking, APDU
transmission, reader-control commands, status-change monitoring, transactions,
and diagnostic access to underlying PC/SC errors. It is the right class when an
application needs direct smart card reader/card communication rather than a
higher-level certificate, minidriver, or PKCS#11 abstraction.
For card-minidriver certificate and key-container operations, use
Chilkat.ScMinidriver. For PKCS#11 token/HSM
sessions, use Chilkat.Pkcs11. Use
SCard for direct PC/SC reader and APDU-level work.