smartcard.scard.scard

module documentation

The smartcard.scard module is a simple wrapper on top of the C language PCSC SCardXXX API.

The smartcard.scard module is the lower layer of the pyscard framework that provides a higher level interface.

You should avoid using the smartcard.scard package directly, and use the pyscard directly because:

smartcard.scard being a C wrapper, the code tends to look like C code written in python syntax
the smartcard package provides higher level abstractions (e.g. CardType, CardConnection), and makes programming easier since it is totally written in Python

You can still use the smartcard.scard package if you want to write your own framework, or if you want to perform quick-and-dirty port of C language programs using SCardXXX calls, or if there are features of SCardXXX API that you want to use and that are not available in the pyscard library.

Introduction

The smartcard.scard module is a Python wrapper around PCSC smart card base services. On Windows, the wrapper is performed around the smart card base components winscard library. On linux and OS X, the wrapper is performed around the PCSC-lite library.

The smartcard.scard module provides mapping for the following API functions, depending on the Operating System:

    =============================== ======= =======
    Function                        Windows  Linux
                                             OS X
    =============================== ======= =======
    GetOpenCardName
    SCardAddReaderToGroup              Y
    SCardBeginTransaction              Y       Y
    SCardCancel                        Y       Y
    SCardConnect                       Y       Y
    SCardControl                       Y       Y
    SCardDisconnect                    Y       Y
    SCardEndTransaction                Y       Y
    SCardEstablishContext              Y       Y
    SCardForgetCardType                Y
    SCardForgetReader                  Y
    SCardForgetReaderGroup             Y
    SCardFreeMemory
    SCardGetAttrib                     Y       Y
    SCardGetCardTypeProviderName       Y
    SCardGetErrorMessage               Y       Y
    SCardGetProviderId
    SCardGetStatusChange               Y       Y
    SCardIntroduceCardType             Y
    SCardIntroduceReader               Y
    SCardIntroduceReaderGroup          Y
    SCardIsValidContext                Y       Y
    SCardListCards                     Y
    SCardListInterfaces                Y
    SCardListReaderGroups              Y       Y
    SCardListReaders                   Y       Y
    SCardLocateCards                   Y
    SCardReconnect                     Y       Y
    SCardReleaseContext                Y       Y
    SCardRemoveReaderFromGroup         Y
    SCardSetAttrib                     Y       Y
    SCardSetCartTypeProviderName
    SCardStatus                        Y       Y
    SCardTransmit                      Y       Y
    SCardUIDlgSelectCard
    =============================== ======= =======

Comments, bug reports, improvements welcome.

-------------------------------------------------------------------------------

Authors

Jean-Daniel Aussel, mailto:jean-daniel.aussel@gemalto.com

Ludovic Rousseau, mailto:ludovic.rousseau@free.fr

This file is part of pyscard.

pyscard is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

