API

This handles smartcard reader communications and forwarding requests over message queues. More...


Functions
PCSC_API char *	pcsc_stringify_error (const long pcscError)
	This function return 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)
	This function destroys a communication context to the PC/SC Resource Manager.
LONG	SCardSetTimeout (SCARDCONTEXT hContext, DWORD dwTimeout)
LONG	SCardConnect (SCARDCONTEXT hContext, LPCSTR szReader, DWORD dwShareMode, DWORD dwPreferredProtocols, LPSCARDHANDLE phCard, LPDWORD pdwActiveProtocol)
	This function establishes a connection to the friendly name of the reader specified in `szReader`.
LONG	SCardReconnect (SCARDHANDLE hCard, DWORD dwShareMode, DWORD dwPreferredProtocols, DWORD dwInitialization, LPDWORD pdwActiveProtocol)
	This function reestablishes a connection to a reader that was previously connected to using SCardConnect().
LONG	SCardDisconnect (SCARDHANDLE hCard, DWORD dwDisposition)
	This function terminates a connection to the connection made through SCardConnect().
LONG	SCardBeginTransaction (SCARDHANDLE hCard)
	This function establishes a temporary exclusive access mode for doing a series of commands or transaction.
LONG	SCardEndTransaction (SCARDHANDLE hCard, DWORD dwDisposition)
	This function ends a previously begun transaction.
LONG	SCardCancelTransaction (SCARDHANDLE hCard)
LONG	SCardStatus (SCARDHANDLE hCard, LPSTR mszReaderNames, LPDWORD pcchReaderLen, LPDWORD pdwState, LPDWORD pdwProtocol, LPBYTE pbAtr, LPDWORD pcbAtrLen)
	This function returns the current status of the reader connected to by `hCard`.
LONG	SCardGetStatusChange (SCARDCONTEXT hContext, DWORD dwTimeout, LPSCARD_READERSTATE_A rgReaderStates, DWORD cReaders)
	This function receives a structure or list of structures containing reader names.
LONG	SCardControl (SCARDHANDLE hCard, DWORD dwControlCode, LPCVOID pbSendBuffer, DWORD cbSendLength, LPVOID pbRecvBuffer, DWORD cbRecvLength, LPDWORD lpBytesReturned)
	This function sends a command directly to the IFD Handler to be processed by the reader.
LONG	SCardGetAttrib (SCARDHANDLE hCard, DWORD dwAttrId, LPBYTE pbAttr, LPDWORD pcbAttrLen)
	This function get an attribute from the IFD Handler.
LONG	SCardSetAttrib (SCARDHANDLE hCard, DWORD dwAttrId, LPCBYTE pbAttr, DWORD cbAttrLen)
	This function set an attribute of the IFD Handler.
LONG	SCardTransmit (SCARDHANDLE hCard, LPCSCARD_IO_REQUEST pioSendPci, LPCBYTE pbSendBuffer, DWORD cbSendLength, LPSCARD_IO_REQUEST pioRecvPci, LPBYTE pbRecvBuffer, LPDWORD pcbRecvLength)
	This function 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)
	This function returns a list of currently available readers on the system.
LONG	SCardListReaderGroups (SCARDCONTEXT hContext, LPSTR mszGroups, LPDWORD pcchGroups)
	This function returns a list of currently available reader groups on the system.
LONG	SCardCancel (SCARDCONTEXT hContext)
	This function cancels all pending blocking requests on the SCardGetStatusChange() function.
LONG	SCardIsValidContext (SCARDCONTEXT hContext)
	check if a SCARDCONTEXT is valid.

Detailed Description

This handles smartcard reader communications and forwarding requests over message queues.

Here is exposed the API for client applications.

Function Documentation

PCSC_API char* pcsc_stringify_error ( const long pcscError )

This function return a human readable text for the given PC/SC error code.

Parameters:

[in] pcscError Error code to be translated to text.

Returns:: Text representing de error code passed.

Test:

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

Definition at line 46 of file error.c.

