Chipcard::PCSC(3pm)

1PCSC(3)               User Contributed Perl Documentation              PCSC(3)
2
3
4

NAME

6       Chipcard::PCSC - Smarcard reader interface library
7

SYNOPSIS

9        my $hContext = new Chipcard::PCSC();
10
11        @ReadersList = $hContext->ListReaders ();
12
13        $hContext->SetTimeout($timeout);
14
15        $hContext->GetStatusChange(\@readers_states, $timeout);
16
17        $apdu = Chipcard::PCSC::array_to_ascii(@apdu);
18
19        @apdu = Chipcard::PCSC::ascii_to_array($apdu);
20
21        $hContext = undef;
22

DESCRIPTION

24       The PCSC module implements the Chipcard::PCSC class. Objects of this
25       class are used to communicate with the PCSC-lite daemon (see pcscd(1)
26       for more information).
27
28       PC/SC represents an abstraction layer to smartcard readers. It provides
29       a communication layer with a wide variety of smart card readers through
30       a standardized API.
31
32       A PCSC object can be used to communicate with more than one reader
33       through Chipcard::PCSC::Card objects. Please read Chipcard::PCSC::Card
34       for extended information on how to talk to a smart card reader.
35
36       A PCSC object uses the following property: "$pcsc_object->{hContext}"
37       the context returned by the pcsc library
38

CONSTRUCTORS

40       The following methods can be used to construct a PCSC object:
41
42       * $hContext = new Chipcard::PCSC($scope, $remote_host);
43           *   $scope is the scope of the connection to the PC/SC daemon. It
44               can be any of the following:
45
46                $Chipcard::PCSC::SCARD_SCOPE_USER     (not used by PCSClite);
47                $Chipcard::PCSC::SCARD_SCOPE_TERMINAL (not used by PCSClite);
48                $Chipcard::PCSC::SCARD_SCOPE_SYSTEM   Services on the local machine;
49                $Chipcard::PCSC::SCARD_SCOPE_GLOBAL   Services on a remote host.
50
51           *   $remote_host is the host name of the remote machine to contact.
52               It is only used when $scope is equal to $Chip‐
53               card::PCSC::SCARD_SCOPE_GLOBAL. A null value means localhost.
54
55       * $hContext = new Chipcard::PCSC($scope);
56           This method is equivalent to:
57
58            $hContext = new Chipcard::PCSC($scope, 0);
59
60       * $hContext = new Chipcard::PCSC();
61           This method is equivalent to:
62
63            $hContext = new Chipcard::PCSC($Chipcard::PCSC::SCARD_SCOPE_SYSTEM, 0);
64

CONSTRUCTION FAILURE

66       Chipcard::PCSC constructors return an "undef" value when the object can
67       not be created. $Chipcard::PCSC::errno can be used to get more informa‐
68       tion about the error.  (See section "ERROR HANDLING" below for more
69       information)
70

Chipcard::PCSC METHODS

72       Here is a list of all the methods that can be used with a PCSC object.
73
74       * hContext->ListReaders( $group );
75           This method returns the available readers in the given $group. If
76           ommited, $group defaults to a null value meaning "all groups".
77           Please note that as of this writing, $group can safely be ommited
78           as it is not used by PCSClite.
79
80           The return value upon succesful completion is an array of strings:
81           one string by available reader. If an error occured, the undef
82           value is returned and $Chipcard::PCSC::errno should be used to get
83           more informations about the error.  (See section "ERROR HANDLING"
84           below for more information). The following example describes the
85           use of ListReaders:
86
87            $hContext = new Chipcard::PCSC();
88            die ("Can't create the PCSC object: $Chipcard::PCSC::errno\n")
89                   unless (defined $hContext);
90
91            @ReadersList = $hContext->ListReaders ();
92            die ("Can't get readers' list: $Chipcard::PCSC::errno\n")
93                   unless (defined($ReadersList[0]));
94
95            $, = "\n  ";
96            print @ReadersList . "\n";
97
98       * $hContext->GetStatusChange(\@readers_states, $timeout);
99           The method "$hContext->GetStatusChange(\@readers_states, $timeout)"
100           uses a reference to a list of hashs.
101
102            # create the list or readers to watch
103            map { push @readers_states, ({'reader_name'=>"$_"}) } @ReadersList;
104
105            @StatusResult = $hContext->GetStatusChange(\@readers_states);
106
107           The keys of the hash are: 'reader_name', 'current_state',
108           'event_state' and 'ATR'.
109
110           To detect a status change you have to first get the status and then
111           copy the 'event_state' in the 'current_state'. The method will
112           return when both states are different or a timeout occurs.
113
114       * $hContext->GetStatusChange(\@readers_states);
115           This method is equivalent to:
116
117            $hContext->GetStatusChange(\@readers_states, 0xFFFFFFFF);
118
119           The timeout is set to infinite.
120
121       * $apdu_ref = Chipcard::PCSC::ascii_to_array($apdu);
122           The method "Chipcard::PCSC::Card::Transmit()" uses references to
123           arrays as in and out parameters. The "Chip‐
124           card::PCSC::ascii_to_array()" is used to transform an APDU in ASCII
125           format to a reference to an array in the good format.
126
127           Example:
128
129            $SendData = Chipcard::PCSC::ascii_to_array("00 A4 01 00 02 01 00");
130
131       * $apdu = Chipcard::PCSC::array_to_ascii($apdu_ref);
132           This method is used to convert the result of a "Chip‐
133           card::PCSC::Card::Transmit()" into ASCII format.
134
135           Example:
136
137            $RecvData = $hCard->Transmit($SendData);
138            print Chipcard::PCSC::array_to_ascii($RecvData);
139
140       * $hContext->SetTimeout( $timeout );
141           This method sets the working time that RPC uses when waiting for a
142           server.
143
144           It returns true upon successful exacution or false otherwise.
145
146           $timeout contains the new timeout value in seconds.
147
148       * $hContext->SetTimeout();
149           This function is equivalent to:
150
151            $hContext->SetTimeout(5);
152

