/usr/lib/x86_64-linux-gnu/perl5/5.22/Chipcard/PCSC.pod is in libpcsc-perl 1.4.14-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 | =head1 NAME
Chipcard::PCSC - Smart card reader interface library
=head1 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;
=head1 DESCRIPTION
The PCSC module implements the Chipcard::PCSC class. Objects of this
class are used to communicate with the PCSC-lite daemon (see F<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
L<Chipcard::PCSC::Card> for extended information on how to talk to a
smart card reader.
A PCSC object uses the following property:
C<$pcsc_object-E<gt>{hContext}> the context returned by the pcsc library
=head1 CONSTRUCTORS
The following methods can be used to construct a PCSC object:
=over 4
=item *
B<$hContext = new Chipcard::PCSC($scope, $remote_host);>
=over 4
=item *
C<$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.
=item *
C<$remote_host> is the host name of the remote machine to contact. It is
only used when C<$scope> is equal to
C<$Chipcard::PCSC::SCARD_SCOPE_GLOBAL>. A null value means F<localhost>.
=back
=item *
B<$hContext = new Chipcard::PCSC($scope);>
This method is equivalent to:
$hContext = new Chipcard::PCSC($scope, 0);
=item *
B<$hContext = new Chipcard::PCSC();>
This method is equivalent to:
$hContext = new Chipcard::PCSC($Chipcard::PCSC::SCARD_SCOPE_SYSTEM, 0);
=back
=head1 CONSTRUCTION FAILURE
Chipcard::PCSC constructors return an C<undef> value when the object can
not be created. C<$Chipcard::PCSC::errno> can be used to get more
information about the error. (See section L<ERROR HANDLING> below for
more information)
=head1 Chipcard::PCSC METHODS
Here is a list of all the methods that can be used with a PCSC object.
=over 4
=item *
B<hContext-E<gt>ListReaders( $group );>
This method returns the available readers in the given C<$group>. If
omitted, C<$group> defaults to a null value meaning "all groups". Please
note that as of this writing, C<$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 C<$Chipcard::PCSC::errno> should be used to get more
information about the error. (See section L<ERROR HANDLING> below for
more information). The following example describes the use of
L<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";
=item *
B<$hContext-E<gt>GetStatusChange(\@readers_states, $timeout);>
The method C<$hContext-E<gt>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);
=item *
B<$hContext-E<gt>GetStatusChange(\@readers_states);>
This method is equivalent to:
$hContext->GetStatusChange(\@readers_states, 0xFFFFFFFF);
The timeout is set to infinite.
=item *
B<$apdu_ref = Chipcard::PCSC::ascii_to_array($apdu);>
The method C<Chipcard::PCSC::Card::Transmit()> uses references to arrays
as in and out parameters. The C<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");
=item *
B<$apdu = Chipcard::PCSC::array_to_ascii($apdu_ref);>
This method is used to convert the result of a
C<Chipcard::PCSC::Card::Transmit()> into ASCII format.
Example:
$RecvData = $hCard->Transmit($SendData);
print Chipcard::PCSC::array_to_ascii($RecvData);
=back
=head1 ERROR HANDLING
All functions from PCSC objects save the return value in a global
variable called C<$Chipcard::PCSC::errno>. This variable therefore holds
the latest status of PCSC.
It is a double-typed magical variable that behaves just like C<$!>. 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, C<$Chipcard::PCSC::errno> contains
the C<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
=head1 SEE ALSO
F<pcscd(1)> manpage has useful information about PC/SC lite.
L<Chipcard::PCSC::Card> manpage gives information about how to
communicate with a reader and the smart card inside it.
=head1 COPYRIGHT
(C) Lionel VICTOR & Ludovic ROUSSEAU, 2001-2004, GNU GPL
(C) Ludovic ROUSSEAU, 2005-2008, GNU GPL
=head1 AUTHORS / ACKNOWLEDGEMENT
Lionel VICTOR <lionel.victor@unforgettable.com>
<lionel.victor@free.fr>
Ludovic ROUSSEAU <ludovic.rousseau@free.fr>
=cut
|