1PCSC(3) User Contributed Perl Documentation PCSC(3)
2
6 Chipcard::PCSC - Smart card reader interface library
7
9 my $hContext = new Chipcard::PCSC();
10 @ReadersList = $hContext->ListReaders ();
12 $hContext->GetStatusChange(\@readers_states, $timeout);
14 $apdu = Chipcard::PCSC::array_to_ascii(@apdu);
16 @apdu = Chipcard::PCSC::ascii_to_array($apdu);
18 $hContext = undef;
20
22 The PCSC module implements the Chipcard::PCSC class. Objects of this
23 class are used to communicate with the PCSC-lite daemon (see pcscd(1)
24 for more information).
25 PC/SC represents an abstraction layer to smart card readers. It
27 provides a communication layer with a wide variety of smart card
28 readers through a standardized API.
29 A PCSC object can be used to communicate with more than one reader
31 through Chipcard::PCSC::Card objects. Please read Chipcard::PCSC::Card
32 for extended information on how to talk to a smart card reader.
33 A PCSC object uses the following property: "$pcsc_object->{hContext}"
35 the context returned by the pcsc library
36
38 The following methods can be used to construct a PCSC object:
39 • $hContext = new Chipcard::PCSC($scope, $remote_host);
41 • $scope is the scope of the connection to the PC/SC daemon. It
43 can be any of the following:
44 $Chipcard::PCSC::SCARD_SCOPE_USER (not used by PCSClite);
46 $Chipcard::PCSC::SCARD_SCOPE_TERMINAL (not used by PCSClite);
47 $Chipcard::PCSC::SCARD_SCOPE_SYSTEM Services on the local machine;
48 $Chipcard::PCSC::SCARD_SCOPE_GLOBAL Services on a remote host.
49 • $remote_host is the host name of the remote machine to contact.
51 It is only used when $scope is equal to
52 $Chipcard::PCSC::SCARD_SCOPE_GLOBAL. A null value means
53 localhost.
54 • $hContext = new Chipcard::PCSC($scope);
56 This method is equivalent to:
58 $hContext = new Chipcard::PCSC($scope, 0);
60 • $hContext = new Chipcard::PCSC();
62 This method is equivalent to:
64 $hContext = new Chipcard::PCSC($Chipcard::PCSC::SCARD_SCOPE_SYSTEM, 0);
66
68 Chipcard::PCSC constructors return an "undef" value when the object can
69 not be created. $Chipcard::PCSC::errno can be used to get more
70 information about the error. (See section "ERROR HANDLING" below for
71 more information)
72
74 Here is a list of all the methods that can be used with a PCSC object.
75 • hContext->ListReaders( $group );
77 This method returns the available readers in the given $group. If
79 omitted, $group defaults to a null value meaning "all groups".
80 Please note that as of this writing, $group can safely be omitted
81 as it is not used by PCSClite.
82 The return value upon successful completion is an array of strings:
84 one string by available reader. If an error occurred, the undef
85 value is returned and $Chipcard::PCSC::errno should be used to get
86 more information about the error. (See section "ERROR HANDLING"
87 below for more information). The following example describes the
88 use of ListReaders:
89 $hContext = new Chipcard::PCSC();
91 die ("Can't create the PCSC object: $Chipcard::PCSC::errno\n")
92 unless (defined $hContext);
93 @ReadersList = $hContext->ListReaders ();
95 die ("Can't get readers' list: $Chipcard::PCSC::errno\n")
96 unless (defined($ReadersList[0]));
97 $, = "\n ";
99 print @ReadersList . "\n";
100 • $hContext->GetStatusChange(\@readers_states, $timeout);
102 The method "$hContext->GetStatusChange(\@readers_states, $timeout)"
104 uses a reference to a list of hashes.
105 # create the list or readers to watch
107 map { push @readers_states, ({'reader_name'=>"$_"}) } @ReadersList;
108 @StatusResult = $hContext->GetStatusChange(\@readers_states);
110 The keys of the hash are: 'reader_name', 'current_state',
112 'event_state' and 'ATR'.
113 To detect a status change you have to first get the status and then
115 copy the 'event_state' in the 'current_state'. The method will
116 return when both states are different or a timeout occurs.
117 @StatusResult = $hContext->GetStatusChange(\@readers_states);
119 foreach $reader (@readers_states)
120 {
121 $reader->{current_state} = $reader->{event_state};
122 }
123 @StatusResult = $hContext->GetStatusChange(\@readers_states);
124 • $hContext->GetStatusChange(\@readers_states);
126 This method is equivalent to:
128 $hContext->GetStatusChange(\@readers_states, 0xFFFFFFFF);
130 The timeout is set to infinite.
132 • $apdu_ref = Chipcard::PCSC::ascii_to_array($apdu);
134 The method Chipcard::PCSC::Card::Transmit() uses references to
136 arrays as in and out parameters. The
137 Chipcard::PCSC::ascii_to_array() is used to transform an APDU in
138 ASCII format to a reference to an array in the good format.
139 Example:
141 $SendData = Chipcard::PCSC::ascii_to_array("00 A4 01 00 02 01 00");
143 • $apdu = Chipcard::PCSC::array_to_ascii($apdu_ref);
145 This method is used to convert the result of a
147 Chipcard::PCSC::Card::Transmit() into ASCII format.
148 Example:
150 $RecvData = $hCard->Transmit($SendData);
152 print Chipcard::PCSC::array_to_ascii($RecvData);
153
155 All functions from PCSC objects save the return value in a global
156 variable called $Chipcard::PCSC::errno. This variable therefore holds
157 the latest status of PCSC.
158 It is a double-typed magical variable that behaves just like $!. This
160 means that it both holds a numerical value describing the error and the
161 corresponding string. The numerical value may change from a system to
162 another as it depends on the PCSC library...
163 Here is a small example of how to use it:
165 $hContext = new Chipcard::PCSC();
167 die ("Can't create the PCSC object: $Chipcard::PCSC::errno\n")
168 unless (defined $hContext);
169 In case the last call was successful, $Chipcard::PCSC::errno contains
171 the "SCARD_S_SUCCESS" status. Here is a list of all possible error
172 codes. They are defined as read-only variables with in the PCSC
173 module:
174 $Chipcard::PCSC::SCARD_S_SUCCESS
176 $Chipcard::PCSC::SCARD_E_CANCELLED
177 $Chipcard::PCSC::SCARD_E_CANT_DISPOSE
178 $Chipcard::PCSC::SCARD_E_CARD_UNSUPPORTED
179 $Chipcard::PCSC::SCARD_E_DUPLICATE_READER
180 $Chipcard::PCSC::SCARD_E_INSUFFICIENT_BUFFER
181 $Chipcard::PCSC::SCARD_E_INVALID_ATR
182 $Chipcard::PCSC::SCARD_E_INVALID_HANDLE
183 $Chipcard::PCSC::SCARD_E_INVALID_PARAMETER
184 $Chipcard::PCSC::SCARD_E_INVALID_TARGET
185 $Chipcard::PCSC::SCARD_E_INVALID_VALUE
186 $Chipcard::PCSC::SCARD_E_NO_MEMORY
187 $Chipcard::PCSC::SCARD_E_NO_SERVICE
188 $Chipcard::PCSC::SCARD_E_NO_SMARTCARD
189 $Chipcard::PCSC::SCARD_E_NOT_READY
190 $Chipcard::PCSC::SCARD_E_NOT_TRANSACTED
191 $Chipcard::PCSC::SCARD_E_PCI_TOO_SMALL
192 $Chipcard::PCSC::SCARD_E_PROTO_MISMATCH
193 $Chipcard::PCSC::SCARD_E_READER_UNAVAILABLE
194 $Chipcard::PCSC::SCARD_E_READER_UNSUPPORTED
195 $Chipcard::PCSC::SCARD_E_SERVICE_STOPPED
196 $Chipcard::PCSC::SCARD_E_SHARING_VIOLATION
197 $Chipcard::PCSC::SCARD_E_SYSTEM_CANCELLED
198 $Chipcard::PCSC::SCARD_E_TIMEOUT
199 $Chipcard::PCSC::SCARD_E_UNKNOWN_CARD
200 $Chipcard::PCSC::SCARD_E_UNKNOWN_READER
201 $Chipcard::PCSC::SCARD_E_UNSUPPORTED_FEATURE
202 $Chipcard::PCSC::SCARD_W_REMOVED_CARD
204 $Chipcard::PCSC::SCARD_W_RESET_CARD
205 $Chipcard::PCSC::SCARD_W_UNPOWERED_CARD
206 $Chipcard::PCSC::SCARD_W_UNRESPONSIVE_CARD
207 $Chipcard::PCSC::SCARD_W_UNSUPPORTED_CARD
208 PCSClite users will also be able to use the following (PCSClite
210 specific) codes:
211 $Chipcard::PCSC::SCARD_INSERTED
213 $Chipcard::PCSC::SCARD_REMOVED
214 $Chipcard::PCSC::SCARD_RESET
215 $Chipcard::PCSC::SCARD_SCOPE_GLOBAL
216 In addition, the wrapper defines:
218 $Chipcard::PCSC::SCARD_P_ALREADY_CONNECTED
220 $Chipcard::PCSC::SCARD_P_NOT_CONNECTED
221
223 pcscd(1) manpage has useful information about PC/SC lite.
224 Chipcard::PCSC::Card manpage gives information about how to communicate
225 with a reader and the smart card inside it.
226
228 (C) Lionel VICTOR & Ludovic ROUSSEAU, 2001-2004, GNU GPL (C) Ludovic
229 ROUSSEAU, 2005-2008, GNU GPL
230
232 Lionel VICTOR <lionel.victor@unforgettable.com>
233 <lionel.victor@free.fr>
234 Ludovic ROUSSEAU <ludovic.rousseau@free.fr>
236perl v5.36.0 2023-01-19 PCSC(3)