References SCARD_E_CANCELLED, SCARD_E_CANT_DISPOSE, SCARD_E_CARD_UNSUPPORTED, SCARD_E_DUPLICATE_READER, SCARD_E_INSUFFICIENT_BUFFER, SCARD_E_INVALID_ATR, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_INVALID_TARGET, SCARD_E_INVALID_VALUE, SCARD_E_NO_MEMORY, SCARD_E_NO_READERS_AVAILABLE, SCARD_E_NO_SERVICE, SCARD_E_NO_SMARTCARD, SCARD_E_NOT_READY, SCARD_E_NOT_TRANSACTED, SCARD_E_PCI_TOO_SMALL, SCARD_E_PROTO_MISMATCH, SCARD_E_READER_UNAVAILABLE, SCARD_E_READER_UNSUPPORTED, SCARD_E_SERVICE_STOPPED, SCARD_E_SHARING_VIOLATION, SCARD_E_SYSTEM_CANCELLED, SCARD_E_TIMEOUT, SCARD_E_UNKNOWN_CARD, SCARD_E_UNKNOWN_READER, SCARD_E_UNSUPPORTED_FEATURE, SCARD_F_COMM_ERROR, SCARD_F_INTERNAL_ERROR, SCARD_F_UNKNOWN_ERROR, SCARD_F_WAITED_TOO_LONG, SCARD_S_SUCCESS, SCARD_W_INSERTED_CARD, SCARD_W_REMOVED_CARD, SCARD_W_RESET_CARD, SCARD_W_UNPOWERED_CARD, SCARD_W_UNRESPONSIVE_CARD, and SCARD_W_UNSUPPORTED_CARD.

LONG SCardBeginTransaction ( SCARDHANDLE hCard )

This function establishes a temporary exclusive access mode for doing a series of commands or 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] 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 runing (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)

Test:

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

References rxSharedSegment::data, begin_struct::hCard, PCSCLITE_CLIENT_ATTEMPTS, PCSCLITE_MAX_READERS_CONTEXTS, _psContextMap::psChannelMap, _psChannelMap::readerName, begin_struct::rv, SCARD_BEGIN_TRANSACTION, SCARD_E_INVALID_HANDLE, SCARD_E_NO_SERVICE, SCARD_E_READER_UNAVAILABLE, SCARD_E_SHARING_VIOLATION, SCARD_F_COMM_ERROR, SCARD_S_SUCCESS, SCardCheckDaemonAvailability(), SHMClientRead(), and WrapSHMWrite().

Here is the call graph for this function:

LONG SCardCancel ( SCARDCONTEXT hContext )

This function cancels all pending blocking requests on the SCardGetStatusChange() function.

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)

Test:

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

References BLOCK_STATUS_RESUME, _psContextMap::contextBlockStatus, SCARD_E_INVALID_HANDLE, SCARD_S_SUCCESS, and SCardGetContextIndice().

Here is the call graph for this function:

LONG SCardCancelTransaction ( SCARDHANDLE hCard )

Deprecated:: This function is not in Microsoft(R) WinSCard API and is deprecated in pcsc-lite API.

Definition at line 1353 of file winscard_clnt.c.

References rxSharedSegment::data, cancel_struct::hCard, PCSCLITE_CLIENT_ATTEMPTS, PCSCLITE_MAX_READERS_CONTEXTS, _psContextMap::psChannelMap, _psChannelMap::readerName, SCARD_E_INVALID_HANDLE, SCARD_E_NO_SERVICE, SCARD_E_READER_UNAVAILABLE, SCARD_F_COMM_ERROR, SCARD_S_SUCCESS, SCardCheckDaemonAvailability(), SHMClientRead(), and WrapSHMWrite().

Here is the call graph for this function:

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

This function establishes a connection to the friendly name of the reader specified in szReader.

The first connection will power up and perform a reset on the card.

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.
`[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.
`[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 runing (SCARD_E_NO_SERVICE)
	SCARD_E_NOT_READY	Could not allocate the desired port (SCARD_E_NOT_READY)
	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_INTERNAL_ERROR	An internal consistency check failed (SCARD_F_INTERNAL_ERROR)

Test:

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

References rxSharedSegment::data, connect_struct::dwPreferredProtocols, connect_struct::dwShareMode, connect_struct::hContext, PCSCLITE_CLIENT_ATTEMPTS, connect_struct::pdwActiveProtocol, connect_struct::phCard, connect_struct::rv, SCARD_CONNECT, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_INVALID_VALUE, SCARD_E_NO_SERVICE, SCARD_E_UNKNOWN_READER, SCARD_F_COMM_ERROR, SCARD_PROTOCOL_ANY_OLD, SCARD_PROTOCOL_RAW, SCARD_PROTOCOL_T0, SCARD_PROTOCOL_T1, SCARD_S_SUCCESS, SCardCheckDaemonAvailability(), SCardGetContextIndice(), SHMClientRead(), connect_struct::szReader, and WrapSHMWrite().

Here is the call graph for this function:

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

This function sends a command directly to the IFD Handler 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.

Note:: the API of this function changed. In pcsc-lite 1.2.0 and before the API was not Windows(R) PC/SC compatible. This has been corrected.

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_INVALID_HANDLE	Invalid `hCard` handle (SCARD_E_INVALID_HANDLE)
	SCARD_E_INVALID_VALUE	Invalid value was presented (SCARD_E_INVALID_VALUE)
	SCARD_E_INSUFFICIENT_BUFFER	`cbSendLength` or `cbRecvLength` are too big (SCARD_E_INSUFFICIENT_BUFFER)
	SCARD_E_NO_SERVICE	The server is not runing (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)
	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)

