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

NAME

6       Chipcard::PCSC - Smart card reader interface library
7

SYNOPSIS

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

DESCRIPTION

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
26       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
30       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
34       A PCSC object uses the following property: "$pcsc_object->{hContext}"
35       the context returned by the pcsc library
36

CONSTRUCTORS

38       The following methods can be used to construct a PCSC object:
39
40       ·   $hContext = new Chipcard::PCSC($scope, $remote_host);
41
42           ·   $scope is the scope of the connection to the PC/SC daemon. It
43               can be any of the following:
44
45                $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
50           ·   $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
55       ·   $hContext = new Chipcard::PCSC($scope);
56
57           This method is equivalent to:
58
59            $hContext = new Chipcard::PCSC($scope, 0);
60
61       ·   $hContext = new Chipcard::PCSC();
62
63           This method is equivalent to:
64
65            $hContext = new Chipcard::PCSC($Chipcard::PCSC::SCARD_SCOPE_SYSTEM, 0);
66

CONSTRUCTION FAILURE

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

Chipcard::PCSC METHODS

74       Here is a list of all the methods that can be used with a PCSC object.
75
76       ·   hContext->ListReaders( $group );
77
78           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
83           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
90            $hContext = new Chipcard::PCSC();
91            die ("Can't create the PCSC object: $Chipcard::PCSC::errno\n")
92                   unless (defined $hContext);
93
94            @ReadersList = $hContext->ListReaders ();
95            die ("Can't get readers' list: $Chipcard::PCSC::errno\n")
96                   unless (defined($ReadersList[0]));
97
98            $, = "\n  ";
99            print @ReadersList . "\n";
100
101       ·   $hContext->GetStatusChange(\@readers_states, $timeout);
102
103           The method "$hContext->GetStatusChange(\@readers_states, $timeout)"
104           uses a reference to a list of hashes.
105
106            # create the list or readers to watch
107            map { push @readers_states, ({'reader_name'=>"$_"}) } @ReadersList;
108
109            @StatusResult = $hContext->GetStatusChange(\@readers_states);
110
111           The keys of the hash are: 'reader_name', 'current_state',
112           'event_state' and 'ATR'.
113
114           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
118            @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
125       ·   $hContext->GetStatusChange(\@readers_states);
126
127           This method is equivalent to:
128
129            $hContext->GetStatusChange(\@readers_states, 0xFFFFFFFF);
130
131           The timeout is set to infinite.
132
133       ·   $apdu_ref = Chipcard::PCSC::ascii_to_array($apdu);
134
135           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
140           Example:
141
142            $SendData = Chipcard::PCSC::ascii_to_array("00 A4 01 00 02 01 00");
143
144       ·   $apdu = Chipcard::PCSC::array_to_ascii($apdu_ref);
145
146           This method is used to convert the result of a
147           "Chipcard::PCSC::Card::Transmit()" into ASCII format.
148
149           Example:
150
151            $RecvData = $hCard->Transmit($SendData);
152            print Chipcard::PCSC::array_to_ascii($RecvData);
153

ERROR HANDLING

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
159       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
164       Here is a small example of how to use it:
165
166        $hContext = new Chipcard::PCSC();
167        die ("Can't create the PCSC object: $Chipcard::PCSC::errno\n")
168            unless (defined $hContext);
169
170       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
175        $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
203        $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
209       PCSClite users will also be able to use the following (PCSClite
210       specific) codes:
211
212        $Chipcard::PCSC::SCARD_INSERTED
213        $Chipcard::PCSC::SCARD_REMOVED
214        $Chipcard::PCSC::SCARD_RESET
215        $Chipcard::PCSC::SCARD_SCOPE_GLOBAL
216
217       In addition, the wrapper defines:
218
219        $Chipcard::PCSC::SCARD_P_ALREADY_CONNECTED
220        $Chipcard::PCSC::SCARD_P_NOT_CONNECTED
221

SEE ALSO

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

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.12.3                      2010-10-27                           PCSC(3)
Impressum