This file is indexed.

/usr/lib/perl5/Chipcard/PCSC.pod is in libpcsc-perl 1.4.13-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