API

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

Functions
PCSC_API const char *	pcsc_stringify_error (const LONG pcscError)
	Returns a human readable text for the given PC/SC error code.
LONG	SCardEstablishContext (DWORD dwScope, LPCVOID pvReserved1, LPCVOID pvReserved2, LPSCARDCONTEXT phContext)
	Creates an Application Context to the PC/SC Resource Manager.
LONG	SCardReleaseContext (SCARDCONTEXT hContext)
	Destroys a communication context to the PC/SC Resource Manager.
LONG	SCardConnect (SCARDCONTEXT hContext, LPCSTR szReader, DWORD dwShareMode, DWORD dwPreferredProtocols, LPSCARDHANDLE phCard, LPDWORD pdwActiveProtocol)
	Establishes a connection to the reader specified in * szReader.
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().
LONG	SCardDisconnect (SCARDHANDLE hCard, DWORD dwDisposition)
	Terminates a connection made through SCardConnect().
LONG	SCardBeginTransaction (SCARDHANDLE hCard)
	Establishes a temporary exclusive access mode for doing a series of commands in a transaction.
LONG	SCardEndTransaction (SCARDHANDLE hCard, DWORD dwDisposition)
	Ends a previously begun transaction.
LONG	SCardStatus (SCARDHANDLE hCard, LPSTR szReaderName, LPDWORD pcchReaderLen, LPDWORD pdwState, LPDWORD pdwProtocol, LPBYTE pbAtr, LPDWORD pcbAtrLen)
	Returns the current status of the reader connected to by hCard.
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.
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.
LONG	SCardGetAttrib (SCARDHANDLE hCard, DWORD dwAttrId, LPBYTE pbAttr, LPDWORD pcbAttrLen)
	Get an attribute from the IFD Handler (reader driver).
LONG	SCardSetAttrib (SCARDHANDLE hCard, DWORD dwAttrId, LPCBYTE pbAttr, DWORD cbAttrLen)
	Set an attribute of the IFD Handler.
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().
LONG	SCardListReaders (SCARDCONTEXT hContext, LPCSTR mszGroups, LPSTR mszReaders, LPDWORD pcchReaders)
	Returns a list of currently available readers on the system.
LONG	SCardFreeMemory (SCARDCONTEXT hContext, LPCVOID pvMem)
	Releases memory that has been returned from the resource manager using the SCARD_AUTOALLOCATE length designator.
LONG	SCardListReaderGroups (SCARDCONTEXT hContext, LPSTR mszGroups, LPDWORD pcchGroups)
	Returns a list of currently available reader groups on the system.
LONG	SCardCancel (SCARDCONTEXT hContext)
	Cancels a specific blocking SCardGetStatusChange() function.
LONG	SCardIsValidContext (SCARDCONTEXT hContext)
	Check if a SCARDCONTEXT is valid.

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.

6. SCardReconnect()

   Any PC/SC transaction held by the process is still valid after SCardReconnect() returned. On Windows the PC/SC transactions are released and a new call to SCardBeginTransaction() must be done.

Function Documentation

pcsc_stringify_error()

PCSC_API const char * pcsc_stringify_error

(

const LONG

pcscError

)

Returns a human readable text for the given PC/SC error code.

Warning

The returned string uses a Thread-Local Storage (TLS) buffer and is valid:

1. only while the thread on which it was obtained is alive.
2. until the next call to this function on the same thread.

Parameters

[in]

pcscError

Error code to be translated to text.

Returns

Text representing the error code passed.

SCARDCONTEXT hContext;
LONG rv;
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
if (rv != SCARD_S_SUCCESS)
    printf("SCardEstablishContext: %s (0x%lX)\n",
        pcsc_stringify_error(rv), rv);

Definition at line 82 of file error.c.

SCardBeginTransaction()

LONG SCardBeginTransaction

(

SCARDHANDLE

hCard

)

Establishes a temporary exclusive access mode for doing a series 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 the function will block until it can continue.

Parameters

[in]

hCard

Connection made from SCardConnect().

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLE	Invalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_READER_UNAVAILABLE	The reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_E_SHARING_VIOLATION	Someone else has exclusive rights (SCARD_E_SHARING_VIOLATION)
SCARD_F_COMM_ERROR	An internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_E_INVALID_VALUE	An invalid value is used for hCard (for example the reader is no more present) (SCARD_E_INVALID_VALUE)

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 1146 of file winscard_clnt.c.

