Class Smartcard::PCSC::Card
In: ext/smartcard_pcsc/pcsc_card.c
Parent: Object

Connects a smart-card in a PC/SC reader to the Ruby world. Wraps a SCARDHANDLE structure.

Methods

Public Class methods

Establishes a connection to the card in the reader whose friendly name is reader_name. The first connection will power up and perform a reset on the card. Wraps SCardConnect in PC/SC.

context:the Smartcard::PCSC::Context to use to connect to the PC/SC resource manager
reader_name:friendly name of the reader to connect to; get using Smartcard::PCSC::Context#list_readers
share_mode:whether a shared or exclusive lock will be requested on the reader; use one of the Smartcard::PCSC::SHARE_ constants
preferred_protocols:desired protocol; use one of the Smartcard::PCSC::PROTOCOL_ constants

[Source]

/* :Document-method: new
 * call-seq:
 *      new(context, reader_name, share_mode, preferred_protocols) --> card
 * 
 * Establishes a connection to the card in the reader whose friendly name is +reader_name+.
 * The first connection will power up and perform a reset on the card.
 * Wraps _SCardConnect_ in PC/SC.
 * 
 * +context+:: the Smartcard::PCSC::Context to use to connect to the PC/SC resource manager
 * +reader_name+:: friendly name of the reader to connect to; get using Smartcard::PCSC::Context#list_readers 
 * +share_mode+:: whether a shared or exclusive lock will be requested on the reader; use one of the Smartcard::PCSC::SHARE_ constants 
 * +preferred_protocols+:: desired protocol; use one of the Smartcard::PCSC::PROTOCOL_ constants
 */