pyscard is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with pyscard; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Function	`SCARD_CTL_CODE`	SCARD_CTL_CODE(long code) -> long
Function	`SCardAddReaderToGroup`	SCardAddReaderToGroup( hcontext, readername, groupname) -> SCARDRETCODE
Function	`SCardBeginTransaction`	SCardBeginTransaction( hcard) -> SCARDRETCODE
Function	`SCardCancel`	SCardCancel( hcontext) -> SCARDRETCODE
Function	`SCardConnect`	SCardConnect( hcontext, readername, dwShareMode, dwPreferredProtocols) -> SCARDRETCODE
Function	`SCardControl`	SCardControl( hcard, dwControlCode, byte[] inbuffer) -> SCARDRETCODE
Function	`SCardDisconnect`	SCardDisconnect( hcard, dwDisposition) -> SCARDRETCODE
Function	`SCardEndTransaction`	SCardEndTransaction( hcard, dwDisposition) -> SCARDRETCODE
Function	`SCardEstablishContext`	SCardEstablishContext( dwScope) -> SCARDRETCODE
Function	`SCardForgetReaderGroup`	SCardForgetReaderGroup( hcontext, groupname) -> SCARDRETCODE
Function	`SCardGetAttrib`	SCardGetAttrib( hcard, dwAttrId) -> SCARDRETCODE
Function	`SCardGetErrorMessage`	SCardGetErrorMessage(long lErrCode) -> ERRORSTRING
Function	`SCardGetStatusChange`	SCardGetStatusChange( hcontext, dwTimeout, tuple[] readerstatelist) -> SCARDRETCODE
Function	`SCardIntroduceReader`	SCardIntroduceReader( hcontext, readername, devicename) -> SCARDRETCODE
Function	`SCardIntroduceReaderGroup`	SCardIntroduceReaderGroup( hcontext, groupname) -> SCARDRETCODE
Function	`SCardIsValidContext`	SCardIsValidContext( hcontext) -> SCARDRETCODE
Function	`SCardListReaderGroups`	SCardListReaderGroups( hcontext) -> SCARDRETCODE
Function	`SCardListReaders`	SCardListReaders( hcontext, [] readergroups) -> SCARDRETCODE
Function	`SCardReconnect`	SCardReconnect( hcard, dwShareMode, dwPreferredProtocols, dwInitialization) -> SCARDRETCODE
Function	`SCardReleaseContext`	SCardReleaseContext( hcontext) -> SCARDRETCODE
Function	`SCardRemoveReaderFromGroup`	SCardRemoveReaderFromGroup( hcontext, readername, groupname) -> SCARDRETCODE
Function	`SCardSetAttrib`	SCardSetAttrib( hcard, dwAttrId, BYTELIST * ATTRIBUTESIN) -> SCARDRETCODE
Function	`SCardStatus`	SCardStatus( hcard) -> SCARDRETCODE
Function	`SCardTransmit`	SCardTransmit( hcard, unsigned long pioSendPci, byte[] apducommand) -> SCARDRETCODE
Class	`_SwigNonDynamicMeta`	Meta class to enforce nondynamic attributes (no new attributes) for a class
Function	`_swig_add_metaclass`	Class decorator for adding a metaclass to a SWIG wrapped class - a slimmed down version of six.add_metaclass
Function	`_swig_repr`	Undocumented
Function	`_swig_setattr_nondynamic_class_variable`	Undocumented
Function	`_swig_setattr_nondynamic_instance_variable`	Undocumented

def SCARD_CTL_CODE(code): ¶

SCARD_CTL_CODE(long code) -> long

This function returns the value of a control code

>>> from smartcard.scard import *
>>> ...
>>> CM_IOCTL_GET_FEATURE_REQUEST = SCARD_CTL_CODE(3400)
>>> ...

def SCardAddReaderToGroup(hcontext, readername, groupname): ¶

SCardAddReaderToGroup( hcontext, readername, groupname) -> SCARDRETCODE

adds a reader to a reader group

Windows only, not supported by PCSC lite wrapper.

example:

>>> from smartcard.scard import *
>>> ... establish context ...
>>> newgroup = 'SCard$MyOwnGroup'
>>> reader = 'SchlumbergerSema Reflex USB v.2 0'
>>> readeralias = 'SchlumbergerSema Reflex USB v.2 0 alias'
>>> hresult = SCardIntroduceReader(hcontext, readeralias, reader])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise error('Unable to introduce reader: ' +
>>>     SCardGetErrorMessage(hresult))
>>>
>>> hresult = SCardAddReaderToGroup(hcontext, readeralias, newgroup)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise error('Unable to add reader to group: ' +
>>>     SCardGetErrorMessage(hresult))
...

def SCardBeginTransaction(hcard): ¶

SCardBeginTransaction( hcard) -> SCARDRETCODE

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.

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # connect
>>> hresult, hcard, dwActiveProtocol = SCardConnect(
>>>     hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>>
>>> # begin transaction
>>> hresult = SCardBeginTransaction(hcard)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)

def SCardCancel(hcontext): ¶

SCardCancel( hcontext) -> SCARDRETCODE

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

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>> ... establish context ...
>>> hresult = SCardCancel(hcard)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
...