Test:

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

References control_struct::cbRecvLength, control_struct::cbSendLength, rxSharedSegment::data, control_struct::dwBytesReturned, _psContextMap::dwClientID, control_struct::dwControlCode, control_struct::hCard, MAX_BUFFER_SIZE, MAX_BUFFER_SIZE_EXTENDED, control_struct::pbRecvBuffer, control_struct::pbSendBuffer, PCSCLITE_CLIENT_ATTEMPTS, PCSCLITE_MAX_MESSAGE_SIZE, PCSCLITE_MAX_READERS_CONTEXTS, _psContextMap::psChannelMap, _psChannelMap::readerName, control_struct::rv, SCARD_CONTROL, SCARD_CONTROL_EXTENDED, SCARD_E_INSUFFICIENT_BUFFER, SCARD_E_INVALID_HANDLE, SCARD_E_NO_SERVICE, SCARD_E_READER_UNAVAILABLE, SCARD_F_COMM_ERROR, SCARD_S_SUCCESS, SCardCheckDaemonAvailability(), SHMClientRead(), SHMMessageReceive(), and WrapSHMWrite().

Here is the call graph for this function:

LONG SCardDisconnect	(	SCARDHANDLE	hCard,
		DWORD	dwDisposition
	)

This function terminates a connection to the connection made through SCardConnect().

dwDisposition can have the following values:

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 - Unpower 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 runing (SCARD_E_NO_SERVICE)
	SCARD_F_COMM_ERROR	An internal communications error has been detected (SCARD_F_COMM_ERROR)

Test:

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

References rxSharedSegment::data, disconnect_struct::dwDisposition, disconnect_struct::hCard, PCSCLITE_CLIENT_ATTEMPTS, disconnect_struct::rv, SCARD_DISCONNECT, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_VALUE, SCARD_E_NO_SERVICE, SCARD_EJECT_CARD, SCARD_F_COMM_ERROR, SCARD_LEAVE_CARD, SCARD_RESET_CARD, SCARD_S_SUCCESS, SCARD_UNPOWER_CARD, SCardCheckDaemonAvailability(), SHMClientRead(), and WrapSHMWrite().

Here is the call graph for this function:

LONG SCardEndTransaction	(	SCARDHANDLE	hCard,
		DWORD	dwDisposition
	)

