.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PCSC 3"
.TH PCSC 3 2024-02-18 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Chipcard::PCSC \- Smart card reader interface library
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& my $hContext = new Chipcard::PCSC();
\&
\& @ReadersList = $hContext\->ListReaders ();
\&
\& $hContext\->GetStatusChange(\e@readers_states, $timeout);
\&
\& $apdu = Chipcard::PCSC::array_to_ascii(@apdu);
\&
\& @apdu = Chipcard::PCSC::ascii_to_array($apdu);
\&
\& $hContext = undef;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The PCSC module implements the Chipcard::PCSC class. Objects of this
class are used to communicate with the PCSC-lite daemon (see \fR\f(BIpcscd\fR\fI\|(1)\fR
for more information).
.PP
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.
.PP
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.
.PP
A PCSC object uses the following property:
\&\f(CW\*(C`$pcsc_object\->{hContext}\*(C'\fR the context returned by the pcsc library
.SH CONSTRUCTORS
.IX Header "CONSTRUCTORS"
The following methods can be used to construct a PCSC object:
.IP \(bu 4
\&\fR\f(CB$hContext\fR\fB = new Chipcard::PCSC($scope, \fR\f(CB$remote_host\fR\fB);\fR
.RS 4
.IP \(bu 4
\&\f(CW$scope\fR is the scope of the connection to the PC/SC daemon. It can be
any of the following:
.Sp
.Vb 4
\& $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.
.Ve
.IP \(bu 4
\&\f(CW$remote_host\fR is the host name of the remote machine to contact. It is
only used when \f(CW$scope\fR is equal to
\&\f(CW$Chipcard::PCSC::SCARD_SCOPE_GLOBAL\fR. A null value means \fIlocalhost\fR.
.RE
.RS 4
.RE
.IP \(bu 4
\&\fR\f(CB$hContext\fR\fB = new Chipcard::PCSC($scope);\fR
.Sp
This method is equivalent to:
.Sp
.Vb 1
\& $hContext = new Chipcard::PCSC($scope, 0);
.Ve
.IP \(bu 4
\&\fR\f(CB$hContext\fR\fB = new Chipcard::PCSC();\fR
.Sp
This method is equivalent to:
.Sp
.Vb 1
\& $hContext = new Chipcard::PCSC($Chipcard::PCSC::SCARD_SCOPE_SYSTEM, 0);
.Ve
.SH "CONSTRUCTION FAILURE"
.IX Header "CONSTRUCTION FAILURE"
Chipcard::PCSC constructors return an \f(CW\*(C`undef\*(C'\fR value when the object can
not be created. \f(CW$Chipcard::PCSC::errno\fR can be used to get more
information about the error.  (See section "ERROR HANDLING" below for
more information)
.SH "Chipcard::PCSC METHODS"
.IX Header "Chipcard::PCSC METHODS"
Here is a list of all the methods that can be used with a PCSC object.
.IP \(bu 4
\&\fBhContext\->ListReaders( \fR\f(CB$group\fR\fB );\fR
.Sp
This method returns the available readers in the given \f(CW$group\fR. If
omitted, \f(CW$group\fR defaults to a null value meaning "all groups". Please
note that as of this writing, \f(CW$group\fR can safely be omitted as it is
not used by PCSClite.
.Sp
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 \f(CW$Chipcard::PCSC::errno\fR 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:
.Sp
.Vb 3
\& $hContext = new Chipcard::PCSC();
\& die ("Can\*(Aqt create the PCSC object: $Chipcard::PCSC::errno\en")
\&        unless (defined $hContext);
\&
\& @ReadersList = $hContext\->ListReaders ();
\& die ("Can\*(Aqt get readers\*(Aq list: $Chipcard::PCSC::errno\en")
\&        unless (defined($ReadersList[0]));
\&
\& $, = "\en  ";
\& print @ReadersList . "\en";
.Ve
.IP \(bu 4
\&\fR\f(CB$hContext\fR\fB\->GetStatusChange(\e@readers_states, \fR\f(CB$timeout\fR\fB);\fR
.Sp
The method \f(CW\*(C`$hContext\->GetStatusChange(\e@readers_states, $timeout)\*(C'\fR
uses a reference to a list of hashes.
.Sp
.Vb 2
\& # create the list or readers to watch
\& map { push @readers_states, ({\*(Aqreader_name\*(Aq=>"$_"}) } @ReadersList;
\&
\& @StatusResult = $hContext\->GetStatusChange(\e@readers_states);
.Ve
.Sp
The keys of the hash are: 'reader_name', 'current_state', 'event_state'
and 'ATR'.
.Sp
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.
.Sp
.Vb 6
\& @StatusResult = $hContext\->GetStatusChange(\e@readers_states);
\& foreach $reader (@readers_states)
\& {
\&   $reader\->{current_state} = $reader\->{event_state};
\& }
\& @StatusResult = $hContext\->GetStatusChange(\e@readers_states);
.Ve
.IP \(bu 4
\&\fR\f(CB$hContext\fR\fB\->GetStatusChange(\e@readers_states);\fR
.Sp
This method is equivalent to:
.Sp
.Vb 1
\& $hContext\->GetStatusChange(\e@readers_states, 0xFFFFFFFF);
.Ve
.Sp
The timeout is set to infinite.
.IP \(bu 4
\&\fR\f(CB$apdu_ref\fR\fB = Chipcard::PCSC::ascii_to_array($apdu);\fR
.Sp
The method \f(CWChipcard::PCSC::Card::Transmit()\fR uses references to arrays
as in and out parameters. The \f(CWChipcard::PCSC::ascii_to_array()\fR is used
to transform an APDU in ASCII format to a reference to an array in the
good format.
.Sp
Example:
.Sp
.Vb 1
\& $SendData = Chipcard::PCSC::ascii_to_array("00 A4 01 00 02 01 00");
.Ve
.IP \(bu 4
\&\fR\f(CB$apdu\fR\fB = Chipcard::PCSC::array_to_ascii($apdu_ref);\fR
.Sp
This method is used to convert the result of a
\&\f(CWChipcard::PCSC::Card::Transmit()\fR into ASCII format.
.Sp
Example:
.Sp
.Vb 2
\& $RecvData = $hCard\->Transmit($SendData);
\& print Chipcard::PCSC::array_to_ascii($RecvData);
.Ve
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
All functions from PCSC objects save the return value in a global
variable called \f(CW$Chipcard::PCSC::errno\fR. This variable therefore holds
the latest status of PCSC.
.PP
It is a double-typed magical variable that behaves just like \f(CW$!\fR. 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...
.PP
Here is a small example of how to use it:
.PP
.Vb 3
\& $hContext = new Chipcard::PCSC();
\& die ("Can\*(Aqt create the PCSC object: $Chipcard::PCSC::errno\en")
\&     unless (defined $hContext);
.Ve
.PP
In case the last call was successful, \f(CW$Chipcard::PCSC::errno\fR contains
the \f(CW\*(C`SCARD_S_SUCCESS\*(C'\fR status. Here is a list of all possible error
codes.  They are defined as read-only variables with in the PCSC module:
.PP
.Vb 10
\& $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_SECURITY_VIOLATION
\& $Chipcard::PCSC::SCARD_W_UNPOWERED_CARD
\& $Chipcard::PCSC::SCARD_W_UNRESPONSIVE_CARD
\& $Chipcard::PCSC::SCARD_W_UNSUPPORTED_CARD
.Ve
.PP
PCSClite users will also be able to use the following (PCSClite
specific) codes:
.PP
.Vb 4
\& $Chipcard::PCSC::SCARD_INSERTED
\& $Chipcard::PCSC::SCARD_REMOVED
\& $Chipcard::PCSC::SCARD_RESET
\& $Chipcard::PCSC::SCARD_SCOPE_GLOBAL
.Ve
.PP
In addition, the wrapper defines:
.PP
.Vb 2
\& $Chipcard::PCSC::SCARD_P_ALREADY_CONNECTED
\& $Chipcard::PCSC::SCARD_P_NOT_CONNECTED
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fR\f(BIpcscd\fR\fI\|(1)\fR 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.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
(C) Lionel VICTOR & Ludovic ROUSSEAU, 2001\-2004, GNU GPL
(C) Ludovic ROUSSEAU, 2005\-2008, GNU GPL
.SH "AUTHORS / ACKNOWLEDGEMENT"
.IX Header "AUTHORS / ACKNOWLEDGEMENT"
.Vb 2
\& Lionel VICTOR <lionel.victor@unforgettable.com>
\&               <lionel.victor@free.fr>
\&
\& Ludovic ROUSSEAU <ludovic.rousseau@free.fr>
.Ve