def SCardConnect(hcontext, readername, dwShareMode, dwPreferredProtocols): ¶

SCardConnect( hcontext, readername, dwShareMode, dwPreferredProtocols) -> SCARDRETCODE

This function establishes a connection to the friendly name of the reader specified in readername. The first connection will power up and perform a reset on the card.

Value of dwShareMode:

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.

Value of dwPreferredProtocols:

SCARD_PROTOCOL_T0 Use the T=0 protocol
SCARD_PROTOCOL_T1 Use the T=1 protocol
SCARD_PROTOCOL_RAW Use with memory type cards

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # connect
>>> hresult, hcard, dwActiveProtocol = SCardConnect(
>>>     hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)

def SCardControl(hcard, dwControlCode, inbuffer): ¶

SCardControl( hcard, dwControlCode, byte[] inbuffer) -> SCARDRETCODE

This function sends a control command to the reader connected to by SCardConnect(). It returns a result and the control response.

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # connect
>>> hresult, hcard, dwActiveProtocol = SCardConnect(
>>>     hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>>
>>> # control
>>> CMD = [0x12, 0x34]
>>> hresult, response = SCardControl(hcard, 42, CMD)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)

def SCardDisconnect(hcard, dwDisposition): ¶

SCardDisconnect( hcard, dwDisposition) -> SCARDRETCODE

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

Value of disposition:

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

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # connect
>>> hresult, hcard, dwActiveProtocol = SCardConnect(
>>>     hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>>
>>> # disconnect
>>> hresult = SCardDisconnect(hcard, SCARD_UNPOWER_CARD)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)

def SCardEndTransaction(hcard, dwDisposition): ¶

SCardEndTransaction( hcard, dwDisposition) -> SCARDRETCODE

This function ends a previously begun transaction. The calling application must be the owner of the previously begun transaction or an error will occur.

Value of disposition:

SCARD_LEAVE_CARD Do nothing
SCARD_RESET_CARD Reset the card
SCARD_UNPOWER_CARD Unpower the card
SCARD_EJECT_CARD Eject the card

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # connect
>>> hresult, hcard, dwActiveProtocol = SCardConnect(
>>>     hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>>
>>> # begin transaction
>>> hresult = SCardBeginTransaction(hcard)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>>
>>> # end transaction
>>> hresult = SCardEndTransaction(hcard, SCARD_LEAVE_CARD)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)

def SCardEstablishContext(dwScope): ¶

SCardEstablishContext( dwScope) -> SCARDRETCODE

This function creates a communication context to the PC/SC Resource Manager. This must be the first PC/SC function called in a PC/SC application.

Value of dwScope:

SCARD_SCOPE_USER Operations performed within the scope of the User
SCARD_SCOPE_TERMINAL Not used
SCARD_SCOPE_GLOBAL Not used
SCARD_SCOPE_SYSTEM Operations performed within the scope of the system

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)

def SCardForgetReaderGroup(hcontext, groupname): ¶

SCardForgetReaderGroup( hcontext, groupname) -> SCARDRETCODE

Removes a previously introduced smart card reader group from the smart card subsystem. Although this function automatically clears all readers from the group, it does not affect the existence of the individual readers in the database.

Windows only, not supported by PCSC lite wrapper.

>>> from smartcard.scard import *
>>> ... establish context ...
>>> ...
>>> hresult = SCardForgetReaderGroup(hcontext, newgroup)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise error('Unable to forget reader group: ' +
>>>     SCardGetErrorMessage(hresult))
...

def SCardGetAttrib(hcard, dwAttrId): ¶

SCardGetAttrib( hcard, dwAttrId) -> SCARDRETCODE

This function get an attribute from the IFD Handler.