This function 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. The disposition action is not currently used in this release. SCARD_LEAVE_CARD - Do nothing. SCARD_RESET_CARD - Reset the card. SCARD_UNPOWER_CARD - Unpower 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` (SCARD_E_INVALID_VALUE)
	SCARD_E_NO_SERVICE	The server is not runing (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)

Test:

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

References rxSharedSegment::data, end_struct::dwDisposition, end_struct::hCard, PCSCLITE_CLIENT_ATTEMPTS, PCSCLITE_MAX_READERS_CONTEXTS, _psContextMap::psChannelMap, _psChannelMap::readerName, end_struct::rv, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_VALUE, SCARD_E_NO_SERVICE, SCARD_E_READER_UNAVAILABLE, SCARD_EJECT_CARD, SCARD_END_TRANSACTION, SCARD_F_COMM_ERROR, SCARD_LEAVE_CARD, SCARD_RESET_CARD, SCARD_S_SUCCESS, SCARD_UNPOWER_CARD, SCardCheckDaemonAvailability(), SHMClientRead(), SYS_USleep(), and WrapSHMWrite().

Here is the call graph for this function:

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

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

Creates an Application Context for a client.

This must be the first function called in a PC/SC application. This is a thread-safe wrapper to the function SCardEstablishContextTH().

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. Can be used for remote connection.
`[in]`	pvReserved2	Reserved for future use.
`[out]`	phContext	Returned Application Context.

Returns:: Connection status.

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 runing (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)

Test:

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

Definition at line 302 of file winscard_clnt.c.

References SCARD_E_INVALID_HANDLE, SCARD_S_SUCCESS, SCardCheckDaemonAvailability(), SCardEstablishContextTH(), SCardLockThread(), and SCardUnlockThread().

Here is the call graph for this function:

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

This function get an attribute from the IFD Handler.

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

Parameters:

`[in]`	hCard	Connection made from SCardConnect().
`[in]`	dwAttrId	Identifier for the attribute to get. 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 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

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.

Parameters:

`[out]`	pbAttr	Pointer to a buffer that receives the attribute.
	pcbAttrLen	[inout] Length of the `pbAttr` buffer in bytes.

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 `hCard` handle (SCARD_E_INVALID_HANDLE)
	SCARD_E_NO_SERVICE	The server is not runing (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)

Test:

 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);
 rv = SCardGetAttrib(hCard, SCARD_ATTR_ATR_STRING, pbAtr, &dwAtrLen);

Definition at line 2550 of file winscard_clnt.c.

References MAX_BUFFER_SIZE, SCARD_E_INVALID_PARAMETER, and SCARD_GET_ATTRIB.

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

This function receives a structure or list of structures containing reader names.

It then blocks for a change in state to occur on any of the OR'd values contained in dwCurrentState 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.

This function will block for reader availability if cReaders is equal to zero and rgReaderStates is NULL.

 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;
 ...
 typedef SCARD_READERSTATE *PSCARD_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_ATRMATCH There is a card in the reader with an ATR matching one of the target cards. If this bit is set, SCARD_STATE_PRESENT will also be set. This bit is only returned on the SCardLocateCards() function.
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 miliseconds) for status change, zero (or INFINITE) for infinite.
	rgReaderStates	[inout] 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_TIMEOUT	The user-specified timeout value has expired (SCARD_E_TIMEOUT)

Test:

 SCARDCONTEXT hContext;
 SCARD_READERSTATE_A rgReaderStates[1];
 LONG rv;
 ...
 rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
 ...
 rgReaderStates[0].szReader = "Reader X";
 rgReaderStates[0].dwCurrentState = SCARD_STATE_UNAWARE;
 ...
 rv = SCardGetStatusChange(hContext, INFINITE, rgReaderStates, 1);
 printf("reader state: 0x%04X\n", rgReaderStates[0].dwEventState);

Definition at line 1719 of file winscard_clnt.c.

References BLOCK_STATUS_BLOCKING, BLOCK_STATUS_RESUME, pubReaderStatesList::cardAtr, pubReaderStatesList::cardAtrLength, _psContextMap::contextBlockStatus, INFINITE, PCSCLITE_MAX_READERS_CONTEXTS, PCSCLITE_STATUS_POLL_RATE, PCSCLITE_STATUS_WAIT, pubReaderStatesList::readerSharing, pubReaderStatesList::readerState, SCARD_ABSENT, SCARD_E_CANCELLED, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_INVALID_VALUE, SCARD_E_READER_UNAVAILABLE, SCARD_E_TIMEOUT, 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, SCardCheckDaemonAvailability(), SCardGetContextIndice(), and SYS_USleep().

Here is the call graph for this function:

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 set by SCardEstablishContext(), it may become not valid 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)

Test:

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

Definition at line 3269 of file winscard_clnt.c.

References SCARD_E_INVALID_HANDLE, SCARD_S_SUCCESS, SCardCheckDaemonAvailability(), and SCardGetContextIndice().

Here is the call graph for this function:

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

This function 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 nul character ('\0') and ended by a double nul character. "SCard$DefaultReaders\\0Group 2\\0\\0".

Parameters:

`[in]`	hContext	Connection context to the PC/SC Resource Manager.
`[out]`	mszGroups	List of groups to list readers.
	pcchGroups	[inout] Size of multi-string buffer including NUL'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_NO_SERVICE	The server is not runing (SCARD_E_NO_SERVICE)

Test:

 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);

Definition at line 3151 of file winscard_clnt.c.

References SCARD_E_INSUFFICIENT_BUFFER, SCARD_E_INVALID_HANDLE, SCARD_S_SUCCESS, SCardCheckDaemonAvailability(), and SCardGetContextIndice().

Here is the call graph for this function:

API

Functions

Detailed Description

Function Documentation