.. _library_reference:

:mod:`scardface` --- Library reference
======================================

.. module:: scardface
   :synopsis: Smart card (ICC) interface library for Python.
.. moduleauthor:: Eric Devolder <eric.devolder@gmail.com>
.. sectionauthor:: Eric Devolder <eric.devolder@gmail.com>



This module implements a smart card interface libary, on top of PC/SC or WINSCARD APIs.


.. _scard_class:

:class:`scardface.SCard()`
--------------------------

The :class:`SCard` class  provides a simple framework for interfacing with a smart card, once inserted into a smart card reader. It features many useful features as exposed by the PC/SC API. 


.. class:: SCard( readers=None, groups=None, timeout=-1, atr=None, pnp=False)
   
	Initialize the SCard object, when attempting to acquire a connection 
        to a valid smart card.
        
        The optional *readers* argument can be either string or iterable of strings, containing the reader(s) to watch. Default is :class:`None`, meaning all readers are scanned.

        The optional *groups* argument can be either string or iterable of strings, containing the reader group(s) to watch. Default is :class:`None`, meaning default group is scanned.

        The optional *timeout* expresses, in seconds (can be float), the maximum time to wait for acquiring a valid smart card session. Upon timeout, an :exc:`SCardError` exception is thrown (command timeout).
                   
        * atr:      bytes, regular expression on ATR to match. 
                    re.search() is used to find a pattern,
                    so please include '^' in front of the string 
                    to match from the beginning.

        * pnp:      bool, default is False.
                    if set to True, then 'readers' and 'groups' are ignored,
                    and the reader is taken amongst the detected list
                    of readers. 
                    In case a reader is added to or removed from the
                    system, the list gets adjusted automatically.

                    This mode allows for auto-insertion of a reader
                    while the API is waiting for a card insertion.
                    
                    Caution:
                    as a side effect, this mode will watch forever even if no
                    reader is connected, when no timeout is specified.

                    platform availability: Windows
                    
        If no reader or group is given, default readers are detected.

        The algorithm attempts to find a valid smartcard connection, 
        until the timeout expires.

        When in main thread, the command can be interrupted by hitting
        CTRL-C (KeyboardInterrupt).

        When called from another thread, the command can be interrupted 
        through calling self.cancel() or cancel_all().

        """


   This constructor XXXXXXXX XXXXXXXXXXXXXXX




.. _scard_objects:

SCard objects
-------------

A :class:`SCard` instance has the following methods:

   .. method:: send(self, *apdu, callback=None):

      send one or several Command APDU to the ICC interface, using the detected protocol. meant to be protocol-independent as much as possible.

      *`*apdu`* is one or several instance(s) of :class:`C_APDU` object, to be sent to the card.

      *callback* is a reference to a callback function, which is called after every sending of a command APDU.
      Defaults to :class:`None`, meaning the default callback being used.

      returns an :class:`R_APDU` instance.

      In case several :class:`C_APDU` are chained, the sending carries on until the response code is different from ``b'\x90\x00'``. In such case, it is the failing :class:`R_APDU` that returns.


.. _functions:

scardface functions
===================

.. func:: scardface.readers( group = None )
   
   retrieves the list of readers associated with the group given as an argument, and returns it as a tuple.

   *group* is a string containing a group name.
   Defaults to :class:`None`, meaning the default group is used.
   
.. func:: scardface.groups()

   retrieves the list of readers groups, and returns it as a tuple.