ERROR HANDLING

154       All functions from PCSC objects save the return value in a global vari‐
155       able called $Chipcard::PCSC::errno. This variable therefore holds the
156       latest status of PCSC.
157
158       It is a double-typed magical variable that behaves just like $!. This
159       means that it both holds a numerical value describing the error and the
160       corresponding string.  The numerical value may change from a system to
161       another as it depends on the PCSC library...
162
163       Here is a small example of how to use it:
164
165        $hContext = new Chipcard::PCSC();
166        die ("Can't create the PCSC object: $Chipcard::PCSC::errno\n")
167            unless (defined $hContext);
168
169       In case the last call was successful, $Chipcard::PCSC::errno contains
170       the "SCARD_S_SUCCESS" status. Here is a list of all possible error
171       codes.  They are defined as read-only variables with in the PCSC mod‐
172       ule:
173
174        $Chipcard::PCSC::SCARD_S_SUCCESS
175        $Chipcard::PCSC::SCARD_E_CANCELLED
176        $Chipcard::PCSC::SCARD_E_CANT_DISPOSE
177        $Chipcard::PCSC::SCARD_E_INSUFFICIENT_BUFFER
178        $Chipcard::PCSC::SCARD_E_INVALID_ATR
179        $Chipcard::PCSC::SCARD_E_INVALID_HANDLE
180        $Chipcard::PCSC::SCARD_E_INVALID_PARAMETER
181        $Chipcard::PCSC::SCARD_E_INVALID_TARGET
182        $Chipcard::PCSC::SCARD_E_INVALID_VALUE
183        $Chipcard::PCSC::SCARD_E_NO_MEMORY
184        $Chipcard::PCSC::SCARD_E_UNKNOWN_READER
185        $Chipcard::PCSC::SCARD_E_TIMEOUT
186        $Chipcard::PCSC::SCARD_E_SHARING_VIOLATION
187        $Chipcard::PCSC::SCARD_E_NO_SMARTCARD
188        $Chipcard::PCSC::SCARD_E_UNKNOWN_CARD
189        $Chipcard::PCSC::SCARD_E_PROTO_MISMATCH
190        $Chipcard::PCSC::SCARD_E_NOT_READY
191        $Chipcard::PCSC::SCARD_E_SYSTEM_CANCELLED
192        $Chipcard::PCSC::SCARD_E_NOT_TRANSACTED
193        $Chipcard::PCSC::SCARD_E_READER_UNAVAILABLE
194        $Chipcard::PCSC::SCARD_E_PCI_TOO_SMALL
195        $Chipcard::PCSC::SCARD_E_READER_UNSUPPORTED
196        $Chipcard::PCSC::SCARD_E_DUPLICATE_READER
197        $Chipcard::PCSC::SCARD_E_CARD_UNSUPPORTED
198        $Chipcard::PCSC::SCARD_E_NO_SERVICE
199        $Chipcard::PCSC::SCARD_E_SERVICE_STOPPED
200
201        $Chipcard::PCSC::SCARD_W_UNSUPPORTED_CARD
202        $Chipcard::PCSC::SCARD_W_UNRESPONSIVE_CARD
203        $Chipcard::PCSC::SCARD_W_UNPOWERED_CARD
204        $Chipcard::PCSC::SCARD_W_RESET_CARD
205        $Chipcard::PCSC::SCARD_W_REMOVED_CARD
206        $Chipcard::PCSC::SCARD_W_INSERTED_CARD
207
208       PCSClite users will also be able to use the following (PCSClite spe‐
209       cific) codes:
210
211        $Chipcard::PCSC::SCARD_E_UNSUPPORTED_FEATURE
212        $Chipcard::PCSC::SCARD_W_INSERTED_CARD
213        $Chipcard::PCSC::SCARD_SCOPE_GLOBAL
214        $Chipcard::PCSC::SCARD_RESET
215        $Chipcard::PCSC::SCARD_INSERTED
216        $Chipcard::PCSC::SCARD_REMOVED
217
218       In addition, the wrapper defines:
219
220        $Chipcard::PCSC::SCARD_P_ALREADY_CONNECTED
221        $Chipcard::PCSC::SCARD_P_NOT_CONNECTED
222

COPYRIGHT

229       (C) Lionel VICTOR & Ludovic ROUSSEAU, 2001-2004, GNU GPL
230

AUTHORS / ACKNOWLEDGEMENT

232        Lionel VICTOR <lionel.victor@unforgettable.com>
233                      <lionel.victor@free.fr>
234
235        Ludovic ROUSSEAU <ludovic.rousseau@free.fr>
236
237
238
239perl v5.8.8                       2006-06-18                           PCSC(3)