.\" Automatically generated by Pod::Man 4.14 (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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 3pm"
.TH PCSC 3pm "2022-10-20" "perl v5.36.0" "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 \s-1PCSC\s0 module implements the Chipcard::PCSC class. Objects of this
class are used to communicate with the PCSC-lite daemon (see \fI\f(BIpcscd\fI\|(1)\fR
for more information).
.PP
\&\s-1PC/SC\s0 represents an abstraction layer to smart card readers. It provides
a communication layer with a wide variety of smart card readers through
a standardized \s-1API.\s0
.PP
A \s-1PCSC\s0 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 \s-1PCSC\s0 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 \s-1PCSC\s0 object:
.IP "\(bu" 4
\&\fB\f(CB$hContext\fB = new Chipcard::PCSC($scope, \f(CB$remote_host\fB);\fR
.RS 4
.IP "\(bu" 4
\&\f(CW$scope\fR is the scope of the connection to the \s-1PC/SC\s0 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
\&\fB\f(CB$hContext\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
\&\fB\f(CB$hContext\fB = new \fBChipcard::PCSC()\fB;\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 \*(L"\s-1ERROR HANDLING\*(R"\s0 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 \s-1PCSC\s0 object.
.IP "\(bu" 4
\&\fBhContext\->ListReaders( \f(CB$group\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 \*(L"all groups\*(R". 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 \*(L"\s-1ERROR HANDLING\*(R"\s0 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
\&\fB\f(CB$hContext\fB\->GetStatusChange(\e@readers_states, \f(CB$timeout\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 '\s-1ATR\s0'.
.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
\&\fB\f(CB$hContext\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
\&\fB\f(CB$apdu_ref\fB = Chipcard::PCSC::ascii_to_array($apdu);\fR
.Sp
The method \f(CW\*(C`Chipcard::PCSC::Card::Transmit()\*(C'\fR uses references to arrays
as in and out parameters. The \f(CW\*(C`Chipcard::PCSC::ascii_to_array()\*(C'\fR is used
to transform an \s-1APDU\s0 in \s-1ASCII\s0 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
\&\fB\f(CB$apdu\fB = Chipcard::PCSC::array_to_ascii($apdu_ref);\fR
.Sp
This method is used to convert the result of a
\&\f(CW\*(C`Chipcard::PCSC::Card::Transmit()\*(C'\fR into \s-1ASCII\s0 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 \s-1PCSC\s0 objects save the return value in a global
variable called \f(CW$Chipcard::PCSC::errno\fR. This variable therefore holds
the latest status of \s-1PCSC.\s0
.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 \s-1PCSC\s0 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 \s-1PCSC\s0 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_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"
\&\fI\f(BIpcscd\fI\|(1)\fR manpage has useful information about \s-1PC/SC\s0 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 \s-1VICTOR &\s0 Ludovic \s-1ROUSSEAU, 2001\-2004, GNU GPL\s0
(C) Ludovic \s-1ROUSSEAU, 2005\-2008, GNU GPL\s0
.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