The possible attributes are:

    ======================================== ======= =======
    Attribute                                Windows  PCSC
                                                      lite
    ======================================== ======= =======
    SCARD_ATTR_ASYNC_PROTOCOL_TYPES                     Y
    SCARD_ATTR_ATR_STRING                       Y       Y
    SCARD_ATTR_CHANNEL_ID                       Y       Y
    SCARD_ATTR_CHARACTERISTICS                  Y       Y
    SCARD_ATTR_CURRENT_BWT                      Y       Y
    SCARD_ATTR_CURRENT_CLK                      Y       Y
    SCARD_ATTR_CURRENT_CWT                      Y       Y
    SCARD_ATTR_CURRENT_D                        Y       Y
    SCARD_ATTR_CURRENT_EBC_ENCODING             Y       Y
    SCARD_ATTR_CURRENT_F                        Y       Y
    SCARD_ATTR_CURRENT_IFSC                     Y       Y
    SCARD_ATTR_CURRENT_IFSD                     Y       Y
    SCARD_ATTR_CURRENT_IO_STATE                 Y       Y
    SCARD_ATTR_CURRENT_N                        Y       Y
    SCARD_ATTR_CURRENT_PROTOCOL_TYPE            Y       Y
    SCARD_ATTR_CURRENT_W                        Y       Y
    SCARD_ATTR_DEFAULT_CLK                      Y       Y
    SCARD_ATTR_DEFAULT_DATA_RATE                Y       Y
    SCARD_ATTR_DEVICE_FRIENDLY_NAME_A           Y       Y
    SCARD_ATTR_DEVICE_FRIENDLY_NAME_W           Y       Y
    SCARD_ATTR_DEVICE_IN_USE                    Y       Y
    SCARD_ATTR_DEVICE_SYSTEM_NAME_A             Y       Y
    SCARD_ATTR_DEVICE_SYSTEM_NAME_W             Y       Y
    SCARD_ATTR_DEVICE_UNIT                      Y       Y
    SCARD_ATTR_ESC_AUTHREQUEST                  Y       Y
    SCARD_ATTR_ESC_CANCEL                       Y       Y
    SCARD_ATTR_ESC_RESET                        Y       Y
    SCARD_ATTR_EXTENDED_BWT                     Y       Y
    SCARD_ATTR_ICC_INTERFACE_STATUS             Y       Y
    SCARD_ATTR_ICC_PRESENCE                     Y       Y
    SCARD_ATTR_ICC_TYPE_PER_ATR                 Y       Y
    SCARD_ATTR_MAXINPUT                         Y       Y
    SCARD_ATTR_MAX_CLK                          Y       Y
    SCARD_ATTR_MAX_DATA_RATE                    Y       Y
    SCARD_ATTR_MAX_IFSD                         Y       Y
    SCARD_ATTR_POWER_MGMT_SUPPORT               Y       Y
    SCARD_ATTR_SUPRESS_T1_IFS_REQUEST           Y       Y
    SCARD_ATTR_SYNC_PROTOCOL_TYPES                      Y
    SCARD_ATTR_USER_AUTH_INPUT_DEVICE           Y       Y
    SCARD_ATTR_USER_TO_CARD_AUTH_DEVICE         Y       Y
    SCARD_ATTR_VENDOR_IFD_SERIAL_NO             Y       Y
    SCARD_ATTR_VENDOR_IFD_TYPE                  Y       Y
    SCARD_ATTR_VENDOR_IFD_VERSION               Y       Y
    SCARD_ATTR_VENDOR_NAME                      Y       Y
    ======================================== ======= =======

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.

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # connect
>>> hresult, hcard, dwActiveProtocol = SCardConnect(
>>>     hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>>
>>> # get attribute
>>> hresult, attrib = SCardGetAttrib(hcard, SCARD_ATTR_ATR_STRING)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>> print(attrib)

def SCardGetErrorMessage(lErrCode): ¶

SCardGetErrorMessage(long lErrCode) -> ERRORSTRING

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

>>> from smartcard.scard import *
>>> ...
>>> hresult, response = SCardTransmit(hcard, SCARD_PCI_T0, SELECT + DF_TELECOM)
>>> if hresult != SCARD_S_SUCCESS:
>>>     print('Failed to transmit:', SCardGetErrorMessage(hresult))
>>> ...

def SCardGetStatusChange(hcontext, dwTimeout, readerstatelist): ¶

SCardGetStatusChange( hcontext, dwTimeout, tuple[] readerstatelist) -> SCARDRETCODE

This function receives a structure or list of tuples containing reader states. A READERSTATE hast three fields (readername, state, atr). It then blocks for a change in state to occur on any of the OR'd values contained in the current state for a maximum blocking time of dwTimeout or forever if INFINITE is used. The new event state will be contained in state. A status change might be a card insertion or removal event, a change in ATR, etc.

Value of state:

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

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # get status change
>>> readerstates = []
>>> for reader in readers:
>>>     readerstates.append((reader, SCARD_STATE_UNAWARE))
>>>
>>> hresult, newstates = SCardGetStatusChange(hcontext, INFINITE, readerstates)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>> for state in newstates:
>>>     reader, eventstate, atr = state
>>>     print(f'Reader: {reader}:', end='')
>>>     if eventstate & SCARD_STATE_PRESENT:
>>>         print(' Card present')
>>>     if eventstate & SCARD_STATE_EMPTY:
>>>         print(' Reader empty')
>>>
>>> print('insert or remove a card')
>>> # wait for card move
>>> readerstates = newstates
>>> hresult, newstates = SCardGetStatusChange(hcontext, INFINITE, readerstates)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)

