pcsc-lite  1.8.8
Functions
API

Handles smart card reader communications and forwarding requests over message queues. More...

Functions

PCSC_API char * pcsc_stringify_error (const LONG pcscError)
 Returns a human readable text for the given PC/SC error code. More...
 
LONG SCardEstablishContext (DWORD dwScope, LPCVOID pvReserved1, LPCVOID pvReserved2, LPSCARDCONTEXT phContext)
 Creates an Application Context to the PC/SC Resource Manager. More...
 
LONG SCardReleaseContext (SCARDCONTEXT hContext)
 Destroys a communication context to the PC/SC Resource Manager. More...
 
LONG SCardConnect (SCARDCONTEXT hContext, LPCSTR szReader, DWORD dwShareMode, DWORD dwPreferredProtocols, LPSCARDHANDLE phCard, LPDWORD pdwActiveProtocol)
 Establishes a connection to the reader specified in * szReader. More...
 
LONG SCardReconnect (SCARDHANDLE hCard, DWORD dwShareMode, DWORD dwPreferredProtocols, DWORD dwInitialization, LPDWORD pdwActiveProtocol)
 Reestablishes a connection to a reader that was previously connected to using SCardConnect(). More...
 
LONG SCardDisconnect (SCARDHANDLE hCard, DWORD dwDisposition)
 Terminates a connection made through SCardConnect(). More...
 
LONG SCardBeginTransaction (SCARDHANDLE hCard)
 Establishes a temporary exclusive access mode for doing a serie of commands in a transaction. More...
 
LONG SCardEndTransaction (SCARDHANDLE hCard, DWORD dwDisposition)
 Ends a previously begun transaction. More...
 
LONG SCardStatus (SCARDHANDLE hCard, LPSTR mszReaderName, LPDWORD pcchReaderLen, LPDWORD pdwState, LPDWORD pdwProtocol, LPBYTE pbAtr, LPDWORD pcbAtrLen)
 Returns the current status of the reader connected to by hCard. More...
 
LONG SCardGetStatusChange (SCARDCONTEXT hContext, DWORD dwTimeout, SCARD_READERSTATE *rgReaderStates, DWORD cReaders)
 Blocks execution until the current availability of the cards in a specific set of readers changes. More...
 
LONG SCardControl (SCARDHANDLE hCard, DWORD dwControlCode, LPCVOID pbSendBuffer, DWORD cbSendLength, LPVOID pbRecvBuffer, DWORD cbRecvLength, LPDWORD lpBytesReturned)
 Sends a command directly to the IFD Handler (reader driver) to be processed by the reader. More...
 
LONG SCardGetAttrib (SCARDHANDLE hCard, DWORD dwAttrId, LPBYTE pbAttr, LPDWORD pcbAttrLen)
 Get an attribute from the IFD Handler (reader driver). More...
 
LONG SCardSetAttrib (SCARDHANDLE hCard, DWORD dwAttrId, LPCBYTE pbAttr, DWORD cbAttrLen)
 Set an attribute of the IFD Handler. More...
 
LONG SCardTransmit (SCARDHANDLE hCard, const SCARD_IO_REQUEST *pioSendPci, LPCBYTE pbSendBuffer, DWORD cbSendLength, SCARD_IO_REQUEST *pioRecvPci, LPBYTE pbRecvBuffer, LPDWORD pcbRecvLength)
 Sends an APDU to the smart card contained in the reader connected to by SCardConnect(). More...
 
LONG SCardListReaders (SCARDCONTEXT hContext, LPCSTR mszGroups, LPSTR mszReaders, LPDWORD pcchReaders)
 Returns a list of currently available readers on the system. More...
 
LONG SCardFreeMemory (SCARDCONTEXT hContext, LPCVOID pvMem)
 Releases memory that has been returned from the resource manager using the SCARD_AUTOALLOCATE length designator. More...
 
LONG SCardListReaderGroups (SCARDCONTEXT hContext, LPSTR mszGroups, LPDWORD pcchGroups)
 Returns a list of currently available reader groups on the system. More...
 
LONG SCardCancel (SCARDCONTEXT hContext)
 Cancels all pending blocking requests on the SCardGetStatusChange() function. More...
 
LONG SCardIsValidContext (SCARDCONTEXT hContext)
 Check if a SCARDCONTEXT is valid. More...
 

Detailed Description

Handles smart card reader communications and forwarding requests over message queues.

Here is exposed the API for client applications.

Attention
Known differences with Microsoft Windows WinSCard implementation:
  1. SCardStatus()
    SCardStatus() returns a bit field on pcsc-lite but a enumeration on Windows.
    This difference may be resolved in a future version of pcsc-lite. The bit-fields would then only contain one bit set.
    You can have a portable code using:
    * if (dwState & SCARD_PRESENT)
    * {
    * // card is present
    * }
    *
  2. SCARD_E_UNSUPPORTED_FEATURE
    Windows may return ERROR_NOT_SUPPORTED instead of SCARD_E_UNSUPPORTED_FEATURE
    This difference will not be corrected. pcsc-lite only uses SCARD_E_* error codes.
  3. SCARD_E_UNSUPPORTED_FEATURE
    For historical reasons the value of SCARD_E_UNSUPPORTED_FEATURE is 0x8010001F in pcsc-lite but 0x80100022 in Windows WinSCard. You should not have any problem if you always use the symbolic name.
    The value 0x8010001F is also used for SCARD_E_UNEXPECTED on pcsc-lite but SCARD_E_UNEXPECTED is never returned by pcsc-lite. So 0x8010001F does always mean SCARD_E_UNSUPPORTED_FEATURE.
    Applications like rdesktop that allow a Windows application to talk to pcsc-lite should take care of this difference and convert the value between the two worlds.
  4. SCardConnect()
    If SCARD_SHARE_DIRECT is used the reader is accessed in shared mode (like with SCARD_SHARE_SHARED) and not in exclusive mode (like with SCARD_SHARE_EXCLUSIVE) as on Windows.
  5. SCardConnect() & SCardReconnect()
    pdwActiveProtocol is not set to SCARD_PROTOCOL_UNDEFINED if SCARD_SHARE_DIRECT is used but the card has already negotiated its protocol.

