Provided by: libpcsc-perl_1.4.14-3_amd64 bug

NAME

       Chipcard::PCSC - Smart card reader interface library

SYNOPSIS

        my $hContext = new Chipcard::PCSC();

        @ReadersList = $hContext->ListReaders ();

        $hContext->GetStatusChange(\@readers_states, $timeout);

        $apdu = Chipcard::PCSC::array_to_ascii(@apdu);

        @apdu = Chipcard::PCSC::ascii_to_array($apdu);

        $hContext = undef;

DESCRIPTION

       The PCSC module implements the Chipcard::PCSC class. Objects of this class are used to
       communicate with the PCSC-lite daemon (see pcscd(1) for more information).

       PC/SC represents an abstraction layer to smart card readers. It provides a communication
       layer with a wide variety of smart card readers through a standardized API.

       A PCSC object can be used to communicate with more than one reader through
       Chipcard::PCSC::Card objects. Please read Chipcard::PCSC::Card for extended information on
       how to talk to a smart card reader.

       A PCSC object uses the following property: "$pcsc_object->{hContext}" the context returned
       by the pcsc library

CONSTRUCTORS

       The following methods can be used to construct a PCSC object:

       •   $hContext = new Chipcard::PCSC($scope, $remote_host);

           •   $scope is the scope of the connection to the PC/SC daemon. It can be any of the
               following:

                $Chipcard::PCSC::SCARD_SCOPE_USER     (not used by PCSClite);
                $Chipcard::PCSC::SCARD_SCOPE_TERMINAL (not used by PCSClite);
                $Chipcard::PCSC::SCARD_SCOPE_SYSTEM   Services on the local machine;
                $Chipcard::PCSC::SCARD_SCOPE_GLOBAL   Services on a remote host.

           •   $remote_host is the host name of the remote machine to contact. It is only used
               when $scope is equal to $Chipcard::PCSC::SCARD_SCOPE_GLOBAL. A null value means
               localhost.

       •   $hContext = new Chipcard::PCSC($scope);

           This method is equivalent to:

            $hContext = new Chipcard::PCSC($scope, 0);

       •   $hContext = new Chipcard::PCSC();

           This method is equivalent to:

            $hContext = new Chipcard::PCSC($Chipcard::PCSC::SCARD_SCOPE_SYSTEM, 0);

CONSTRUCTION FAILURE

       Chipcard::PCSC constructors return an "undef" value when the object can not be created.
       $Chipcard::PCSC::errno can be used to get more information about the error.  (See section
       "ERROR HANDLING" below for more information)

Chipcard::PCSC METHODS

       Here is a list of all the methods that can be used with a PCSC object.

       •   hContext->ListReaders( $group );

           This method returns the available readers in the given $group. If omitted, $group
           defaults to a null value meaning "all groups". Please note that as of this writing,
           $group can safely be omitted as it is not used by PCSClite.

           The return value upon successful completion is an array of strings: one string by
           available reader. If an error occurred, the undef value is returned and
           $Chipcard::PCSC::errno should be used to get more information about the error.  (See
           section "ERROR HANDLING" below for more information). The following example describes
           the use of ListReaders:

            $hContext = new Chipcard::PCSC();
            die ("Can't create the PCSC object: $Chipcard::PCSC::errno\n")
                   unless (defined $hContext);

            @ReadersList = $hContext->ListReaders ();
            die ("Can't get readers' list: $Chipcard::PCSC::errno\n")
                   unless (defined($ReadersList[0]));

            $, = "\n  ";
            print @ReadersList . "\n";

       •   $hContext->GetStatusChange(\@readers_states, $timeout);

           The method "$hContext->GetStatusChange(\@readers_states, $timeout)" uses a reference
           to a list of hashes.

            # create the list or readers to watch
            map { push @readers_states, ({'reader_name'=>"$_"}) } @ReadersList;

            @StatusResult = $hContext->GetStatusChange(\@readers_states);

           The keys of the hash are: 'reader_name', 'current_state', 'event_state' and 'ATR'.

           To detect a status change you have to first get the status and then copy the
           'event_state' in the 'current_state'. The method will return when both states are
           different or a timeout occurs.

            @StatusResult = $hContext->GetStatusChange(\@readers_states);
            foreach $reader (@readers_states)
            {
              $reader->{current_state} = $reader->{event_state};
            }
            @StatusResult = $hContext->GetStatusChange(\@readers_states);

       •   $hContext->GetStatusChange(\@readers_states);

           This method is equivalent to:

            $hContext->GetStatusChange(\@readers_states, 0xFFFFFFFF);

           The timeout is set to infinite.

       •   $apdu_ref = Chipcard::PCSC::ascii_to_array($apdu);

           The method "Chipcard::PCSC::Card::Transmit()" uses references to arrays as in and out
           parameters. The "Chipcard::PCSC::ascii_to_array()" is used to transform an APDU in
           ASCII format to a reference to an array in the good format.

           Example:

            $SendData = Chipcard::PCSC::ascii_to_array("00 A4 01 00 02 01 00");

       •   $apdu = Chipcard::PCSC::array_to_ascii($apdu_ref);

           This method is used to convert the result of a "Chipcard::PCSC::Card::Transmit()" into
           ASCII format.

           Example:

            $RecvData = $hCard->Transmit($SendData);
            print Chipcard::PCSC::array_to_ascii($RecvData);