def SCardIntroduceReader(hcontext, readername, devicename): ¶

SCardIntroduceReader( hcontext, readername, devicename) -> SCARDRETCODE

Introduces a reader to the smart card subsystem.

Windows only, not supported by PCSC lite wrapper.

>>> from smartcard.scard import *
>>> ...
>>> dummyreader = readers[0] + ' dummy'
>>> hresult = SCardIntroduceReader(hcontext, dummyreader, readers[0])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise error('Unable to introduce reader: ' + dummyreader + ' : '
>>>     + SCardGetErrorMessage(hresult))
...

def SCardIntroduceReaderGroup(hcontext, groupname): ¶

SCardIntroduceReaderGroup( hcontext, groupname) -> SCARDRETCODE

Introduces a reader group to the smart card subsystem. However, the reader group is not created until the group is specified when adding a reader to the smart card database.

Windows only, not supported by PCSC lite wrapper.

>>> from smartcard.scard import *
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> hresult = SCardIntroduceReaderGroup(hcontext, 'SCard$MyOwnGroup')
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise error('Unable to introduce reader group: ' +
>>>     SCardGetErrorMessage(hresult))
>>> hresult = SCardAddReaderToGroup(hcontext, 'SchlumbergerSema Reflex USB v.2 0', 'SCard$MyOwnGroup')
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise error('Unable to add reader to group: ' +
>>>     SCardGetErrorMessage(hresult))

def SCardIsValidContext(hcontext): ¶

SCardIsValidContext( hcontext) -> SCARDRETCODE

This function determines 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.

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # valid context?
>>> hresult = SCardIsValidContext(hcontext)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)

def SCardListReaderGroups(hcontext): ¶

SCardListReaderGroups( hcontext) -> SCARDRETCODE

This function returns a list of currently available reader groups on the system.

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> hresult, readerGroups = SCardListReaderGroups(hcontext)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>> print('PCSC Reader groups:', readerGroups)

def SCardListReaders(hcontext, readergroups): ¶

SCardListReaders( hcontext, [] readergroups) -> SCARDRETCODE

This function returns a list of currently available readers on the system. A list of group can be provided in input to list readers in a given group only.

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>> for reader in readers:
>>>     print(reader)

def SCardReconnect(hcard, dwShareMode, dwPreferredProtocols, dwInitialization): ¶

SCardReconnect( hcard, dwShareMode, dwPreferredProtocols, dwInitialization) -> SCARDRETCODE

This function 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 it's state accordingly.

Value of dwShareMode:

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

Value of dwPreferredProtocols:

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.

