Readers

Obtaining readers

The smart card readers can be obtained through the following means:

SCWS.readers

Maintains the list of all known smart card readers in the system, as an array of SCWS.Reader() objects. This list is initially empty when the page loads, until the environment is established using SCWS.createEnvironment().

SCWS.updateReaderList()

Fills in or forces the update of the SCWS.readers array.

If updates are made to the reader list within the processing, the appropriate event callbacks are called.

Returns

A Promise resolved when the operation is complete. The resulting value is the updated SCWS.readers array itself.

SCWS.getReader(name)

Returns the reader with the given name.

Arguments

  • name – The reader name, as a string.

Returns

The requested SCWS.Reader() object (the result is returned immediately, not through a Promise).

Reader events

Reader events can be monitored by providing the following callback functions:

SCWS.onreaderadded

Callback (can be assigned to a user function) used to receive notifications when a reader is plugged in the computer.

The new SCWS.Reader() object is given as a parameter to the callback function.

SCWS.onreaderremoved

Callback (can be assigned to a user function) used to receive notifications when a reader is unplugged from the computer.

The removed SCWS.Reader() object is given as a parameter to the callback function.

SCWS.onreaderstatechanged

Callback (can be assigned to a user function) used to receive notifications when the state of a reader changes (e.g. insertion or withdrawal of a card, …).

The affected SCWS.Reader() object is given as a parameter to the callback function. Its properties can be consulted (e.g. Reader.status, Reader.cardPresent, …) to obtain more information about the event.

Manipulating readers

The Reader class is described below:

class SCWS.Reader()

Represents a smart card reader (either a physical, hardware reader, or a virtual smart card reader).

SCWS.Reader.name

The name of the reader.

SCWS.Reader.cardPresent

Boolean indicating if a card is inserted in the reader.

SCWS.Reader.status

Status of the reader, as a string. The following status strings can be returned:

  • "unavailable": Indicates the reader has been removed (unplugged from the computer).

  • "mute": The inserted card is mute (no answer on reset), the connection is therefore impossible.

  • "exclusive": The reader is being used in exclusive mode by another process, the connection is impossible yet.

  • "ok": The reader is in a normal state (whether a card is inserted or not).

  • Any other value indicates a problem with an indeterminate cause (driver problem, or malfunction).

SCWS.Reader.dongle

Boolean indicating if the reader is known as a USB dongle type (as opposed to a standard ID-1 format card reader). Note that this is indicative, and based on an internal registry of reader names.

SCWS.Reader.virtual

Boolean indicating if the reader is a virtual smart card.

SCWS.Reader.connectICAO([aid])

Connects to the card inserted in the reader. The card must be ICAO compliant through given Application Identifier.

Arguments

  • aid – The Application Identifier (AID), as a hexadecimal string. If value is absent, default eMRTD AID (“A0 00 00 02 47 10 01”) is used.

Throws

  • ICAO_ERR_TOKEN_NOT_PRESENT() – there is no token present in reader.

  • ICAO_ERR_TOKEN_NOT_RECOGNIZED() – connected token seems to not be an eMRTD token (select MF specified in ICAO specifications fails, given eMRTD AID is not found…).

Returns

A Promise resolving to the SCWS.ICAO.Token() object resulting from the operation.

SCWS.Reader.requiresNfcTagReaderSession()

Boolean indicating if the device supports iOS NFC Tag Reader Session.