Function Documentation

PCSC_API char* pcsc_stringify_error ( const LONG  pcscError)
LONG SCardBeginTransaction ( SCARDHANDLE  hCard)

Establishes a temporary exclusive access mode for doing a serie of commands in a transaction.

You might want to use this when you are selecting a few files and then writing a large file so you can make sure that another application will not change the current file. If another application has a lock on this reader or this application is in SCARD_SHARE_EXCLUSIVE there will be no action taken.

Parameters
[in]hCardConnection made from SCardConnect().
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLEInvalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_READER_UNAVAILABLEThe reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_E_SHARING_VIOLATIONSomeone else has exclusive rights (SCARD_E_SHARING_VIOLATION)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
* rv = SCardBeginTransaction(hCard);
* ...
* / * Do some transmit commands * /
*

Definition at line 1143 of file winscard_clnt.c.

References MessageReceive(), MessageSendWithHeader(), PCSCLITE_LOCK_POLL_RATE, SCARD_BEGIN_TRANSACTION, SCARD_E_INVALID_HANDLE, SCARD_E_SHARING_VIOLATION, SCARD_S_SUCCESS, and SYS_USleep().

LONG SCardCancel ( SCARDCONTEXT  hContext)

Cancels all pending blocking requests on the SCardGetStatusChange() function.