Value of dwInitialization:

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

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # connect
>>> hresult, hcard, dwActiveProtocol = SCardConnect(
>>>     hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>>
>>> # reconnect
>>> hresult, activeProtocol = SCardReconnect(hcard, SCARD_SHARE_EXCLUSIVE, SCARD_PROTOCOL_T0, SCARD_RESET_CARD)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)

def SCardReleaseContext(hcontext): ¶

SCardReleaseContext( hcontext) -> SCARDRETCODE

Release a PC/SC context established by SCardEstablishContext().

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # release context
>>> hresult = SCardReleaseContext(hcontext)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ReleaseContextException(hresult)

def SCardRemoveReaderFromGroup(hcontext, readername, groupname): ¶

SCardRemoveReaderFromGroup( hcontext, readername, groupname) -> SCARDRETCODE

Removes a reader from an existing reader group. This function has no affect on the reader.

Windows only, not supported by PCSC lite wrapper.

>>> from smartcard.scard import *
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> hresult = SCardRemoveReaderFromGroup(hcontext, 'SchlumbergerSema Reflex USB v.2 0', 'SCard$MyOwnGroup')
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise error('Unable to remove reader from group: ' +
>>>     SCardGetErrorMessage(hresult))
...

def SCardSetAttrib(hcard, dwAttrId, ATTRIBUTESIN): ¶

SCardSetAttrib( hcard, dwAttrId, BYTELIST * ATTRIBUTESIN) -> SCARDRETCODE

This function sets an attribute from the IFD Handler. Not all attributes are supported by all readers nor can they be set at all times.

The possible attributes are:

    ======================================== ======= =======
    Attribute                                Windows  PCSC
                                                      lite
    ======================================== ======= =======
    SCARD_ATTR_ASYNC_PROTOCOL_TYPES                     Y
    SCARD_ATTR_ATR_STRING                       Y       Y
    SCARD_ATTR_CHANNEL_ID                       Y       Y
    SCARD_ATTR_CHARACTERISTICS                  Y       Y
    SCARD_ATTR_CURRENT_BWT                      Y       Y
    SCARD_ATTR_CURRENT_CLK                      Y       Y
    SCARD_ATTR_CURRENT_CWT                      Y       Y
    SCARD_ATTR_CURRENT_D                        Y       Y
    SCARD_ATTR_CURRENT_EBC_ENCODING             Y       Y
    SCARD_ATTR_CURRENT_F                        Y       Y
    SCARD_ATTR_CURRENT_IFSC                     Y       Y
    SCARD_ATTR_CURRENT_IFSD                     Y       Y
    SCARD_ATTR_CURRENT_IO_STATE                 Y       Y
    SCARD_ATTR_CURRENT_N                        Y       Y
    SCARD_ATTR_CURRENT_PROTOCOL_TYPE            Y       Y
    SCARD_ATTR_CURRENT_W                        Y       Y
    SCARD_ATTR_DEFAULT_CLK                      Y       Y
    SCARD_ATTR_DEFAULT_DATA_RATE                Y       Y
    SCARD_ATTR_DEVICE_FRIENDLY_NAME_A           Y       Y
    SCARD_ATTR_DEVICE_FRIENDLY_NAME_W           Y       Y
    SCARD_ATTR_DEVICE_IN_USE                    Y       Y
    SCARD_ATTR_DEVICE_SYSTEM_NAME_A             Y       Y
    SCARD_ATTR_DEVICE_SYSTEM_NAME_W             Y       Y
    SCARD_ATTR_DEVICE_UNIT                      Y       Y
    SCARD_ATTR_ESC_AUTHREQUEST                  Y       Y
    SCARD_ATTR_ESC_CANCEL                       Y       Y
    SCARD_ATTR_ESC_RESET                        Y       Y
    SCARD_ATTR_EXTENDED_BWT                     Y       Y
    SCARD_ATTR_ICC_INTERFACE_STATUS             Y       Y
    SCARD_ATTR_ICC_PRESENCE                     Y       Y
    SCARD_ATTR_ICC_TYPE_PER_ATR                 Y       Y
    SCARD_ATTR_MAXINPUT                         Y       Y
    SCARD_ATTR_MAX_CLK                          Y       Y
    SCARD_ATTR_MAX_DATA_RATE                    Y       Y
    SCARD_ATTR_MAX_IFSD                         Y       Y
    SCARD_ATTR_POWER_MGMT_SUPPORT               Y       Y
    SCARD_ATTR_SUPRESS_T1_IFS_REQUEST           Y       Y
    SCARD_ATTR_SYNC_PROTOCOL_TYPES                      Y
    SCARD_ATTR_USER_AUTH_INPUT_DEVICE           Y       Y
    SCARD_ATTR_USER_TO_CARD_AUTH_DEVICE         Y       Y
    SCARD_ATTR_VENDOR_IFD_SERIAL_NO             Y       Y
    SCARD_ATTR_VENDOR_IFD_TYPE                  Y       Y
    SCARD_ATTR_VENDOR_IFD_VERSION               Y       Y
    SCARD_ATTR_VENDOR_NAME                      Y       Y
    ======================================== ======= =======

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.