SCardCancel()

LONG SCardCancel

(

SCARDCONTEXT

hContext

)

Cancels a specific blocking SCardGetStatusChange() function.

MUST be called with the same SCARDCONTEXT as SCardGetStatusChange().

Parameters

[in]

hContext

Connection context to the PC/SC Resource Manager.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLE	Invalid hContext handle (SCARD_E_INVALID_HANDLE)
SCARD_E_NO_SERVICE	Server is not running (SCARD_E_NO_SERVICE)
SCARD_F_COMM_ERROR	An 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 = "Reader X";
rgReaderStates.dwCurrentState = SCARD_STATE_EMPTY;
cReaders = 1;
...
rv = SCardGetStatusChange(hContext, INFINITE, &rgReaderStates, cReaders);
...
/ * Spawn off thread for following function * /
rv = SCardCancel(hContext);

Definition at line 3118 of file winscard_clnt.c.

SCardConnect()

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]	hContext	Connection context to the PC/SC Resource Manager.
[in]	szReader	Reader name to connect to.
[in]	dwShareMode	Mode 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]	dwPreferredProtocols	Desired protocol use. 0 - valid only if dwShareMode is SCARD_SHARE_DIRECT 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.
[out]	phCard	Handle to this connection.
[out]	pdwActiveProtocol	Established protocol to this connection.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLE	Invalid hContext handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETER	phCard or pdwActiveProtocol is NULL (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUE	Invalid sharing mode, requested protocol, or reader name (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NO_SMARTCARD	No smart card present (SCARD_E_NO_SMARTCARD)
SCARD_E_PROTO_MISMATCH	Requested protocol is unknown (SCARD_E_PROTO_MISMATCH)
SCARD_E_READER_UNAVAILABLE	Could not power up the reader or card (SCARD_E_READER_UNAVAILABLE)
SCARD_E_SHARING_VIOLATION	Someone else has exclusive rights (SCARD_E_SHARING_VIOLATION)
SCARD_E_UNKNOWN_READER	szReader is NULL (SCARD_E_UNKNOWN_READER)
SCARD_E_UNSUPPORTED_FEATURE	Protocol not supported (SCARD_E_UNSUPPORTED_FEATURE)
SCARD_F_COMM_ERROR	An internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_F_INTERNAL_ERROR	An internal consistency check failed (SCARD_F_INTERNAL_ERROR)
SCARD_W_UNPOWERED_CARD	Card is not powered (SCARD_W_UNPOWERED_CARD)
SCARD_W_UNRESPONSIVE_CARD	Card 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 802 of file winscard_clnt.c.

SCardControl()

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]	hCard	Connection made from SCardConnect().
[in]	dwControlCode	Control code for the operation. Click here for a list of supported commands by some drivers.
[in]	pbSendBuffer	Command to send to the reader.
[in]	cbSendLength	Length of the command.
[out]	pbRecvBuffer	Response from the reader.
[in]	cbRecvLength	Length of the response buffer.
[out]	lpBytesReturned	Length of the response.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFER	cbRecvLength was not large enough for the reader response. The expected size is now in lpBytesReturned (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLE	Invalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETER	pbSendBuffer is NULL or cbSendLength is null and the IFDHandler is version 2.0 (without dwControlCode) (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUE	Invalid value was presented (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NOT_TRANSACTED	Data exchange not successful (SCARD_E_NOT_TRANSACTED)
SCARD_E_READER_UNAVAILABLE	The reader has been removed(SCARD_E_READER_UNAVAILABLE)
SCARD_E_UNSUPPORTED_FEATURE	Driver does not support (SCARD_E_UNSUPPORTED_FEATURE)
SCARD_F_COMM_ERROR	An internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_W_REMOVED_CARD	The card has been removed from the reader(SCARD_W_REMOVED_CARD)
SCARD_W_RESET_CARD	The 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 2210 of file winscard_clnt.c.

SCardDisconnect()

LONG SCardDisconnect	(	SCARDHANDLE	hCard,
		DWORD	dwDisposition
	)

Terminates a connection made through SCardConnect().

Parameters

[in]	hCard	Connection made from SCardConnect().
[in]	dwDisposition	Reader function to execute. SCARD_LEAVE_CARD - Do nothing. SCARD_RESET_CARD - Reset the card (warm reset). SCARD_UNPOWER_CARD - Power down the card (cold reset). SCARD_EJECT_CARD - Eject the card.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful(SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLE	Invalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_VALUE	Invalid dwDisposition (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NO_SMARTCARD	No smart card present (SCARD_E_NO_SMARTCARD)
SCARD_F_COMM_ERROR	An 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 = SCardDisconnect(hCard, SCARD_UNPOWER_CARD);

Definition at line 1056 of file winscard_clnt.c.

SCardEndTransaction()

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]	hCard	Connection made from SCardConnect().
[in]	dwDisposition	Action to be taken on the reader. SCARD_LEAVE_CARD - Do nothing. SCARD_RESET_CARD - Reset the card. SCARD_UNPOWER_CARD - Power down the card. SCARD_EJECT_CARD - Eject the card.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLE	Invalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_VALUE	Invalid value for dwDisposition or hCard (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_READER_UNAVAILABLE	The reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_E_SHARING_VIOLATION	Someone else has exclusive rights (SCARD_E_SHARING_VIOLATION)
SCARD_F_COMM_ERROR	An 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 * /
...
rv = SCardEndTransaction(hCard, SCARD_LEAVE_CARD);

Definition at line 1247 of file winscard_clnt.c.

SCardEstablishContext()

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, unless calling SCardCancel(), which MUST be called with the same context as the context used to call SCardGetStatusChange().

Parameters

[in]	dwScope	Scope of the establishment. This can either be a local or remote connection. SCARD_SCOPE_USER - Not used. SCARD_SCOPE_TERMINAL - Not used. SCARD_SCOPE_GLOBAL - Not used. SCARD_SCOPE_SYSTEM - Services on the local machine.
[in]	pvReserved1	Reserved for future use.
[in]	pvReserved2	Reserved for future use.
[out]	phContext	Returned Application Context.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INVALID_PARAMETER	phContext is null (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUE	Invalid scope type passed (SCARD_E_INVALID_VALUE )
SCARD_E_NO_MEMORY	There is no free slot to store hContext (SCARD_E_NO_MEMORY)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_F_COMM_ERROR	An internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_F_INTERNAL_ERROR	An internal consistency check failed (SCARD_F_INTERNAL_ERROR)

SCARDCONTEXT hContext;
LONG rv;
...
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);

Definition at line 469 of file winscard_clnt.c.

SCardFreeMemory()

LONG SCardFreeMemory	(	SCARDCONTEXT	hContext,
		LPCVOID	pvMem
	)

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

Parameters

[in]	hContext	Connection context to the PC/SC Resource Manager.
[in]	pvMem	pointer to allocated memory

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLE	Invalid hContext handle (SCARD_E_INVALID_HANDLE)

Definition at line 2958 of file winscard_clnt.c.

SCardGetAttrib()

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]	hCard	Connection made from SCardConnect().
[in]	dwAttrId	Identifier 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. SCARD_ATTR_ASYNC_PROTOCOL_TYPES SCARD_ATTR_ATR_STRING SCARD_ATTR_CHANNEL_ID SCARD_ATTR_CHARACTERISTICS SCARD_ATTR_CURRENT_BWT SCARD_ATTR_CURRENT_CLK SCARD_ATTR_CURRENT_CWT SCARD_ATTR_CURRENT_D SCARD_ATTR_CURRENT_EBC_ENCODING SCARD_ATTR_CURRENT_F SCARD_ATTR_CURRENT_IFSC SCARD_ATTR_CURRENT_IFSD SCARD_ATTR_CURRENT_IO_STATE SCARD_ATTR_CURRENT_N SCARD_ATTR_CURRENT_PROTOCOL_TYPE SCARD_ATTR_CURRENT_W SCARD_ATTR_DEFAULT_CLK SCARD_ATTR_DEFAULT_DATA_RATE SCARD_ATTR_DEVICE_FRIENDLY_NAME Implemented by pcsc-lite if the IFD Handler (driver) returns IFD_ERROR_TAG. pcsc-lite then returns the same reader name as returned by SCardListReaders(). SCARD_ATTR_DEVICE_IN_USE SCARD_ATTR_DEVICE_SYSTEM_NAME SCARD_ATTR_DEVICE_UNIT SCARD_ATTR_ESC_AUTHREQUEST SCARD_ATTR_ESC_CANCEL SCARD_ATTR_ESC_RESET SCARD_ATTR_EXTENDED_BWT SCARD_ATTR_ICC_INTERFACE_STATUS SCARD_ATTR_ICC_PRESENCE SCARD_ATTR_ICC_TYPE_PER_ATR SCARD_ATTR_MAX_CLK SCARD_ATTR_MAX_DATA_RATE SCARD_ATTR_MAX_IFSD SCARD_ATTR_MAXINPUT SCARD_ATTR_POWER_MGMT_SUPPORT SCARD_ATTR_SUPRESS_T1_IFS_REQUEST SCARD_ATTR_SYNC_PROTOCOL_TYPES SCARD_ATTR_USER_AUTH_INPUT_DEVICE SCARD_ATTR_USER_TO_CARD_AUTH_DEVICE SCARD_ATTR_VENDOR_IFD_SERIAL_NO SCARD_ATTR_VENDOR_IFD_TYPE SCARD_ATTR_VENDOR_IFD_VERSION SCARD_ATTR_VENDOR_NAME
[out]	pbAttr	Pointer to a buffer that receives the attribute. If this value is NULL, SCardGetAttrib() ignores the buffer length supplied in pcbAttrLen, writes the length of the buffer that would have been returned if this parameter had not been NULL to pcbAttrLen, and returns a success code.
[in,out]	pcbAttrLen	Length of the pbAttr buffer in bytes and receives the actual length of the received attribute.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_UNSUPPORTED_FEATURE	the dwAttrId attribute is not supported by the driver (SCARD_E_UNSUPPORTED_FEATURE)
SCARD_E_NOT_TRANSACTED	the driver returned an error (SCARD_E_NOT_TRANSACTED) Data exchange not successful (SCARD_E_NOT_TRANSACTED)
SCARD_E_INSUFFICIENT_BUFFER	cbAttrLen is too big (SCARD_E_INSUFFICIENT_BUFFER) pbAttr buffer not large enough. In that case the expected buffer size is indicated in *pcbAttrLen (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLE	Invalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETER	A parameter is NULL and should not (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_MEMORY	Memory allocation failed (SCARD_E_NO_MEMORY)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_READER_UNAVAILABLE	The reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_F_COMM_ERROR	An internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_E_INVALID_VALUE	An invalid value is used for hCard (for example the reader is no more present) (SCARD_E_INVALID_VALUE)

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);
rv = SCardGetAttrib(hCard, SCARD_ATTR_ATR_STRING, NULL, &dwAttrLen);
if (SCARD_S_SUCCESS == rv)
{
    pbAttr = malloc(dwAttrLen);
    rv = SCardGetAttrib(hCard, SCARD_ATTR_ATR_STRING, pbAttr, &dwAttrLen);
    free(pbAttr);
}

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 2421 of file winscard_clnt.c.

SCardGetStatusChange()

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.

To cancel the ongoing call, use SCardCancel() with the same SCARDCONTEXT.

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
} SCARD_READERSTATE, *LPSCARD_READERSTATE;

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]	hContext	Connection context to the PC/SC Resource Manager.
[in]	dwTimeout	Maximum waiting time (in milliseconds) for status change, INFINITE for infinite.
[in,out]	rgReaderStates	Structures of readers with current states.
[in]	cReaders	Number of structures.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_NO_SERVICE	Server is not running (SCARD_E_NO_SERVICE)
SCARD_E_INVALID_PARAMETER	rgReaderStates is NULL and cReaders > 0 (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUE	Invalid States, reader name, etc (SCARD_E_INVALID_VALUE)
SCARD_E_INVALID_HANDLE	Invalid hContext handle (SCARD_E_INVALID_HANDLE)
SCARD_E_READER_UNAVAILABLE	The reader is unavailable (SCARD_E_READER_UNAVAILABLE)
SCARD_E_UNKNOWN_READER	The reader name is unknown (SCARD_E_UNKNOWN_READER)
SCARD_E_TIMEOUT	The user-specified timeout value has expired (SCARD_E_TIMEOUT)
SCARD_E_CANCELLED	The call has been cancelled by a call to SCardCancel() (SCARD_E_CANCELLED)

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;
...
// Get current state
rv = SCardGetStatusChange(hContext, INFINITE, rgReaderStates, 2);
printf("reader state: 0x%04X\n", rgReaderStates[0].dwEventState);
printf("reader state: 0x%04X\n", rgReaderStates[1].dwEventState);
 
// Wait for card insertion
if (rgReaderStates[0].dwEventState & SCARD_STATE_EMPTY)
{
    rgReaderStates[0].dwCurrentState = rgReaderStates[0].dwEventState;
    rv = SCardGetStatusChange(hContext, INFINITE, rgReaderStates, 2);
}

Definition at line 1678 of file winscard_clnt.c.

SCardIsValidContext()

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]

hContext

Connection context to the PC/SC Resource Manager.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLE	Invalid Handle (SCARD_E_INVALID_HANDLE)

SCARDCONTEXT hContext;
LONG rv;
...
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
rv = SCardIsValidContext(hContext);

Definition at line 3208 of file winscard_clnt.c.

SCardListReaderGroups()

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]	hContext	Connection context to the PC/SC Resource Manager.
[out]	mszGroups	List of groups to list readers.
[in,out]	pcchGroups	Size of multi-string buffer including NULL's.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFER	Reader buffer not large enough (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLE	Invalid Scope Handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETER	mszGroups is NULL and *pcchGroups == SCARD_AUTOALLOCATE (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_MEMORY	Memory allocation failed (SCARD_E_NO_MEMORY)
SCARD_E_NO_SERVICE	The 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 3028 of file winscard_clnt.c.

SCardListReaders()

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.

Encoding: The reader names and group names are encoded using UTF-8.

Parameters

[in]	hContext	Connection context to the PC/SC Resource Manager.
[in]	mszGroups	List of groups to list readers (not used).
[out]	mszReaders	Multi-string with list of readers.
[in,out]	pcchReaders	Size of multi-string buffer including NULL's.

Returns

Connection status.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFER	Reader buffer not large enough (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLE	Invalid Scope Handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETER	pcchReaders is NULL (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_MEMORY	Memory allocation failed (SCARD_E_NO_MEMORY)
SCARD_E_NO_READERS_AVAILABLE	No readers available (SCARD_E_NO_READERS_AVAILABLE)
SCARD_E_NO_SERVICE	The 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);
 
char *p = mszReaders;
while (*p)
{
  printf("Reader: %s\n", p);
  p += strlen(p) +1;
}

or, with auto allocation:

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 2842 of file winscard_clnt.c.

SCardReconnect()

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 its state accordingly.

Parameters

[in]	hCard	Handle to a previous call to connect.
[in]	dwShareMode	Mode of connection type: exclusive/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.
[in]	dwPreferredProtocols	Desired 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]	dwInitialization	Desired action taken on the card/reader. SCARD_LEAVE_CARD - Do nothing. SCARD_RESET_CARD - Reset the card (warm reset). SCARD_UNPOWER_CARD - Power down the card (cold reset). SCARD_EJECT_CARD - Eject the card.
[out]	pdwActiveProtocol	Established protocol to this connection.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INVALID_HANDLE	Invalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETER	phContext is null. (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUE	Invalid hCard, sharing mode, requested protocol, or reader name (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NO_SMARTCARD	No smart card present (SCARD_E_NO_SMARTCARD)
SCARD_E_PROTO_MISMATCH	Requested protocol is unknown (SCARD_E_PROTO_MISMATCH)
SCARD_E_READER_UNAVAILABLE	The reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_E_SHARING_VIOLATION	Someone else has exclusive rights (SCARD_E_SHARING_VIOLATION)
SCARD_E_UNSUPPORTED_FEATURE	Protocol not supported (SCARD_E_UNSUPPORTED_FEATURE)
SCARD_F_COMM_ERROR	An internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_F_INTERNAL_ERROR	An internal consistency check failed (SCARD_F_INTERNAL_ERROR)
SCARD_W_REMOVED_CARD	The smart card has been removed (SCARD_W_REMOVED_CARD)
SCARD_W_UNRESPONSIVE_CARD	Card 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)
{
  rv = SCardReconnect(hCard, SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0,
           SCARD_RESET_CARD, &dwActiveProtocol);
}

Definition at line 957 of file winscard_clnt.c.

SCardReleaseContext()

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]

hContext

Connection context to be closed.

Returns

Connection status.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_INVALID_HANDLE	Invalid hContext handle (SCARD_E_INVALID_HANDLE)
SCARD_F_COMM_ERROR	An 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 690 of file winscard_clnt.c.

SCardSetAttrib()

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]	hCard	Connection made from SCardConnect().
[in]	dwAttrId	Identifier for the attribute to set.
[in]	pbAttr	Pointer to a buffer that receives the attribute.
[in]	cbAttrLen	Length of the pbAttr buffer in bytes.

Returns

Error code

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFER	cbAttrLen is too big (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLE	Invalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETER	A parameter is NULL and should not (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NOT_TRANSACTED	Data exchange not successful (SCARD_E_NOT_TRANSACTED)
SCARD_E_READER_UNAVAILABLE	The reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_F_COMM_ERROR	An 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 2504 of file winscard_clnt.c.

SCardStatus()

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

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

Its 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 szReaderName. 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]	hCard	Connection made from SCardConnect().
[in,out]	szReaderName	Friendly name of this reader.
[in,out]	pcchReaderLen	Size of the szReaderName.
[out]	pdwState	Current 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]	pdwProtocol	Current protocol of this reader. SCARD_PROTOCOL_T0 Use the T=0 protocol. SCARD_PROTOCOL_T1 Use the T=1 protocol.
[out]	pbAtr	Current ATR of a card in this reader.
[out]	pcbAtrLen	Length of ATR.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFER	Not enough allocated memory for szReaderName or for pbAtr (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLE	Invalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETER	pcchReaderLen or pcbAtrLen is NULL (SCARD_E_INVALID_PARAMETER)
SCARD_E_NO_MEMORY	Memory allocation failed (SCARD_E_NO_MEMORY)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_READER_UNAVAILABLE	The reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_F_COMM_ERROR	An internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_F_INTERNAL_ERROR	An internal consistency check failed (SCARD_F_INTERNAL_ERROR)
SCARD_W_REMOVED_CARD	The smart card has been removed (SCARD_W_REMOVED_CARD)
SCARD_W_RESET_CARD	The 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 1391 of file winscard_clnt.c.

SCardTransmit()

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 its length in pcbRecvLength.

pioSendPci and pioRecvPci are structures containing the following:

typedef struct {
   DWORD dwProtocol;    // SCARD_PROTOCOL_T0, SCARD_PROTOCOL_T1 or SCARD_PROTOCOL_RAW
   DWORD cbPciLength;   // Length of this structure
} SCARD_IO_REQUEST;

Parameters

[in]	hCard	Connection made from SCardConnect().
[in]	pioSendPci	Structure of Protocol Control Information. SCARD_PCI_T0 - Predefined T=0 PCI structure. SCARD_PCI_T1 - Predefined T=1 PCI structure. SCARD_PCI_RAW - Predefined RAW PCI structure.
[in]	pbSendBuffer	APDU to send to the card.
[in]	cbSendLength	Length of the APDU.
[in,out]	pioRecvPci	Structure of protocol information. This parameter can be NULL if no PCI is returned.
[out]	pbRecvBuffer	Response from the card.
[in,out]	pcbRecvLength	Length of the response.

Returns

Error code.

Return values

SCARD_S_SUCCESS	Successful (SCARD_S_SUCCESS)
SCARD_E_INSUFFICIENT_BUFFER	cbRecvLength was not large enough for the card response. The expected size is now in cbRecvLength (SCARD_E_INSUFFICIENT_BUFFER)
SCARD_E_INVALID_HANDLE	Invalid hCard handle (SCARD_E_INVALID_HANDLE)
SCARD_E_INVALID_PARAMETER	pbSendBuffer or pbRecvBuffer or pcbRecvLength or pioSendPci is null (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUE	Invalid hCard, Protocol, reader name, etc (SCARD_E_INVALID_VALUE)
SCARD_E_NO_SERVICE	The server is not running (SCARD_E_NO_SERVICE)
SCARD_E_NOT_TRANSACTED	APDU exchange not successful (SCARD_E_NOT_TRANSACTED)
SCARD_E_PROTO_MISMATCH	Connect protocol is different than desired (SCARD_E_PROTO_MISMATCH)
SCARD_E_READER_UNAVAILABLE	The reader has been removed (SCARD_E_READER_UNAVAILABLE)
SCARD_F_COMM_ERROR	An internal communications error has been detected (SCARD_F_COMM_ERROR)
SCARD_W_RESET_CARD	The card has been reset by another application (SCARD_W_RESET_CARD)
SCARD_W_REMOVED_CARD	The card has been removed from the reader (SCARD_W_REMOVED_CARD)

LONG rv;
SCARDCONTEXT hContext;
SCARDHANDLE hCard;
DWORD dwActiveProtocol, dwSendLength, dwRecvLength;
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,
         NULL, pbRecvBuffer, &dwRecvLength);

Definition at line 2661 of file winscard_clnt.c.