NAME
PCSC
DESCRIPTION
SpringCard's wrapper for PC/SC API
COPYRIGHT
Copyright (c) 2010-2012 SpringCard - www.springcard.com
AUTHOR
Johann.D and Emilie.C / SpringCard
HISTORY
ECL ../../2009 : early drafts JDA 21/04/2010 : first official release JDA 20/11/2010 : improved the SCardChannel object: implemented SCardControl, exported the hCard JDA 24/01/2011 : added static DefaultReader and DefaultCardChannel to ease 'quick and dirty' development for simple applications JDA 25/01/2011 : added SCardChannel.Reconnect methods JDA 16/01/2012 : improved CardBuffer, CAPDU and RAPDU objects for robustness JDA 12/02/2012 : added the SCardReaderList object to monitor all the readers JDA 26/03/2012 : added SCARD_PCI_T0, SCARD_PCI_T1 and SCARD_PCI_RAW JDA 07/02/2012 : minor improvements
PORTABILITY
.NET on Win32 (not yet validated on Win64 --> please compile for x86 target)
NAME
SCARD.CardProtocolToString
DESCRIPTION
Translate the Protocol of the card into a user-readable string
SYNOPSIS
string SCARD.CardProtocolToString( uint protocol );
NAME
SCARD.CardShareModeToString
DESCRIPTION
Translate the Share Mode of the card into a user-readable string
SYNOPSIS
string SCARD.CardShareModeToString( uint share_mode );
NAME
SCARD.CardStatusWordsToString
DESCRIPTION
Translate the Status Word of the card into a user-readable string
SYNOPSIS
string SCARD.CardStatusWordsToString( byte SW1, byte SW2 ); string SCARD.CardStatusWordsToString( ushort SW );
NAME
SCARD.Connect
DESCRIPTION
.NET wrapper for SCardConnect (UNICODE implementation)
NAME
SCARD.Control
DESCRIPTION
.NET wrapper for SCardControl
NAME
SCARD.Disconnect
DESCRIPTION
.NET wrapper for SCardDisconnect
NAME
SCARD.ErrorToString
DESCRIPTION
Translate a PC/SC error code into a user-readable string
SYNOPSIS
string SCARD.ErrorToString( uint code );
NAME
SCARD.EstablishContext
DESCRIPTION
.NET wrapper for SCardEstablishContext
NAME
SCARD.GetStatusChange
DESCRIPTION
.NET wrapper for SCardGetStatusChange (UNICODE implementation)
NAME
SCARD.ListReaders
DESCRIPTION
.NET wrapper for SCardListReaders (UNICODE implementation)
NAME
SCARD.Readers
DESCRIPTION
Provides the list of the connected PC/SC readers
SYNOPSIS
string[] SCARD.Readers
NAME
SCARD.ReaderStatusToString
DESCRIPTION
Translate the Status of the reader into a user-readable string
SYNOPSIS
string SCARD.ReaderStatusToString( uint state );
NAME
SCARD.Reconnect
DESCRIPTION
.NET wrapper for SCardReconnect
NAME
SCARD.ReleaseContext
DESCRIPTION
.NET wrapper for SCardReleaseContext
NAME
SCARD.Status
DESCRIPTION
.NET wrapper for SCardStatus (UNICODE version)
NAME
SCARD.Transmit
DESCRIPTION
.NET wrapper for SCardTransmit
NAME
SCardChannel.CardAtr
SYNOPSIS
CardBuffer CardAtr
OUTPUT
Returns the ATR of the smartcard in the reader, or null if no smartcard is present.
SEE ALSO
SCardChannel.CardPresent
NAME
SCardChannel.CardAvailable
SYNOPSIS
bool CardAvailable
OUTPUT
Returns true if a card is available in the reader associated to the SCardChannel object. Returns false if there's no smartcard in the reader, or if it is already used by another process/thread.
SEE ALSO
SCardChannel.CardPresent SCardChannel.CardAtr
NAME
SCardChannel.CardPresent
SYNOPSIS
bool CardPresent
OUTPUT
Returns true if a card is present in the reader associated to the SCardChannel object. Returns false if there's no smartcard in the reader.
SEE ALSO
SCardChannel.CardAvailable SCardChannel.CardAtr
NAME
SCardChannel.Command
SYNOPSIS
CAPDU Command
DESCRIPTION
C-APDU to be sent to the card through SCardChannel.Transmit
NAME
SCardChannel.Connect()
SYNOPSIS
bool Connect()
DESCRIPTION
Open the connection channel to the smartcard (according to the specified Protocol, default is either T=0 or T=1)
OUTPUT
Returns true if the connection has been successfully established. Returns false if not. See LastError for details.
SEE ALSO
SCardChannel.CardPresent SCardChannel.CardAtr SCardChannel.Protocol SCardChannel.Transmit
NAME
SCardChannel.Connected
SYNOPSIS
bool Connected
OUTPUT
Returns true if the SCardChannel object is actually connected to a smartcard. Returns false if not.
NAME
SCardChannel.Disconnect()
SYNOPSIS
bool Disconnect() bool Disconnect(uint disposition)
DESCRIPTION
Close the connection channel
INPUTS
The disposition parameter must take one of the following values: - SCARD.EJECT_CARD - SCARD.UNPOWER_CARD - SCARD.RESET_CARD - SCARD.LEAVE_CARD If this parameter is omitted, it defaults to SCARD.RESET_CARD
SEE ALSO
SCardChannel.Connect
NAME
SCardChannel.DisconnectEject()
SYNOPSIS
bool DisconnectEject()
DESCRIPTION
Same as SCardChannel.Disconnect(SCARD.EJECT_CARD)
NAME
SCardChannel.DisconnectLeave()
SYNOPSIS
void DisconnectLeave()
DESCRIPTION
Same as SCardChannel.Disconnect(SCARD.LEAVE_CARD)
NAME
SCardChannel.DisconnectReset()
SYNOPSIS
bool DisconnectReset()
DESCRIPTION
Same as SCardChannel.Disconnect(SCARD.RESET_CARD)
NAME
SCardChannel.DisconnectUnpower()
SYNOPSIS
bool DisconnectUnpower()
DESCRIPTION
Same as SCardChannel.Disconnect(SCARD.UNPOWER_CARD)
NAME
SCardChannel.LastError
SYNOPSIS
uint LastError
OUTPUT
Returns the last error encountered by the object when working with SCARD functions.
SEE ALSO
SCardChannel.LastErrorAsString
NAME
SCardChannel.LastErrorAsString
SYNOPSIS
string LastErrorAsString
OUTPUT
Returns the last error encountered by the object when working with SCARD functions.
SEE ALSO
SCardChannel.LastError
NAME
SCardChannel.Protocol
SYNOPSIS
uint Protocol
INPUTS
Before the smartcard has been , set Protocol to specify the communication protocol(s) to be used by Connect(). Allowed values are SCARD.PROTOCOL_T0, SCARD.PROTOCOL_T1 or SCARD.PROTOCOL_T0|SCARD.PROTOCOL_T1.
OUTPUT
Once the smartcard has been connected (Connected == true), Protocol is the current communication protocol. Possible values are SCARD.PROTOCOL_T0 or SCARD.PROTOCOL_T1.
SEE ALSO
SCardChannel.ProtocolAsString
NAME
SCardChannel.ProtocolAsString
SYNOPSIS
string ProtocolAsString
INPUTS
Before the smartcard has been connected, set ProtocolAsString to specify the communication protocol(s) to be used by Connect(). Allowed values are "T=0", "T=1" or "*" (or "T=0|T=1").
OUTPUT
Once the smartcard has been connected (Connected == true), ProtocolAsString is the current communication protocol. Possible values are "T=0" or "T=1".
SEE ALSO
SCardChannel.Protocol
NAME
SCardChannel.Reconnect()
SYNOPSIS
bool Reconnect() bool Reconnect(uint disposition)
DESCRIPTION
Re-open the connection channel to the smartcard
INPUTS
The disposition parameter must take one of the following values: - SCARD.EJECT_CARD - SCARD.UNPOWER_CARD - SCARD.RESET_CARD - SCARD.LEAVE_CARD If this parameter is omitted, it defaults to SCARD.RESET_CARD
OUTPUT
Returns true if the connection has been successfully re-established. Returns false if not. See LastError for details.
SEE ALSO
SCardChannel.Connect SCardChannel.Disconnect
NAME
SCardChannel.ReconnectEject()
SYNOPSIS
void ReconnectEject()
DESCRIPTION
Same as SCardChannel.Reconnect(SCARD.EJECT_CARD)
NAME
SCardChannel.ReconnectLeave()
SYNOPSIS
void ReconnectLeave()
DESCRIPTION
Same as SCardChannel.Reconnect(SCARD.LEAVE_CARD)
NAME
SCardChannel.ReconnectReset()
SYNOPSIS
void ReconnectReset()
DESCRIPTION
Same as SCardChannel.Disconnect(SCARD.RESET_CARD)
NAME
SCardChannel.ReconnectUnpower()
SYNOPSIS
void ReconnectUnpower()
DESCRIPTION
Same as SCardChannel.Reconnect(SCARD.UNPOWER_CARD)
NAME
SCardChannel.Response
SYNOPSIS
RAPDU Response
DESCRIPTION
R-APDU returned by the card after a succesfull call to SCardChannel.Transmit
NAME
SCardChannel.ShareMode
SYNOPSIS
uint ShareMode
INPUTS
Before the smartcard has been connected, set ShareMode to specify the sharing mode to be used by Connect(). Allowed values are SCARD.SHARE_EXCLUSIVE, SCARD.SHARE_SHARED or SCARD.SHARE_DIRECT.
SEE ALSO
SCardChannel.ShareModeAsString
NAME
SCardChannel.ShareModeAsString
SYNOPSIS
string ShareModeAsString
INPUTS
Before the smartcard has been connected, set ShareModeAsString to specify the sharing mode to be used by Connect(). Allowed values are "EXCLUSIVE", "SHARED" or "DIRECT".
SEE ALSO
SCardChannel.ShareMode
NAME
SCardChannel.Transmit()
SYNOPSIS
bool Transmit() RAPDU Transmit(CAPDU capdu) bool Transmit(CAPDU capdu, ref RAPDU rapdu) void Transmit(CAPDU capdu, TransmitDoneCallback callback)
DESCRIPTION
Sends a command APDU (CAPDU) to the connected card, and retrieves its response APDU (RAPDU)
SOURCE
SCardChannel card = new SCardChannel( ... reader ... ); if (!card.Connect( SCARD.PROTOCOL_T0|SCARD.PROTOCOL_T1 )) { // handle error } // Example 1 // --------- card.Command = new CAPDU("00 A4 00 00 02 3F 00"); if (!card.Transmit()) { // handle error } MessageBox.Show("Card answered: " + card.Response.AsString(" ")); // Example 2 // --------- RAPDU response = card.Transmit(new CAPDU("00 A4 00 00 02 3F 00"))) if (response == null) { // handle error } MessageBox.Show("Card answered: " + response.AsString(" ")); // Example 3 // --------- CAPDU command = new CAPDU("00 A4 00 00 02 3F 00"); RAPDU response = new RAPDU(); if (!card.Transmit(command, ref response)) { // handle error } MessageBox.Show("Card answered: " + response.AsString(" ")); // Example 4 // --------- // In this example the Transmit is performed by a background thread // We supply a delegate so the main class (window/form) will be notified // when Transmit will return delegate void OnTransmitDoneInvoker(RAPDU response); void OnTransmitDone(RAPDU response) { // Ensure we're back in the context of the main thread (application's message pump) if (this.InvokeRequired) { this.BeginInvoke(new OnTransmitDoneInvoker(OnTransmitDone), response); return; } if (response == null) { // handle error } MessageBox.Show("Card answered: " + response.AsString(" ")); } card.Transmit(new CAPDU("00 A4 00 00 02 3F 00"), new SCardChannel.TransmitDoneCallback(OnTransmitDone));
SEE ALSO
SCardChannel.Connect SCardChannel.Transmit SCardChannel.Command SCardChannel.Response
NAME
SCardReader.CardAtr
SYNOPSIS
CardBuffer CardAtr
OUTPUT
If a smartcard is present in the reader (SCardReader.CardPresent == true), returns the ATR of the card. Returns null overwise.
SEE ALSO
SCardReader.CardPresent SCardReader.Status
NAME
SCardReader.CardAvailable
SYNOPSIS
bool CardAvailable
OUTPUT
Returns true if a card is available in the reader. Returns false if there's no smartcard in the reader, or if it is already used by another process/thread.
SEE ALSO
SCardReader.CardAtr SCardReader.CardPresent SCardReader.Status
NAME
SCardReader.CardPresent
SYNOPSIS
bool CardPresent
OUTPUT
Returns true if a card is present in the reader. Returns false if there's no smartcard in the reader.
SEE ALSO
SCardReader.CardAtr SCardReader.CardAvailable SCardReader.Status
NAME
uint SCardReader.LastError
OUTPUT
Returns the last error encountered by the object when working with SCARD functions.
SEE ALSO
SCardReader.LastErrorAsString
NAME
string SCardReader.LastErrorAsString
OUTPUT
Returns the last error encountered by the object when working with SCARD functions.
SEE ALSO
SCardReader.LastError
NAME
SCardReader.Name
SYNOPSIS
string Name
OUTPUT
Return the name of the reader specified when instanciating the object.
NAME
SCardReader.StartMonitor()
SYNOPSIS
SCardReader.StartMonitor(SCardReader.StatusChangeCallback callback);
DESCRIPTION
Create a background thread to monitor the reader associated to the object. Everytime the status of the reader is changed, the callback is invoked.
SEE ALSO
SCardReader.StatusChangeCallback SCardReader.StopMonitor()
NAME
SCardReader.Status
SYNOPSIS
uint Status
OUTPUT
Returns the current status of the reader.
SEE ALSO
SCardReader.CardPresent SCardReader.StatusAsString
NAME
SCardReader.StatusAsString
SYNOPSIS
string StatusAsString
OUTPUT
Returns the current status of the reader, using SCARD.ReaderStatusToString as formatter.
SEE ALSO
SCardReader.Status
NAME
SCardReader.StatusChangeCallback
SYNOPSIS
delegate void StatusChangeCallback(uint ReaderState, CardBuffer CardAtr);
DESCRIPTION
Typedef for the callback that will be called by the background thread launched by SCardReader.StartMonitor(), everytime the status of the reader is changed.
NOTES
The callback is invoked in the context of a background thread. This implies that it is not allowed to access the GUI's components directly.
NAME
SCardReader.StopMonitor()
DESCRIPTION
Stop the background thread previously launched by SCardReader.StartMonitor().
NAME
uint SCardReaderList.LastError
OUTPUT
Returns the last error encountered by the object when working with SCARD functions.
SEE ALSO
SCardReaderList.LastErrorAsString
NAME
string SCardReaderList.LastErrorAsString
OUTPUT
Returns the last error encountered by the object when working with SCARD functions.
SEE ALSO
SCardReaderList.LastError
NAME
SCardReaderList.Readers
DESCRIPTION
Provides the list of the monitored PC/SC readers
SYNOPSIS
string[] SCardReaderList.Readers
NAME
SCardReaderList.StartMonitor()
SYNOPSIS
SCardReaderList.StartMonitor(SCardReaderList.StatusChangeCallback callback);
DESCRIPTION
Create a background thread to monitor the reader associated to the object. Everytime the status of the reader is changed, the callback is invoked.
SEE ALSO
SCardReaderList.StatusChangeCallback SCardReaderList.StopMonitor()
NAME
SCardReaderList.StatusChangeCallback
SYNOPSIS
delegate void StatusChangeCallback(string ReaderName, uint ReaderState, CardBuffer CardAtr);
DESCRIPTION
Typedef for the callback that will be called by the background thread launched by SCardReaderList.StartMonitor(), everytime the status of one of the readers is changed.
NOTES
The callback is invoked in the context of a background thread. This implies that it is not allowed to access the GUI's components directly.
NAME
SCardReaderList.StopMonitor()
DESCRIPTION
Stop the background thread previously launched by SCardReaderList.StartMonitor().
NAME
CAPDU
DESCRIPTION
The CAPDU object is used to format and send COMMAND APDUs (according to ISO 7816-4) to the smartcard
DERIVED FROM
CardBuffer
NAME
CardBuffer
DESCRIPTION
The CardBuffer provides convenient access to byte-arrays
DERIVED BY
CAPDU RAPDU
NAME
RAPDU
DESCRIPTION
The RAPDU object is used to receive and decode RESPONSE APDUs (according to ISO 7816-4) from the smartcard
DERIVED FROM
CardBuffer
NAME
SCARD
DESCRIPTION
Static class that gives access to PC/SC functions (SCard... provided by winscard.dll)
NAME
SCardChannel
DESCRIPTION
The SCardChannel object provides the actual connection to the smartcard through the PC/SC reader
SYNOPSIS
SCardChannel( string reader_name ); SCardChannel( SCardReader reader );
NAME
SCardReader
DESCRIPTION
The SCardReader object is used to monitor a PC/SC reader (i.e. wait for card events)
SYNOPSIS
SCardReader( string reader_name );
NAME
SCardReaderList
DESCRIPTION
The SCardReaderList object is used to monitor a set of PC/SC readers (i.e. wait for card events)
SYNOPSIS
SCardReaderList( string[] reader_names );