>>> from smartcard.scard import *
>>> ... establish context and connect to card ...
>>> hresult, attrib = SCardSetAttrib(hcard, SCARD_ATTR_VENDOR_NAME, ['G', 'e', 'm', 'a', 'l', 't', 'o'])
>>> if hresult != SCARD_S_SUCCESS:
>>>      print('Failed to set attribute')
>>> ...

def SCardStatus(hcard): ¶

SCardStatus( hcard) -> SCARDRETCODE

This function returns the current status of the reader connected to by hcard. The reader friendly name is returned, as well as the state, protocol and ATR. The state is a DWORD possibly OR'd with the following values:

Value of pdwState:

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

Value of pdwProtocol:

SCARD_PROTOCOL_T0 Use the T=0 protocol
SCARD_PROTOCOL_T1 Use the T=1 protocol

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>> from smartcard.util import toHexString
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # connect
>>> hresult, hcard, dwActiveProtocol = SCardConnect(
>>>     hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>>
>>> # status
>>> hresult, reader, state, protocol, atr = SCardStatus(hcard)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>> print('Reader:', reader)
>>> print('State: 0x%04X' % state)
>>> print('Protocol:', protocol)
>>> print('ATR:', toHexString(atr))

def SCardTransmit(hcard, pioSendPci, apducommand): ¶

SCardTransmit( hcard, unsigned long pioSendPci, byte[] apducommand) -> SCARDRETCODE

This function sends an APDU to the smart card contained in the reader connected to by SCardConnect(). It returns a result and the card APDU response.

Value of pioSendPci:

SCARD_PCI_T0 Pre-defined T=0 PCI structure
SCARD_PCI_T1 Pre-defined T=1 PCI structure

>>> from smartcard.scard import *
>>> from smartcard.pcsc import *
>>> from smartcard.util import toHexString
>>>
>>> # establish context
>>> hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.EstablishContextException(hresult)
>>>
>>> # list readers
>>> hresult, readers = SCardListReaders(hcontext, [])
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.ListReadersException(hresult)
>>>
>>> # connect
>>> hresult, hcard, dwActiveProtocol = SCardConnect(
>>>     hcontext, readers[0], SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>>
>>> # transmit
>>> SELECT = [0xA0, 0xA4, 0x00, 0x00, 0x02]
>>> DF_TELECOM = [0x7F, 0x10]
>>> hresult, response = SCardTransmit(hcard, SCARD_PCI_T0, SELECT + DF_TELECOM)
>>> if hresult != SCARD_S_SUCCESS:
>>>     raise PCSCExceptions.BaseSCardException(hresult)
>>> print(toHexString(response))

def _swig_add_metaclass(metaclass): ¶

Class decorator for adding a metaclass to a SWIG wrapped class - a slimmed down version of six.add_metaclass

def _swig_repr(self): ¶

Undocumented

def _swig_setattr_nondynamic_class_variable(set): ¶

Undocumented

def _swig_setattr_nondynamic_instance_variable(set): ¶

Undocumented