static VALUE PCSC_Card_initialize(VALUE self, VALUE rbContext, VALUE rbReaderName, VALUE rbShareMode, VALUE rbPreferredProtocols) {

Public Instance methods

Establishes a temporary exclusive access mode for doing a series of commands or transaction. Wraps SCardBeginTransaction in PC/SC.

[Source]

/* :Document-method: begin_transaction
 * call-seq:
 *      card.begin_transaction() --> self
 * 
 * Establishes a temporary exclusive access mode for doing a series of commands or transaction. 
 * Wraps _SCardBeginTransaction_ in PC/SC.
 */
static VALUE PCSC_Card_begin_transaction(VALUE self) {

Sends a command directly to the interface driver to be processed by the reader. Useful for creating client side reader drivers for functions like PIN pads, biometrics, or other smart card reader extensions that are not normally handled by PC/SC. Wraps SCardControl in PC/SC.

The bytes in the response are returned wrapped in a string. (don‘t complain, it‘s a low-level API)

control_code:control code for the operation; it‘s an integer, and it‘s IFD-specific
send_data:the data bytes to be send to the driver; wrap the bytes in a string-like object (low-level API, remember?)
max_recv_bytes:the maximum number of bytes that can be received

In general, I tried to avoid having you specify receive buffer sizes. This is the only case where that is impossible to achieve, because there is no well-known maximum buffer size, and the SCardControl call is not guaranteed to be idempotent, so it‘s not OK to re-issue it until the buffer size works out.

[Source]

/* :Document-method: control
 * call-seq:
 *      card.control(control_code, send_data, max_recv_bytes) --> recv_data
 * 
 * Sends a command directly to the interface driver to be processed by the reader.
 * Useful for creating client side reader drivers for functions like PIN pads, biometrics, or other smart card reader
 * extensions that are not normally handled by PC/SC. 
 * Wraps _SCardControl_ in PC/SC.
 * 
 * The bytes in the response are returned wrapped in a string. (don't complain, it's a low-level API)
 * 
 * +control_code+:: control code for the operation; it's an integer, and it's IFD-specific
 * +send_data+:: the data bytes to be send to the driver; wrap the bytes in a string-like object (low-level API, remember?)
 * +max_recv_bytes+:: the maximum number of bytes that can be received
 * 
 * In general, I tried to avoid having you specify receive buffer sizes. This is the only case where that is impossible to achieve,
 * because there is no well-known maximum buffer size, and the _SCardControl_ call is not guaranteed to be idempotent, so it's not OK to
 * re-issue it until the buffer size works out.
 */
static VALUE PCSC_Card_control(VALUE self, VALUE rbControlCode, VALUE rbSendData, VALUE rbMaxRecvBytes) {

Terminates the connection made using Card#new. The Card object is invalid afterwards. Wraps SCardDisconnect in PC/SC.

disposition:action to be taken on the card inside the reader; use one of the Smartcard::PCSC::DISPOSITION_ constants

[Source]

/* :Document-method: disconnect
 * call-seq:
 *      context.disconnect(disposition) --> self
 * 
 * Terminates the connection made using Card#new. The Card object is invalid afterwards.
 * Wraps _SCardDisconnect_ in PC/SC.
 * 
 * +disposition+:: action to be taken on the card inside the reader; use one of the Smartcard::PCSC::DISPOSITION_ constants
 */
static VALUE PCSC_Card_disconnect(VALUE self, VALUE rbDisposition) {

Ends a previously begun transaction. The calling application must be the owner of the previously begun transaction or an error will occur. Wraps SCardEndTransaction in PC/SC.

disposition:action to be taken on the card inside the reader; use one of the Smartcard::PCSC::DISPOSITION_ constants

[Source]

/* :Document-method: end_transaction
 * call-seq:
 *      context.end_transaction(disposition) --> attribute_value
 * 
 * Ends a previously begun transaction. The calling application must be the owner of the previously begun transaction or an error will occur. 
 * Wraps _SCardEndTransaction_ in PC/SC.
 * 
 * +disposition+:: action to be taken on the card inside the reader; use one of the Smartcard::PCSC::DISPOSITION_ constants
 */
static VALUE PCSC_Card_end_transaction(VALUE self, VALUE rbDisposition) {

Reads the value of an attribute from the interface driver. Remember that the IFD may not implement some of the attributes specified in Smartcard::PCSC, and it may implement some attributes that are not included in Smartcard::PCSC. Wraps SCardGetAttrib in PC/SC.

The returned value has the bytes in the attribute, wrapped in a string. (don‘t complain, it‘s a low-level API)

attribute_id:identifies the attribute to be read; use one of the Smartcard::PCSC::ATTR_ constants

[Source]

/* :Document-method: get_attribute
 * call-seq:
 *      card.get_attribute(attribute_id) --> attribute_value
 * 
 * Reads the value of an attribute from the interface driver.
 * Remember that the IFD may not implement some of the attributes specified in Smartcard::PCSC, and it may implement some attributes that
 * are not included in Smartcard::PCSC.
 * Wraps _SCardGetAttrib_ in PC/SC.
 * 
 * The returned value has the bytes in the attribute, wrapped in a string. (don't complain, it's a low-level API)
 * 
 * +attribute_id+:: identifies the attribute to be read; use one of the Smartcard::PCSC::ATTR_ constants
 */
static VALUE PCSC_Card_get_attribute(VALUE self, VALUE rbAttributeId) {

The error code returned by the last PC/SC call. Useful for recovering from exceptions.

The returned code is a number, and should be one of the Smartcard::PCSC::SCARD_ constants. The code indicating correct operation is Smartcard::PCSC::SCARD_S_SUCCESS.

[Source]

/* :Document-method: last_error
 * call-seq:
 *      card.last_error() --> last_error
 * 
 * The error code returned by the last PC/SC call. Useful for recovering from exceptions.
 * 
 * The returned code is a number, and should be one of the Smartcard::PCSC::SCARD_ constants.
 * The code indicating correct operation is Smartcard::PCSC::SCARD_S_SUCCESS.
 */
static VALUE PCSC_Card_last_error(VALUE self) {

Reestablishes a connection to a reader that was previously connected to using Card#new. Wraps SCardReconnect in PC/SC.

share_mode:whether a shared or exclusive lock will be requested on the reader; use one of the Smartcard::PCSC::SHARE_ constants
preferred_protocols:desired protocol; use one of the Smartcard::PCSC::PROTOCOL_ constants
initialization:action to be taken on the card inside the reader; use one of the Smartcard::PCSC::INITIALIZE_ constants

[Source]

/* :Document-method: reconnect
 * call-seq:
 *      card.reconnect(share_mode, preferred_protocols, initialization) --> self
 * 
 * Reestablishes a connection to a reader that was previously connected to using Card#new.
 * Wraps _SCardReconnect_ in PC/SC.
 * 
 * +share_mode+:: whether a shared or exclusive lock will be requested on the reader; use one of the Smartcard::PCSC::SHARE_ constants 
 * +preferred_protocols+:: desired protocol; use one of the Smartcard::PCSC::PROTOCOL_ constants
 * +initialization+:: action to be taken on the card inside the reader; use one of the Smartcard::PCSC::INITIALIZE_ constants
 */
static VALUE PCSC_Card_reconnect(VALUE self, VALUE rbShareMode, VALUE rbPreferredProtocols, VALUE rbInitialization) {

Sets the value of an attribute in the interface driver. Remember that the IFD may not implement some of the attributes specified in Smartcard::PCSC, and it may implement some attributes that are not included in Smartcard::PCSC. Wraps SCardSetAttrib in PC/SC.

attribute_id:identifies the attribute to be set; use one of the Smartcard::PCSC::ATTR_ constants
attribute_value:the value to be assigned to the attribute; wrap the bytes in a string-like object (low-level API, remember?)

[Source]

/* :Document-method: set_attribute
 * call-seq:
 *      context.set_attribute(attribute_id, attribute_value) --> self
 * 
 * Sets the value of an attribute in the interface driver.
 * Remember that the IFD may not implement some of the attributes specified in Smartcard::PCSC, and it may implement some attributes that
 * are not included in Smartcard::PCSC.
 * Wraps _SCardSetAttrib_ in PC/SC.
 * 
 * +attribute_id+:: identifies the attribute to be set; use one of the Smartcard::PCSC::ATTR_ constants
 * +attribute_value+:: the value to be assigned to the attribute; wrap the bytes in a string-like object (low-level API, remember?)
 */
static VALUE PCSC_Card_set_attribute(VALUE self, VALUE rbAttributeId, VALUE rbAttributeValue) {

Retrieves the current status of the smartcard, and packages it up in a nice hash for you. Wraps SCardStatus in PC/SC.

The response hash contains the following keys:

:state :reader/card status; bitfield, with bits defined as Smartcard::PCSC::STATUS_ constants
:protocol :the protocol established with the card; check against Smartcard::PCSC::PROTOCOL_ constants
:atr :the card‘s ATR bytes, wrapped in a string
:reader_names :array of strings containing all the names of the reader containing the smartcard

[Source]

/* :Document-method: status
 * call-seq:
 *      card.status() --> card_status
 * 
 * Retrieves the current status of the smartcard, and packages it up in a nice hash for you.
 * Wraps _SCardStatus_ in PC/SC.
 * 
 * The response hash contains the following keys:
 * <tt>:state</tt> :: reader/card status; bitfield, with bits defined as Smartcard::PCSC::STATUS_ constants
 * <tt>:protocol</tt> :: the protocol established with the card; check against Smartcard::PCSC::PROTOCOL_ constants
 * <tt>:atr</tt> :: the card's ATR bytes, wrapped in a string
 * <tt>:reader_names</tt> :: array of strings containing all the names of the reader containing the smartcard
 */
static VALUE PCSC_Card_status(VALUE self) {

Sends an APDU to the smart card, and returns the card‘s response to the APDU. Wraps SCardTransmit in PC/SC.

The bytes in the card‘s response are returned wrapped in a string. (don‘t complain, it‘s a low-level API)

send_data:the APDU to be send to the card; wrap the bytes in a string-like object (low-level API, remember?)
send_io_request:Smartcard::PCSC::IoRequest instance indicating the send protocol; you should use one of the Smartcard::PCSC::IOREQUEST_ constants
recv_io_request:Smartcard::PCSC::IoRequest instance receving information about the recv protocol; you can use the result of Smartcard::PCSC::IoRequest#new

[Source]

/* :Document-method: transmit
 * call-seq:
 *      card.transmit(send_data, send_io_request, recv_io_request) --> recv_data
 * 
 * Sends an APDU to the smart card, and returns the card's response to the APDU.
 * Wraps _SCardTransmit_ in PC/SC.
 * 
 * The bytes in the card's response are returned wrapped in a string. (don't complain, it's a low-level API)
 * 
 * +send_data+:: the APDU to be send to the card; wrap the bytes in a string-like object (low-level API, remember?)
 * +send_io_request+:: Smartcard::PCSC::IoRequest instance indicating the send protocol; you should use one of the Smartcard::PCSC::IOREQUEST_ constants
 * +recv_io_request+:: Smartcard::PCSC::IoRequest instance receving information about the recv protocol; you can use the result of Smartcard::PCSC::IoRequest#new
 */
static VALUE PCSC_Card_transmit(VALUE self, VALUE rbSendData, VALUE rbSendIoRequest, VALUE rbRecvIoRequest) {

[Validate]