ERROR HANDLING

       All functions from PCSC objects save the return value in a global variable called
       $Chipcard::PCSC::errno. This variable therefore holds the latest status of PCSC.

       It is a double-typed magical variable that behaves just like $!. This means that it both
       holds a numerical value describing the error and the corresponding string.  The numerical
       value may change from a system to another as it depends on the PCSC library...

       Here is a small example of how to use it:

        $hContext = new Chipcard::PCSC();
        die ("Can't create the PCSC object: $Chipcard::PCSC::errno\n")
            unless (defined $hContext);

       In case the last call was successful, $Chipcard::PCSC::errno contains the
       "SCARD_S_SUCCESS" status. Here is a list of all possible error codes.  They are defined as
       read-only variables with in the PCSC module:

        $Chipcard::PCSC::SCARD_S_SUCCESS
        $Chipcard::PCSC::SCARD_E_CANCELLED
        $Chipcard::PCSC::SCARD_E_CANT_DISPOSE
        $Chipcard::PCSC::SCARD_E_CARD_UNSUPPORTED
        $Chipcard::PCSC::SCARD_E_DUPLICATE_READER
        $Chipcard::PCSC::SCARD_E_INSUFFICIENT_BUFFER
        $Chipcard::PCSC::SCARD_E_INVALID_ATR
        $Chipcard::PCSC::SCARD_E_INVALID_HANDLE
        $Chipcard::PCSC::SCARD_E_INVALID_PARAMETER
        $Chipcard::PCSC::SCARD_E_INVALID_TARGET
        $Chipcard::PCSC::SCARD_E_INVALID_VALUE
        $Chipcard::PCSC::SCARD_E_NO_MEMORY
        $Chipcard::PCSC::SCARD_E_NO_SERVICE
        $Chipcard::PCSC::SCARD_E_NO_SMARTCARD
        $Chipcard::PCSC::SCARD_E_NOT_READY
        $Chipcard::PCSC::SCARD_E_NOT_TRANSACTED
        $Chipcard::PCSC::SCARD_E_PCI_TOO_SMALL
        $Chipcard::PCSC::SCARD_E_PROTO_MISMATCH
        $Chipcard::PCSC::SCARD_E_READER_UNAVAILABLE
        $Chipcard::PCSC::SCARD_E_READER_UNSUPPORTED
        $Chipcard::PCSC::SCARD_E_SERVICE_STOPPED
        $Chipcard::PCSC::SCARD_E_SHARING_VIOLATION
        $Chipcard::PCSC::SCARD_E_SYSTEM_CANCELLED
        $Chipcard::PCSC::SCARD_E_TIMEOUT
        $Chipcard::PCSC::SCARD_E_UNKNOWN_CARD
        $Chipcard::PCSC::SCARD_E_UNKNOWN_READER
        $Chipcard::PCSC::SCARD_E_UNSUPPORTED_FEATURE

        $Chipcard::PCSC::SCARD_W_REMOVED_CARD
        $Chipcard::PCSC::SCARD_W_RESET_CARD
        $Chipcard::PCSC::SCARD_W_UNPOWERED_CARD
        $Chipcard::PCSC::SCARD_W_UNRESPONSIVE_CARD
        $Chipcard::PCSC::SCARD_W_UNSUPPORTED_CARD

       PCSClite users will also be able to use the following (PCSClite specific) codes:

        $Chipcard::PCSC::SCARD_INSERTED
        $Chipcard::PCSC::SCARD_REMOVED
        $Chipcard::PCSC::SCARD_RESET
        $Chipcard::PCSC::SCARD_SCOPE_GLOBAL

       In addition, the wrapper defines:

        $Chipcard::PCSC::SCARD_P_ALREADY_CONNECTED
        $Chipcard::PCSC::SCARD_P_NOT_CONNECTED

SEE ALSO

       pcscd(1) manpage has useful information about PC/SC lite.  Chipcard::PCSC::Card manpage
       gives information about how to communicate with a reader and the smart card inside it.

COPYRIGHT

       (C) Lionel VICTOR & Ludovic ROUSSEAU, 2001-2004, GNU GPL (C) Ludovic ROUSSEAU, 2005-2008,
       GNU GPL

AUTHORS / ACKNOWLEDGEMENT

        Lionel VICTOR <lionel.victor@unforgettable.com>
                      <lionel.victor@free.fr>

        Ludovic ROUSSEAU <ludovic.rousseau@free.fr>