ts::pcsc Namespace Reference

PC/SC smartcard API utilities. More...

Classes
struct	ReaderState
	State of a smartcard reader. More...

Typedefs
using	ReaderStateVector = std::vector< ReaderState >
	Vector of smartcard reader states.

Functions
::LONG	GetStates (::SCARDCONTEXT context, ReaderStateVector &states, uint32_t timeout_ms=INFINITE)
	Get the state of all smartcard readers in the system.
::LONG	GetStatesChange (::SCARDCONTEXT context, ReaderStateVector &states, uint32_t timeout_ms=INFINITE)
	Get the state change of all smartcard readers in the system.
::LONG	ListReaders (::SCARDCONTEXT context, UStringVector &readers)
	Get the list of all smartcard readers in the system.
bool	MatchATR (const uint8_t *atr1, size_t atr1_size, const uint8_t *atr2, size_t atr2_size, const uint8_t *mask=nullptr, size_t mask_size=0)
	Check if an ATR matches an expected one.
::LONG	SearchSmartCard (::SCARDCONTEXT context, UString &reader_name, const uint8_t *atr=nullptr, size_t atr_size=0, const uint8_t *atr_mask=nullptr, size_t atr_mask_size=0, const uint8_t *pwr=nullptr, size_t pwr_size=0, const uint8_t *pwr_mask=nullptr, size_t pwr_mask_size=0, uint32_t timeout_ms=INFINITE)
	Search all smartcard readers for a smartcard matching an expected ATR.
UString	StrError (::LONG status)
	Get an error message for a PC/SC error.
bool	Success (::LONG status, Report &report=(ts::CerrReport::Instance()))
	Check a PC/SC status.
::LONG	Transmit (::SCARDHANDLE handle, uint32_t protocol, const void *send, size_t send_size, void *resp, size_t resp_size, uint16_t &sw, size_t &resp_length)
	Transmit an APDU to smartcard and read response.

Detailed Description

PC/SC smartcard API utilities.

Function Documentation

StrError()

UString ts::pcsc::StrError

(

::LONG

status

)

Get an error message for a PC/SC error.

Parameters

[in]

status

A PC/SC error code.

Returns

An error message for status.

Success()

bool ts::pcsc::Success	(	::LONG	status,
		Report &	report = (ts::CerrReport::Instance())
	)

Check a PC/SC status.

Parameters

[in]	status	A PC/SC error code.
[in]	report	Where to report errors. In case of error, report an error message.

Returns

True if status is success, false if error.

MatchATR()

bool ts::pcsc::MatchATR	(	const uint8_t *	atr1,
		size_t	atr1_size,
		const uint8_t *	atr2,
		size_t	atr2_size,
		const uint8_t *	mask = nullptr,
		size_t	mask_size = 0
	)

Check if an ATR matches an expected one.

Parameters

[in]	atr1	Address of returned ATR.
[in]	atr1_size	Size in bytes of returned ATR.
[in]	atr2	Address of reference ATR.
[in]	atr2_size	Size in bytes of reference ATR.
[in]	mask	Address of mask of valid bits in atr1. For each bit which is set in mask, the corresponding bits in the ATR are checked. For each bit which is cleared in mask, the corresponding bit in the ATR is ignored.
[in]	mask_size	Size in bytes of mask. If mask is shorter than atr1, the missing bytes are assumed as 0xFF. This means that missing bytes in the mask are considered as "to be checked" in the ATR.

Returns

True if atr1 matches atr2, according to mask.

ListReaders()

::LONG ts::pcsc::ListReaders	(	::SCARDCONTEXT	context,
		UStringVector &	readers
	)

Get the list of all smartcard readers in the system.

Parameters

[in,out]	context	An open PC/SC context.
[out]	readers	The list of all smartcard readers.

Returns

A PC/SC status.

GetStates()

::LONG ts::pcsc::GetStates	(	::SCARDCONTEXT	context,
		ReaderStateVector &	states,
		uint32_t	timeout_ms = INFINITE
	)

Get the state of all smartcard readers in the system.

Parameters

[in,out]	context	An open PC/SC context.
[out]	states	Returned states of all readers.
[in]	timeout_ms	The timeout is given in milliseconds (or use INFINITE).

Returns

A PC/SC status.

GetStatesChange()

::LONG ts::pcsc::GetStatesChange	(	::SCARDCONTEXT	context,
		ReaderStateVector &	states,
		uint32_t	timeout_ms = INFINITE
	)

Get the state change of all smartcard readers in the system.

Parameters

[in,out]	context	An open PC/SC context.
[in,out]	states	Updated states of all readers.
[in]	timeout_ms	The timeout is given in milliseconds (or use INFINITE).

Returns

A PC/SC status.

SearchSmartCard()

::LONG ts::pcsc::SearchSmartCard	(	::SCARDCONTEXT	context,
		UString &	reader_name,
		const uint8_t *	atr = nullptr,
		size_t	atr_size = 0,
		const uint8_t *	atr_mask = nullptr,
		size_t	atr_mask_size = 0,
		const uint8_t *	pwr = nullptr,
		size_t	pwr_size = 0,
		const uint8_t *	pwr_mask = nullptr,
		size_t	pwr_mask_size = 0,
		uint32_t	timeout_ms = INFINITE
	)

Search all smartcard readers for a smartcard matching an expected ATR.

Parameters

[in,out]	context	An open PC/SC context.
[out]	reader_name	Returned smartcard reader.
[in]	atr	Address of reference ATR. If atr is 0, the ATR is not checked and the first smartcard is used.
[in]	atr_size	Size in bytes of reference ATR.
[in]	atr_mask	Address of mask of valid bits in atr. For each bit which is set in atr_mask, the corresponding bits in the ATR are checked. For each bit which is cleared in mask, the corresponding bit in the ATR is ignored.
[in]	atr_mask_size	Size in bytes of atr_mask. If mask is shorter than atr1, the missing bytes are assumed as 0xFF. This means that missing bytes in the mask are considered as "to be checked" in the ATR.
[in]	pwr	Address of reference ATR at power up. A smartcard reader is selected if its ATR matches either atr or pwr.
[in]	pwr_size	Size in bytes of reference ATR at power uo.
[in]	pwr_mask	Address of mask of valid bits in pwr.
[in]	pwr_mask_size	Size in bytes of pwr_mask.
[in]	timeout_ms	The timeout is given in milliseconds (or use INFINITE).

Returns

A PC/SC status.

Transmit()

::LONG ts::pcsc::Transmit	(	::SCARDHANDLE	handle,
		uint32_t	protocol,
		const void *	send,
		size_t	send_size,
		void *	resp,
		size_t	resp_size,
		uint16_t &	sw,
		size_t &	resp_length
	)

Transmit an APDU to smartcard and read response.

Parameters

[in,out]	handle	PC/SC handle.
[in]	protocol	Protocol id.
[in]	send	Address of APDU data.
[in]	send_size	Size in bytes of APDU data.
[out]	resp	Address of response buffer. Upon return, the resp buffer contains the APDU response, without status word (SW).
[in]	resp_size	Size in bytes of resp buffer.
[out]	sw	Returned status word (SW).
[out]	resp_length	Actual number of returned bytes in resp.

Returns

A PC/SC status.