Parameters
[in]hContextConnection context to the PC/SC Resource Manager.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLEInvalid hContext handle (SCARD_E_INVALID_HANDLE)
SCARD_E_NO_SERVICEServer is not running (SCARD_E_NO_SERVICE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
* SCARDCONTEXT hContext;
* DWORD cReaders;
* SCARD_READERSTATE rgReaderStates;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rgReaderStates.szReader = strdup("Reader X");
* rgReaderStates.dwCurrentState = SCARD_STATE_EMPTY;
* ...
* / * Spawn off thread for following function * /
* ...
* rv = SCardGetStatusChange(hContext, 0, rgReaderStates, cReaders);
* rv = SCardCancel(hContext);
*

Definition at line 3167 of file winscard_clnt.c.

References ClientCloseSession(), ClientSetupSession(), MessageReceive(), MessageSendWithHeader(), SCARD_CANCEL, SCARD_E_INVALID_HANDLE, SCARD_E_NO_SERVICE, SCARD_S_SUCCESS, and SCardGetContext().

LONG SCardConnect ( SCARDCONTEXT  hContext,
LPCSTR  szReader,
DWORD  dwShareMode,
DWORD  dwPreferredProtocols,
LPSCARDHANDLE  phCard,
LPDWORD  pdwActiveProtocol 
)

Establishes a connection to the reader specified in * szReader.

Parameters
[in]hContextConnection context to the PC/SC Resource Manager.
[in]szReaderReader name to connect to.
[in]dwShareModeMode of connection type: exclusive or shared.
  • SCARD_SHARE_SHARED - This application will allow others to share the reader.
  • SCARD_SHARE_EXCLUSIVE - This application will NOT allow others to share the reader.
  • SCARD_SHARE_DIRECT - Direct control of the reader, even without a card. SCARD_SHARE_DIRECT can be used before using SCardControl() to send control commands to the reader even if a card is not present in the reader. Contrary to Windows winscard behavior, the reader is accessed in shared mode and not exclusive mode.
[in]dwPreferredProtocolsDesired protocol use.
[out]phCardHandle to this connection.
[out]pdwActiveProtocolEstablished protocol to this connection.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLEInvalid hContext handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETERphCard or pdwActiveProtocol is NULL (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUEInvalid sharing mode, requested protocol, or reader name (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NO_SMARTCARDNo smart card present (SCARD_E_NO_SMARTCARD)
SCARD_E_NOT_READYCould not allocate the desired port (SCARD_E_NOT_READY)
SCARD_E_PROTO_MISMATCHRequested protocol is unknown (SCARD_E_PROTO_MISMATCH)
SCARD_E_READER_UNAVAILABLECould not power up the reader or card (SCARD_E_READER_UNAVAILABLE)
SCARD_E_SHARING_VIOLATIONSomeone else has exclusive rights (SCARD_E_SHARING_VIOLATION)
SCARD_E_UNKNOWN_READERszReader is NULL (SCARD_E_UNKNOWN_READER)
SCARD_E_UNSUPPORTED_FEATUREProtocol not supported (SCARD_E_UNSUPPORTED_FEATURE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_F_INTERNAL_ERRORAn internal consistency check failed (SCARD_F_INTERNAL_ERROR)
SCARD_W_UNPOWERED_CARDCard is not powered (SCARD_W_UNPOWERED_CARD)
SCARD_W_UNRESPONSIVE_CARDCard is mute (SCARD_W_UNRESPONSIVE_CARD)
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
*

Definition at line 768 of file winscard_clnt.c.

References ATRDecodeAtr(), pubReaderStatesList::cardAtr, pubReaderStatesList::cardAtrLength, pubReaderStatesList::cardProtocol, ReaderContext::contexts, ReaderContext::hLockId, IFD_POWER_UP, IFD_SUCCESS, IFDPowerICC(), MessageReceive(), MessageSendWithHeader(), ReaderContext::mMutex, PCSCLITE_LOCK_POLL_RATE, PCSCLITE_SHARING_EXCLUSIVE_CONTEXT, PCSCLITE_SHARING_NO_CONTEXT, PHSetProtocol(), POWER_STATE_INUSE, POWER_STATE_UNPOWERED, ReaderContext::powerState, ReaderContext::powerState_lock, pubReaderStatesList::readerSharing, pubReaderStatesList::readerState, ReaderContext::readerState, SCARD_CONNECT, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_INVALID_VALUE, SCARD_E_NO_SMARTCARD, SCARD_E_PROTO_MISMATCH, SCARD_E_SHARING_VIOLATION, SCARD_E_UNKNOWN_READER, SCARD_F_INTERNAL_ERROR, SCARD_NEGOTIABLE, SCARD_POWERED, SCARD_PRESENT, SCARD_PROTOCOL_ANY_OLD, SCARD_PROTOCOL_RAW, SCARD_PROTOCOL_T0, SCARD_PROTOCOL_T1, SCARD_PROTOCOL_UNDEFINED, SCARD_S_SUCCESS, SCARD_SHARE_DIRECT, SCARD_SHARE_EXCLUSIVE, SCARD_SHARE_SHARED, SCARD_W_UNPOWERED_CARD, SCARD_W_UNRESPONSIVE_CARD, SCardGetContext(), and SYS_USleep().

LONG SCardControl ( SCARDHANDLE  hCard,
DWORD  dwControlCode,
LPCVOID  pbSendBuffer,
DWORD  cbSendLength,
LPVOID  pbRecvBuffer,
DWORD  cbRecvLength,
LPDWORD  lpBytesReturned 
)

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.

Parameters
[in]hCardConnection made from SCardConnect().
[in]dwControlCodeControl code for the operation.
Click here for a list of supported commands by some drivers.
[in]pbSendBufferCommand to send to the reader.
[in]cbSendLengthLength of the command.
[out]pbRecvBufferResponse from the reader.
[in]cbRecvLengthLength of the response buffer.
[out]lpBytesReturnedLength of the response.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFERcbSendLength or cbRecvLength are too big (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLEInvalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETERpbSendBuffer is NULL or cbSendLength is null and the IFDHandler is version 2.0 (without dwControlCode) (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUEInvalid value was presented (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NOT_TRANSACTEDData exchange not successful (SCARD_E_NOT_TRANSACTED)
SCARD_E_READER_UNAVAILABLEThe reader has been removed(SCARD_E_READER_UNAVAILABLE)
SCARD_E_UNSUPPORTED_FEATUREDriver does not support (SCARD_E_UNSUPPORTED_FEATURE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_W_REMOVED_CARDThe card has been removed from the reader(SCARD_W_REMOVED_CARD)
SCARD_W_RESET_CARDThe card has been reset by another application (SCARD_W_RESET_CARD)
* LONG rv;
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol, dwSendLength, dwRecvLength;
* BYTE pbRecvBuffer[10];
* BYTE pbSendBuffer[] = { 0x06, 0x00, 0x0A, 0x01, 0x01, 0x10 0x00 };
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_RAW, &hCard, &dwActiveProtocol);
* dwSendLength = sizeof(pbSendBuffer);
* dwRecvLength = sizeof(pbRecvBuffer);
* rv = SCardControl(hCard, 0x42000001, pbSendBuffer, dwSendLength,
* pbRecvBuffer, sizeof(pbRecvBuffer), &dwRecvLength);
*

Definition at line 2255 of file winscard_clnt.c.

References IFDControl(), MAX_BUFFER_SIZE_EXTENDED, MessageReceive(), MessageSend(), MessageSendWithHeader(), SCARD_CONTROL, SCARD_E_INSUFFICIENT_BUFFER, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_UNSUPPORTED_FEATURE, SCARD_S_SUCCESS, and ReaderContext::version.

LONG SCardDisconnect ( SCARDHANDLE  hCard,
DWORD  dwDisposition 
)

Terminates a connection made through SCardConnect().

Parameters
[in]hCardConnection made from SCardConnect().
[in]dwDispositionReader function to execute.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful(SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLEInvalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_VALUEInvalid dwDisposition (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NO_SMARTCARDNo smart card present (SCARD_E_NO_SMARTCARD)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
*

Definition at line 1040 of file winscard_clnt.c.

References pubReaderStatesList::cardAtr, pubReaderStatesList::cardAtrLength, pubReaderStatesList::cardProtocol, ReaderContext::contexts, ReaderContext::hLockId, IFD_POWER_DOWN, IFD_POWER_UP, IFD_RESET, IFD_SUCCESS, IFDGetCapabilities(), IFDPowerICC(), MAX_BUFFER_SIZE, MessageReceive(), MessageSendWithHeader(), PCSCLITE_LOCK_POLL_RATE, PCSCLITE_SHARING_EXCLUSIVE_CONTEXT, PCSCLITE_SHARING_NO_CONTEXT, POWER_STATE_GRACE_PERIOD, POWER_STATE_UNPOWERED, ReaderContext::powerState, ReaderContext::powerState_lock, pubReaderStatesList::readerSharing, pubReaderStatesList::readerState, ReaderContext::readerState, SCARD_ABSENT, SCARD_DISCONNECT, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_VALUE, SCARD_E_SHARING_VIOLATION, SCARD_EJECT_CARD, SCARD_LEAVE_CARD, SCARD_NEGOTIABLE, SCARD_POWERED, SCARD_PRESENT, SCARD_PROTOCOL_UNDEFINED, SCARD_RESET, SCARD_RESET_CARD, SCARD_S_SUCCESS, SCARD_SWALLOWED, SCARD_UNPOWER_CARD, SCARD_W_REMOVED_CARD, ReaderContext::slot, SYS_USleep(), and TAG_IFD_STOP_POLLING_THREAD.

LONG SCardEndTransaction ( SCARDHANDLE  hCard,
DWORD  dwDisposition 
)

Ends a previously begun transaction.

The calling application must be the owner of the previously begun transaction or an error will occur.

Parameters
[in]hCardConnection made from SCardConnect().
[in]dwDispositionAction to be taken on the reader. The disposition action is not currently used in this release.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLEInvalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_VALUEInvalid value for dwDisposition (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_READER_UNAVAILABLEThe reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_E_SHARING_VIOLATIONSomeone else has exclusive rights (SCARD_E_SHARING_VIOLATION)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
* rv = SCardBeginTransaction(hCard);
* ...
* / * Do some transmit commands * /
* ...
*

Definition at line 1254 of file winscard_clnt.c.

References pubReaderStatesList::cardAtr, pubReaderStatesList::cardAtrLength, pubReaderStatesList::cardProtocol, _psContextMap::dwClientID, IFD_POWER_DOWN, IFD_POWER_UP, IFD_RESET, IFDPowerICC(), MAX_BUFFER_SIZE, MessageReceive(), MessageSendWithHeader(), _psContextMap::mMutex, pubReaderStatesList::readerState, ReaderContext::readerState, SCARD_ABSENT, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_VALUE, SCARD_EJECT_CARD, SCARD_END_TRANSACTION, SCARD_LEAVE_CARD, SCARD_NEGOTIABLE, SCARD_POWERED, SCARD_PRESENT, SCARD_PROTOCOL_UNDEFINED, SCARD_RESET, SCARD_RESET_CARD, SCARD_S_SUCCESS, SCARD_SWALLOWED, SCARD_UNPOWER_CARD, SCARD_W_REMOVED_CARD, ReaderContext::slot, and SYS_USleep().

LONG SCardEstablishContext ( DWORD  dwScope,
LPCVOID  pvReserved1,
LPCVOID  pvReserved2,
LPSCARDCONTEXT  phContext 
)

Creates an Application Context to the PC/SC Resource Manager.

This must be the first WinSCard function called in a PC/SC application. Each thread of an application shall use its own SCARDCONTEXT.

Parameters
[in]dwScopeScope of the establishment. This can either be a local or remote connection.
[in]pvReserved1Reserved for future use.
[in]pvReserved2Reserved for future use.
[out]phContextReturned Application Context.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INVALID_PARAMETERphContext is null (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUEInvalid scope type passed (SCARD_E_INVALID_VALUE )
SCARD_E_NO_MEMORYThere is no free slot to store hContext (SCARD_E_NO_MEMORY)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_F_INTERNAL_ERRORAn internal consistency check failed (SCARD_F_INTERNAL_ERROR)
* SCARDCONTEXT hContext;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
*

Definition at line 424 of file winscard_clnt.c.

References SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_VALUE, SCARD_S_SUCCESS, SCARD_SCOPE_GLOBAL, SCARD_SCOPE_SYSTEM, SCARD_SCOPE_TERMINAL, SCARD_SCOPE_USER, SCardCheckDaemonAvailability(), SCardEstablishContextTH(), SCardLockThread(), and SCardUnlockThread().

LONG SCardFreeMemory ( SCARDCONTEXT  hContext,
LPCVOID  pvMem 
)

Releases memory that has been returned from the resource manager using the SCARD_AUTOALLOCATE length designator.

Parameters
[in]hContextConnection context to the PC/SC Resource Manager.
[in]pvMempointer to allocated memory
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLEInvalid hContext handle (SCARD_E_INVALID_HANDLE)

Definition at line 2997 of file winscard_clnt.c.

References SCARD_E_INVALID_HANDLE, SCARD_S_SUCCESS, and SCardGetContext().

LONG SCardGetAttrib ( SCARDHANDLE  hCard,
DWORD  dwAttrId,
LPBYTE  pbAttr,
LPDWORD  pcbAttrLen 
)

Get an attribute from the IFD Handler (reader driver).

The list of possible attributes is available in the file reader.h.

If *pcbAttrLen is equal to SCARD_AUTOALLOCATE then the function will allocate itself the needed memory. Use SCardFreeMemory() to release it.

Parameters
[in]hCardConnection made from SCardConnect().
[in]dwAttrIdIdentifier for the attribute to get.
Not all the dwAttrId values listed above may be implemented in the IFD Handler you are using. And some dwAttrId values not listed here may be implemented.
[out]pbAttrPointer to a buffer that receives the attribute.
[in,out]pcbAttrLenLength of the pbAttr buffer in bytes.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFERcbAttrLen is too big (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INSUFFICIENT_BUFFERReader buffer not large enough (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLEInvalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETERA parameter is NULL and should not (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_MEMORYMemory allocation failed (SCARD_E_NO_MEMORY)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NOT_TRANSACTEDData exchange not successful (SCARD_E_NOT_TRANSACTED)
SCARD_E_READER_UNAVAILABLEThe reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
* LONG rv;
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol;
* unsigned char pbAtr[MAX_ATR_SIZE];
* DWORD dwAtrLen;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_RAW, &hCard, &dwActiveProtocol);
* dwAtrLen = sizeof(pbAtr);
* rv = SCardGetAttrib(hCard, SCARD_ATTR_ATR_STRING, pbAtr, &dwAtrLen);
*
* LONG rv;
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol;
* unsigned char *pbAttr;
* DWORD dwAttrLen;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_RAW, &hCard, &dwActiveProtocol);
* dwAttrLen = SCARD_AUTOALLOCATE;
* rv = SCardGetAttrib(hCard, SCARD_ATTR_ATR_STRING, (unsigned char *)&pbAttr, &dwAttrLen);
*

Definition at line 2456 of file winscard_clnt.c.

References IFD_ERROR_INSUFFICIENT_BUFFER, IFD_ERROR_TAG, IFD_SUCCESS, IFDGetCapabilities(), MAX_BUFFER_SIZE, pubReaderStatesList::readerName, ReaderContext::readerState, SCARD_ATTR_DEVICE_FRIENDLY_NAME, SCARD_AUTOALLOCATE, SCARD_E_INSUFFICIENT_BUFFER, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_NO_MEMORY, SCARD_E_NOT_TRANSACTED, SCARD_E_UNSUPPORTED_FEATURE, SCARD_GET_ATTRIB, and SCARD_S_SUCCESS.

LONG SCardGetStatusChange ( SCARDCONTEXT  hContext,
DWORD  dwTimeout,
SCARD_READERSTATE rgReaderStates,
DWORD  cReaders 
)

Blocks execution until the current availability of the cards in a specific set of readers changes.

This function receives a structure or list of structures containing reader names. It then blocks waiting for a change in state to occur for a maximum blocking time of dwTimeout or forever if INFINITE is used.

The new event state will be contained in dwEventState. A status change might be a card insertion or removal event, a change in ATR, etc.

dwEventState also contains a number of events in the upper 16 bits (dwEventState & 0xFFFF0000). This number of events is incremented for each card insertion or removal in the specified reader. This can be used to detect a card removal/insertion between two calls to SCardGetStatusChange()

To wait for a reader event (reader added or removed) you may use the special reader name "\\?PnP?\Notification". If a reader event occurs the state of this reader will change and the bit SCARD_STATE_CHANGED will be set.

* typedef struct {
* LPCSTR szReader; // Reader name
* LPVOID pvUserData; // User defined data
* DWORD dwCurrentState; // Current state of reader
* DWORD dwEventState; // Reader state after a state change
* DWORD cbAtr; // ATR Length, usually MAX_ATR_SIZE
* BYTE rgbAtr[MAX_ATR_SIZE]; // ATR Value
*

Value of dwCurrentState and dwEventState:

  • SCARD_STATE_UNAWARE The application is unaware of the current state, and would like to know. The use of this value results in an immediate return from state transition monitoring services. This is represented by all bits set to zero.
  • SCARD_STATE_IGNORE This reader should be ignored
  • SCARD_STATE_CHANGED There is a difference between the state believed by the application, and the state known by the resource manager. When this bit is set, the application may assume a significant state change has occurred on this reader.
  • SCARD_STATE_UNKNOWN The given reader name is not recognized by the resource manager. If this bit is set, then SCARD_STATE_CHANGED and SCARD_STATE_IGNORE will also be set
  • SCARD_STATE_UNAVAILABLE The actual state of this reader is not available. If this bit is set, then all the following bits are clear.
  • SCARD_STATE_EMPTY There is no card in the reader. If this bit is set, all the following bits will be clear
  • SCARD_STATE_PRESENT There is a card in the reader
  • SCARD_STATE_EXCLUSIVE The card in the reader is allocated for exclusive use by another application. If this bit is set, SCARD_STATE_PRESENT will also be set.
  • SCARD_STATE_INUSE The card in the reader is in use by one or more other applications, but may be connected to in shared mode. If this bit is set, SCARD_STATE_PRESENT will also be set.
  • SCARD_STATE_MUTE There is an unresponsive card in the reader.
Parameters
[in]hContextConnection context to the PC/SC Resource Manager.
[in]dwTimeoutMaximum waiting time (in milliseconds) for status change, zero (or INFINITE) for infinite.
[in,out]rgReaderStatesStructures of readers with current states.
[in]cReadersNumber of structures.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_NO_SERVICEServer is not running (SCARD_E_NO_SERVICE)
SCARD_E_INVALID_PARAMETERrgReaderStates is NULL and cReaders > 0 (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUEInvalid States, reader name, etc (SCARD_E_INVALID_VALUE)
SCARD_E_INVALID_HANDLEInvalid hContext handle (SCARD_E_INVALID_HANDLE)
SCARD_E_READER_UNAVAILABLEThe reader is unavailable (SCARD_E_READER_UNAVAILABLE)
SCARD_E_TIMEOUTThe user-specified timeout value has expired (SCARD_E_TIMEOUT)
* SCARDCONTEXT hContext;
* SCARD_READERSTATE rgReaderStates[2];
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* ...
* rgReaderStates[0].szReader = "Reader X";
* rgReaderStates[0].dwCurrentState = SCARD_STATE_UNAWARE;
*
* rgReaderStates[1].szReader = "\\\\?PnP?\\Notification";
* rgReaderStates[1].dwCurrentState = SCARD_STATE_UNAWARE;
* ...
* rv = SCardGetStatusChange(hContext, INFINITE, rgReaderStates, 2);
* printf("reader state: 0x%04X\n", rgReaderStates[0].dwEventState);
* printf("reader state: 0x%04X\n", rgReaderStates[1].dwEventState);
*

Definition at line 1697 of file winscard_clnt.c.

References _psContextMap::cancellable, pubReaderStatesList::cardAtr, pubReaderStatesList::cardAtrLength, CMD_STOP_WAITING_READER_STATE_CHANGE, CMD_WAIT_READER_STATE_CHANGE, _psContextMap::dwClientID, pubReaderStatesList::eventCounter, INFINITE, MessageReceive(), MessageReceiveTimeout(), MessageSendWithHeader(), _psContextMap::mMutex, PCSCLITE_MAX_READERS_CONTEXTS, PCSCLITE_SHARING_EXCLUSIVE_CONTEXT, PCSCLITE_SHARING_LAST_CONTEXT, PCSCLITE_SHARING_NO_CONTEXT, PCSCLITE_STATUS_POLL_RATE, pubReaderStatesList::readerSharing, pubReaderStatesList::readerState, SCARD_ABSENT, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_INVALID_VALUE, SCARD_E_TIMEOUT, SCARD_E_UNKNOWN_READER, SCARD_PRESENT, SCARD_S_SUCCESS, SCARD_STATE_ATRMATCH, SCARD_STATE_CHANGED, SCARD_STATE_EMPTY, SCARD_STATE_EXCLUSIVE, SCARD_STATE_IGNORE, SCARD_STATE_INUSE, SCARD_STATE_MUTE, SCARD_STATE_PRESENT, SCARD_STATE_UNAVAILABLE, SCARD_STATE_UNAWARE, SCARD_STATE_UNKNOWN, SCARD_SWALLOWED, SCARD_UNKNOWN, SCardGetContext(), SYS_USleep(), time_sub(), and wait_reader_state_change::timeOut.

LONG SCardIsValidContext ( SCARDCONTEXT  hContext)

Check if a SCARDCONTEXT is valid.

Call this function to determine whether a smart card context handle is still valid. After a smart card context handle has been returned by SCardEstablishContext(), it may become invalid if the resource manager service has been shut down.

Parameters
[in]hContextConnection context to the PC/SC Resource Manager.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLEInvalid Handle (SCARD_E_INVALID_HANDLE)
* SCARDCONTEXT hContext;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardIsValidContext(hContext);
*

Definition at line 3251 of file winscard_clnt.c.

References SCARD_E_INVALID_HANDLE, SCARD_S_SUCCESS, and SCardGetContext().

LONG SCardListReaderGroups ( SCARDCONTEXT  hContext,
LPSTR  mszGroups,
LPDWORD  pcchGroups 
)

Returns a list of currently available reader groups on the system.

mszGroups is a pointer to a character string that is allocated by the application. If the application sends mszGroups as NULL then this function will return the size of the buffer needed to allocate in pcchGroups.

The group names is a multi-string and separated by a null character ('\0') and ended by a double null character like "SCard$DefaultReaders\0Group 2\0\0".

If *pcchGroups is equal to SCARD_AUTOALLOCATE then the function will allocate itself the needed memory. Use SCardFreeMemory() to release it.

Parameters
[in]hContextConnection context to the PC/SC Resource Manager.
[out]mszGroupsList of groups to list readers.
[in,out]pcchGroupsSize of multi-string buffer including NULL's.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFERReader buffer not large enough (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLEInvalid Scope Handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETERmszGroups is NULL (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_MEMORYMemory allocation failed (SCARD_E_NO_MEMORY)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
* SCARDCONTEXT hContext;
* LPSTR mszGroups;
* DWORD dwGroups;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardListReaderGroups(hContext, NULL, &dwGroups);
* mszGroups = malloc(sizeof(char)*dwGroups);
* rv = SCardListReaderGroups(hContext, mszGroups, &dwGroups);
*
* SCARDCONTEXT hContext;
* LPSTR mszGroups;
* DWORD dwGroups;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* dwGroups = SCARD_AUTOALLOCATE;
* rv = SCardListReaderGroups(hContext, (LPSTR)&mszGroups, &dwGroups);
* rv = SCardFreeMemory(hContext, mszGroups);
*

Definition at line 3069 of file winscard_clnt.c.

References _psContextMap::mMutex, SCARD_AUTOALLOCATE, SCARD_E_INSUFFICIENT_BUFFER, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_NO_MEMORY, SCARD_S_SUCCESS, and SCardGetContext().

LONG SCardListReaders ( SCARDCONTEXT  hContext,
LPCSTR  mszGroups,
LPSTR  mszReaders,
LPDWORD  pcchReaders 
)

Returns a list of currently available readers on the system.

mszReaders is a pointer to a character string that is allocated by the application. If the application sends mszGroups and mszReaders as NULL then this function will return the size of the buffer needed to allocate in pcchReaders.

If *pcchReaders is equal to SCARD_AUTOALLOCATE then the function will allocate itself the needed memory. Use SCardFreeMemory() to release it.

Parameters
[in]hContextConnection context to the PC/SC Resource Manager.
[in]mszGroupsList of groups to list readers (not used).
[out]mszReadersMulti-string with list of readers.
[in,out]pcchReadersSize of multi-string buffer including NULL's.
Returns
Connection status.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFERReader buffer not large enough (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLEInvalid Scope Handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETERpcchReaders is NULL (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_MEMORYMemory allocation failed (SCARD_E_NO_MEMORY)
SCARD_E_NO_READERS_AVAILABLENo readers available (SCARD_E_NO_READERS_AVAILABLE)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
* SCARDCONTEXT hContext;
* LPSTR mszReaders;
* DWORD dwReaders;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardListReaders(hContext, NULL, NULL, &dwReaders);
* mszReaders = malloc(sizeof(char)*dwReaders);
* rv = SCardListReaders(hContext, NULL, mszReaders, &dwReaders);
*
* SCARDCONTEXT hContext;
* LPSTR mszReaders;
* DWORD dwReaders;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* dwReaders = SCARD_AUTOALLOCATE
* rv = SCardListReaders(hContext, NULL, (LPSTR)&mszReaders, &dwReaders);
* rv = SCardFreeMemory(hContext, mszReaders);
*

Definition at line 2871 of file winscard_clnt.c.

References _psContextMap::mMutex, PCSCLITE_MAX_READERS_CONTEXTS, SCARD_AUTOALLOCATE, SCARD_E_INSUFFICIENT_BUFFER, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_NO_MEMORY, SCARD_E_NO_READERS_AVAILABLE, SCARD_S_SUCCESS, and SCardGetContext().

LONG SCardReconnect ( SCARDHANDLE  hCard,
DWORD  dwShareMode,
DWORD  dwPreferredProtocols,
DWORD  dwInitialization,
LPDWORD  pdwActiveProtocol 
)

Reestablishes a connection to a reader that was previously connected to using SCardConnect().

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 SCardReconnect() must be called in order to acknowledge that the card was reset and allow it to change it's state accordingly.

Parameters
[in]hCardHandle to a previous call to connect.
[in]dwShareModeMode of connection type: exclusive/shared.
[in]dwPreferredProtocolsDesired protocol use.
  • SCARD_PROTOCOL_T0 - Use the T=0 protocol.
  • SCARD_PROTOCOL_T1 - Use the T=1 protocol.
  • SCARD_PROTOCOL_RAW - Use with memory type cards. dwPreferredProtocols is a bit mask of acceptable protocols for the connection. You can use (SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1) if you do not have a preferred protocol.
[in]dwInitializationDesired action taken on the card/reader.
[out]pdwActiveProtocolEstablished protocol to this connection.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLEInvalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETERphContext is null. (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUEInvalid sharing mode, requested protocol, or reader name (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NO_SMARTCARDNo smart card present (SCARD_E_NO_SMARTCARD)
SCARD_E_NOT_READYCould not allocate the desired port (SCARD_E_NOT_READY)
SCARD_E_PROTO_MISMATCHRequested protocol is unknown (SCARD_E_PROTO_MISMATCH)
SCARD_E_READER_UNAVAILABLEThe reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_E_SHARING_VIOLATIONSomeone else has exclusive rights (SCARD_E_SHARING_VIOLATION)
SCARD_E_UNSUPPORTED_FEATUREProtocol not supported (SCARD_E_UNSUPPORTED_FEATURE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_F_INTERNAL_ERRORAn internal consistency check failed (SCARD_F_INTERNAL_ERROR)
SCARD_W_REMOVED_CARDThe smart card has been removed (SCARD_W_REMOVED_CARD)
SCARD_W_UNRESPONSIVE_CARDCard is mute (SCARD_W_UNRESPONSIVE_CARD)
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol, dwSendLength, dwRecvLength;
* LONG rv;
* BYTE pbRecvBuffer[10];
* BYTE pbSendBuffer[] = {0xC0, 0xA4, 0x00, 0x00, 0x02, 0x3F, 0x00};
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
* ...
* dwSendLength = sizeof(pbSendBuffer);
* dwRecvLength = sizeof(pbRecvBuffer);
* rv = SCardTransmit(hCard, SCARD_PCI_T0, pbSendBuffer, dwSendLength,
* &pioRecvPci, pbRecvBuffer, &dwRecvLength);
* / * Card has been reset by another application * /
* if (rv == SCARD_W_RESET_CARD)
* {
* SCARD_RESET_CARD, &dwActiveProtocol);
* }
*

Definition at line 932 of file winscard_clnt.c.

References ATRDecodeAtr(), pubReaderStatesList::cardAtr, pubReaderStatesList::cardAtrLength, pubReaderStatesList::cardProtocol, ReaderContext::contexts, IFD_POWER_DOWN, IFD_POWER_UP, IFD_RESET, IFDPowerICC(), MessageReceive(), MessageSendWithHeader(), ReaderContext::mMutex, PCSCLITE_LOCK_POLL_RATE, PCSCLITE_SHARING_EXCLUSIVE_CONTEXT, PCSCLITE_SHARING_LAST_CONTEXT, PHSetProtocol(), pubReaderStatesList::readerSharing, pubReaderStatesList::readerState, ReaderContext::readerState, SCARD_ABSENT, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_INVALID_VALUE, SCARD_E_NO_SMARTCARD, SCARD_E_PROTO_MISMATCH, SCARD_E_SHARING_VIOLATION, SCARD_LEAVE_CARD, SCARD_NEGOTIABLE, SCARD_POWERED, SCARD_PRESENT, SCARD_PROTOCOL_ANY_OLD, SCARD_PROTOCOL_RAW, SCARD_PROTOCOL_T0, SCARD_PROTOCOL_T1, SCARD_PROTOCOL_UNDEFINED, SCARD_RECONNECT, SCARD_RESET, SCARD_RESET_CARD, SCARD_S_SUCCESS, SCARD_SHARE_DIRECT, SCARD_SHARE_EXCLUSIVE, SCARD_SHARE_SHARED, SCARD_SWALLOWED, SCARD_UNPOWER_CARD, SCARD_W_REMOVED_CARD, SCARD_W_UNRESPONSIVE_CARD, and SYS_USleep().

LONG SCardReleaseContext ( SCARDCONTEXT  hContext)

Destroys a communication context to the PC/SC Resource Manager.

This must be the last function called in a PC/SC application.

Parameters
[in]hContextConnection context to be closed.
Returns
Connection status.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_INVALID_HANDLEInvalid hContext handle (SCARD_E_INVALID_HANDLE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
* SCARDCONTEXT hContext;
* LONG rv;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardReleaseContext(hContext);
*

Definition at line 642 of file winscard_clnt.c.

References MessageReceive(), MessageSendWithHeader(), SCARD_E_INVALID_HANDLE, SCARD_RELEASE_CONTEXT, SCARD_S_SUCCESS, SCardGetContext(), SCardLockThread(), SCardRemoveContext(), and SCardUnlockThread().

LONG SCardSetAttrib ( SCARDHANDLE  hCard,
DWORD  dwAttrId,
LPCBYTE  pbAttr,
DWORD  cbAttrLen 
)

Set an attribute of the IFD Handler.

The list of attributes you can set is dependent on the IFD Handler you are using.

Parameters
[in]hCardConnection made from SCardConnect().
[in]dwAttrIdIdentifier for the attribute to set.
[in]pbAttrPointer to a buffer that receives the attribute.
[in]cbAttrLenLength of the pbAttr buffer in bytes.
Returns
Error code
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFERcbAttrLen is too big (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLEInvalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETERA parameter is NULL and should not (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NOT_TRANSACTEDData exchange not successful (SCARD_E_NOT_TRANSACTED)
SCARD_E_READER_UNAVAILABLEThe reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
* LONG rv;
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol;
* unsigned char pbAttr[] = { 0x12, 0x34, 0x56 };
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_RAW, &hCard, &dwActiveProtocol);
* rv = SCardSetAttrib(hCard, 0x42000001, pbAttr, sizeof(pbAttr));
*

Definition at line 2539 of file winscard_clnt.c.

References IFD_ERROR_TAG, IFD_SUCCESS, IFDSetCapabilities(), SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_NOT_TRANSACTED, SCARD_E_UNSUPPORTED_FEATURE, SCARD_S_SUCCESS, and SCARD_SET_ATTRIB.

LONG SCardStatus ( SCARDHANDLE  hCard,
LPSTR  mszReaderName,
LPDWORD  pcchReaderLen,
LPDWORD  pdwState,
LPDWORD  pdwProtocol,
LPBYTE  pbAtr,
LPDWORD  pcbAtrLen 
)

Returns the current status of the reader connected to by hCard.

It's friendly name will be stored in szReaderName. pcchReaderLen will be the size of the allocated buffer for szReaderName, while pcbAtrLen will be the size of the allocated buffer for pbAtr. If either of these is too small, the function will return with SCARD_E_INSUFFICIENT_BUFFER and the necessary size in pcchReaderLen and pcbAtrLen. The current state, and protocol will be stored in pdwState and pdwProtocol respectively.

*pdwState also contains a number of events in the upper 16 bits (*pdwState & 0xFFFF0000). This number of events is incremented for each card insertion or removal in the specified reader. This can be used to detect a card removal/insertion between two calls to SCardStatus().

If *pcchReaderLen is equal to SCARD_AUTOALLOCATE then the function will allocate itself the needed memory for mszReaderName. Use SCardFreeMemory() to release it.

If *pcbAtrLen is equal to SCARD_AUTOALLOCATE then the function will allocate itself the needed memory for pbAtr. Use SCardFreeMemory() to release it.

Parameters
[in]hCardConnection made from SCardConnect().
[in,out]mszReaderNameFriendly name of this reader.
[in,out]pcchReaderLenSize of the szReaderName multistring.
[out]pdwStateCurrent state of this reader. pdwState is a DWORD possibly OR'd with the following values:
  • SCARD_ABSENT - There is no card in the reader.
  • SCARD_PRESENT - There is a card in the reader, but it has not been moved into position for use.
  • SCARD_SWALLOWED - There is a card in the reader in position for use. The card is not powered.
  • SCARD_POWERED - Power is being provided to the card, but the reader driver is unaware of the mode of the card.
  • SCARD_NEGOTIABLE - The card has been reset and is awaiting PTS negotiation.
  • SCARD_SPECIFIC - The card has been reset and specific communication protocols have been established.
[out]pdwProtocolCurrent protocol of this reader.
[out]pbAtrCurrent ATR of a card in this reader.
[out]pcbAtrLenLength of ATR.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFERNot enough allocated memory for szReaderName or for pbAtr (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLEInvalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETERpcchReaderLen or pcbAtrLen is NULL (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_MEMORYMemory allocation failed (SCARD_E_NO_MEMORY)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_READER_UNAVAILABLEThe reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_F_INTERNAL_ERRORAn internal consistency check failed (SCARD_F_INTERNAL_ERROR)
SCARD_W_REMOVED_CARDThe smart card has been removed (SCARD_W_REMOVED_CARD)
SCARD_W_RESET_CARDThe smart card has been reset (SCARD_W_RESET_CARD)
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol;
* DWORD dwState, dwProtocol, dwAtrLen, dwReaderLen;
* BYTE pbAtr[MAX_ATR_SIZE];
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
* ...
* dwAtrLen = sizeof(pbAtr);
* rv = SCardStatus(hCard, NULL, &dwReaderLen, &dwState, &dwProtocol, pbAtr, &dwAtrLen);
*
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol;
* DWORD dwState, dwProtocol, dwAtrLen, dwReaderLen;
* BYTE *pbAtr = NULL;
* char *pcReader = NULL;
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
* ...
* dwReaderLen = SCARD_AUTOALLOCATE;
* dwAtrLen = SCARD_AUTOALLOCATE;
* rv = SCardStatus(hCard, (LPSTR)&pcReader, &dwReaderLen, &dwState,
* &dwProtocol, (LPBYTE)&pbAtr, &dwAtrLen);
*

Definition at line 1413 of file winscard_clnt.c.

References pubReaderStatesList::cardAtrLength, pubReaderStatesList::cardProtocol, pubReaderStatesList::eventCounter, MAX_ATR_SIZE, MessageReceive(), MessageSendWithHeader(), PCSCLITE_LOCK_POLL_RATE, PCSCLITE_MAX_READERS_CONTEXTS, ReaderContext::readerState, SCARD_AUTOALLOCATE, SCARD_E_INSUFFICIENT_BUFFER, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_NO_MEMORY, SCARD_E_READER_UNAVAILABLE, SCARD_E_SHARING_VIOLATION, SCARD_F_INTERNAL_ERROR, SCARD_S_SUCCESS, SCARD_STATUS, and SYS_USleep().

LONG SCardTransmit ( SCARDHANDLE  hCard,
const SCARD_IO_REQUEST pioSendPci,
LPCBYTE  pbSendBuffer,
DWORD  cbSendLength,
SCARD_IO_REQUEST pioRecvPci,
LPBYTE  pbRecvBuffer,
LPDWORD  pcbRecvLength 
)

Sends an APDU to the smart card contained in the reader connected to by SCardConnect().

The card responds from the APDU and stores this response in pbRecvBuffer and it's length in pcbRecvLength. pioSendPci and pioRecvPci are structures containing the following:

* typedef struct {
* DWORD dwProtocol; // SCARD_PROTOCOL_T0 or SCARD_PROTOCOL_T1
* DWORD cbPciLength; // Length of this structure
*
Parameters
[in]hCardConnection made from SCardConnect().
[in,out]pioSendPciStructure of Protocol Control Information.
[in]pbSendBufferAPDU to send to the card.
[in]cbSendLengthLength of the APDU.
[in,out]pioRecvPciStructure of protocol information.
[out]pbRecvBufferResponse from the card.
[in,out]pcbRecvLengthLength of the response.
Returns
Error code.
Return values
SCARD_S_SUCCESSSuccessful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFERcbSendLength or cbRecvLength are too big (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLEInvalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETERpbSendBuffer or pbRecvBuffer or pcbRecvLength or pioSendPci is null (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUEInvalid Protocol, reader name, etc (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICEThe server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NOT_TRANSACTEDAPDU exchange not successful (SCARD_E_NOT_TRANSACTED)
SCARD_E_PROTO_MISMATCHConnect protocol is different than desired (SCARD_E_PROTO_MISMATCH)
SCARD_E_READER_UNAVAILABLEThe reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_F_COMM_ERRORAn internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_W_RESET_CARDThe card has been reset by another application (SCARD_W_RESET_CARD)
SCARD_W_REMOVED_CARDThe card has been removed from the reader (SCARD_W_REMOVED_CARD)
* LONG rv;
* SCARDCONTEXT hContext;
* SCARDHANDLE hCard;
* DWORD dwActiveProtocol, dwSendLength, dwRecvLength;
* SCARD_IO_REQUEST pioRecvPci;
* BYTE pbRecvBuffer[10];
* BYTE pbSendBuffer[] = { 0xC0, 0xA4, 0x00, 0x00, 0x02, 0x3F, 0x00 };
* ...
* rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
* rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
* SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
* dwSendLength = sizeof(pbSendBuffer);
* dwRecvLength = sizeof(pbRecvBuffer);
* rv = SCardTransmit(hCard, SCARD_PCI_T0, pbSendBuffer, dwSendLength,
* &pioRecvPci, pbRecvBuffer, &dwRecvLength);
*

Definition at line 2697 of file winscard_clnt.c.

References pubReaderStatesList::cardProtocol, SCARD_IO_REQUEST::cbPciLength, _psContextMap::dwClientID, SCARD_IO_REQUEST::dwProtocol, IFDTransmit(), MAX_BUFFER_SIZE_EXTENDED, MessageReceive(), MessageSend(), MessageSendWithHeader(), _psContextMap::mMutex, PCSCLITE_LOCK_POLL_RATE, pubReaderStatesList::readerState, ReaderContext::readerState, SCARD_ABSENT, SCARD_E_INSUFFICIENT_BUFFER, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_NO_SMARTCARD, SCARD_E_PROTO_MISMATCH, SCARD_E_SHARING_VIOLATION, SCARD_PROTOCOL_ANY, SCARD_PROTOCOL_ANY_OLD, SCARD_PROTOCOL_RAW, SCARD_PROTOCOL_T1, SCARD_S_SUCCESS, SCARD_TRANSMIT, SYS_USleep(), and ReaderContext::version.