« back to all changes in this revision
Viewing changes to doc/pcsc-lite.tex
- browse files at revision 2.1.1
- compare with another revision
- download diff
- download tarball
- view history from revision 2.1.1
- Committer: Bazaar Package Importer
- Author(s): Ludovic Rousseau
- Date: 2004-06-13 21:45:56 UTC
- mfrom: (1.1.1 upstream)
- mto: This revision was merged to the branch mainline in revision 3.
- Revision ID: james.westby@ubuntu.com-20040613214556-zio7hrzkz9wwtffx
Tags: 1.2.9-beta2-2
* debian/rules: add -lpthread to LDFLAGS so that pthread_* symbols are
included in the library (problem only seen on mips and mipsel).
Closes: #253629
* debian/control: make libpcsclite-dev and libpcsclite1 at Priority:
optional so that other packages at Priority: optional can use them.
Closes: #249374
included in the library (problem only seen on mips and mipsel).
Closes: #253629
* debian/control: make libpcsclite-dev and libpcsclite1 at Priority:
optional so that other packages at Priority: optional can use them.
Closes: #249374
- files added:
- ChangeLog.cvs
- aclocal
- doc/example
- win32
- files removed:
- build
- files modified:
- AUTHORS
added
removed
doc/pcsc-lite.tex
1
%
2
% MUSCLE Smart Card Development ( http://www.linuxnet.com )
3
%
4
% Copyright (C) 2004
5
% David Corcoran <corcoran@linuxnet.com>
6
% Ludovic Rousseau <ludovic.rousseau@free.fr>
7
%
8
% $Id: pcsc-lite.tex,v 1.1.1.1 2004/05/11 13:44:18 rousseau Exp $
9
10
\documentclass[a4paper,12pt]{article}
11
12
\usepackage{longtable}
13
\usepackage{url}
14
\usepackage{varioref}
15
16
% D�tection de pdflatex
17
\ifx\pdfcompresslevel\undefined
18
% Si on fait un postscript
19
\typeout{Postscript version}
20
\usepackage[dvips]{graphicx,rotating}
21
%\usepackage[dvips,matrix,line,curve,arrow,frame]{xy}
22
\DeclareGraphicsExtensions{.eps}
23
\else
24
% Si on fait un PDF
25
\typeout{PDF version}
26
\usepackage[pdftex]{graphicx,rotating}
27
%\usepackage[matrix,line,curve,arrow,frame]{xy}
28
\DeclareGraphicsExtensions{.jpg,.pdf}
29
\usepackage[pdftex]{hyperref}
30
\usepackage{ae,aeguill}
31
\fi
32
33
% smaller margins
34
\usepackage{fullpage}
35
36
% do not number subsubsection
37
\setcounter{tocdepth}{2}
38
\setcounter{secnumdepth}{2}
39
40
\newcommand{\synopsis}{\subsubsection{Synopsis:}}
41
\newcommand{\parameters}{\subsubsection{Parameters:}}
42
\newcommand{\desc}{\subsubsection{Description:}}
43
\newcommand{\example}{\subsubsection{Example:}}
44
\newcommand{\returns}{\subsubsection{Returns:}}
45
46
\title{MUSCLE PC/SC Lite API \\ Toolkit API Reference Documentation}
47
\author{David Corcoran \& Ludovic Rousseau\\
48
\url{corcoran@linuxnet.com}, \url{ludovic.rousseau@free.fr}}
49
\date{April 14, 2004}
50
51
52
\begin{document}
53
54
\maketitle
55
56
\begin{abstract}
57
This toolkit and documentation is provided on an \emph{as is} basis.
58
The authors shall not be held responsible for any mishaps caused by the
59
use of this software.
60
61
For more information please visit \url{http://www.musclecard.com/}.
62
63
\end{abstract}
64
65
% space between paragraphs
66
\parskip = 8pt
67
68
% remove paragraph indentation
69
\addtolength{\parindent}{-\parindent}
70
71
Document history: \\
72
\begin{tabular}{|l|l|l|}
73
\hline
74
0.8.7 & March 8, 2001 & latest PDF only version \\
75
\hline
76
0.9.0 & April 14, 2004 & reformat using \LaTeX{} and correct bugs \\
77
\hline
78
\end{tabular}
79
80
\newpage
81
\tableofcontents
82
\newpage
83
84
%---------%---------%---------%---------%---------%---------%---------
85
\section{Introduction/Overview}
86
87
This document contains the reference API calls for communicating to the
88
MUSCLE PC/SC Smart Card Resource Manager. PC/SC is a standard proposed by
89
the PC/SC workgroup \cite{pcsc_workgroup} which is a conglomerate of
90
representative from major smart card manufacturers and other companies.
91
This specification tries to abstract the smart card layer into a high
92
level API so that smart cards and their readers can be accessed in a
93
homogeneous fashion.
94
95
This toolkit was written in ANSI C that can be used with most compilers
96
and does NOT use complex and large data structures such as vectors,
97
\textit{etc}. The C API emulates the winscard API that is used on the
98
Windows platform. It is contained in the library \texttt{libpcsclite.so}
99
that is linked to your application.
100
101
I would really like to hear from you. If you have any feedback either on
102
this documentation or on the MUSCLE project please feel free to email me
103
at: \url{corcoran@musclecard.com}.
104
105
106
%---------%---------%---------%---------%---------%---------%---------
107
\section{Definitions}
108
109
110
%---------%---------%---------%---------%---------%---------
111
\subsection{Defined types}
112
113
The following is a list of commonly used type definitions in the
114
following API. These definitions and more can be found in the
115
\url{include/pcsclite.h} file.
116
117
{\tt
118
\begin{longtable}{|l|l|}
119
\hline
120
\textrm{PC/SC type} & \textrm{C type} \\
121
\hline
122
\hline
123
BOOL & short \\
124
BYTE & unsigned char \\
125
DWORD & unsigned long \\
126
LONG & long \\
127
LPBYTE & unsigned char * \\
128
LPCBYTE & const unsigned char * \\
129
LPCSTR & const char * \\
130
LPCVOID & const void * \\
131
LPCWSTR & char * \\
132
LPDWORD & unsigned long * \\
133
LPSCARDCONTEXT & unsigned long * \\
134
LPSCARDHANDLE & unsigned long * \\
135
LPSTR & char * \\
136
LPVOID & void * \\
137
PSCARDCONTEXT & unsigned long * \\
138
PSCARDHANDLE & unsigned long * \\
139
RESPONSECODE & long \\
140
SCARDCONTEXT & unsigned long \\
141
SCARDHANDLE & unsigned long \\
142
ULONG & unsigned long \\
143
USHORT & unsigned short \\
144
WORD & unsigned long \\
145
\hline
146
\end{longtable}
147
}
148
149
%---------%---------%---------%---------%---------%---------
150
\subsection{Error codes}
151
\label{Error codes}
152
153
The following is a list of commonly used errors. Since different
154
cards produce different errors they must map over to these error
155
messages.
156
157
{\tt
158
\begin{longtable}{|l|}
159
\hline
160
SCARD\_S\_SUCCESS \\
161
\hline
162
SCARD\_E\_CANCELLED \\
163
SCARD\_E\_CANT\_DISPOSE \\
164
SCARD\_E\_CARD\_UNSUPPORTED \\
165
SCARD\_E\_DUPLICATE\_READER \\
166
SCARD\_E\_INSUFFICIENT\_BUFFER \\
167
SCARD\_E\_INVALID\_ATR \\
168
SCARD\_E\_INVALID\_HANDLE \\
169
SCARD\_E\_INVALID\_PARAMETER \\
170
SCARD\_E\_INVALID\_TARGET \\
171
SCARD\_E\_INVALID\_VALUE \\
172
SCARD\_E\_NO\_MEMORY \\
173
SCARD\_E\_NO\_SERVICE \\
174
SCARD\_E\_NO\_SMARTCARD \\
175
SCARD\_E\_NOT\_READY \\
176
SCARD\_E\_NOT\_TRANSACTED \\
177
SCARD\_E\_PCI\_TOO\_SMALL \\
178
SCARD\_E\_PROTO\_MISMATCH \\
179
SCARD\_E\_READER\_UNAVAILABLE \\
180
SCARD\_E\_READER\_UNSUPPORTED \\
181
SCARD\_E\_SERVICE\_STOPPED \\
182
SCARD\_E\_SHARING\_VIOLATION \\
183
SCARD\_E\_SYSTEM\_CANCELLED \\
184
SCARD\_E\_TIMEOUT \\
185
SCARD\_E\_UNKNOWN\_CARD \\
186
SCARD\_E\_UNKNOWN\_READER \\
187
SCARD\_F\_COMM\_ERROR \\
188
SCARD\_F\_INTERNAL\_ERROR \\
189
SCARD\_F\_UNKNOWN\_ERROR \\
190
SCARD\_F\_WAITED\_TOO\_LONG \\
191
\hline
192
SCARD\_W\_UNSUPPORTED\_CARD \\
193
SCARD\_W\_UNRESPONSIVE\_CARD \\
194
SCARD\_W\_UNPOWERED\_CARD \\
195
SCARD\_W\_RESET\_CARD \\
196
SCARD\_W\_REMOVED\_CARD \\
197
\hline
198
\end{longtable}
199
}
200
201
202
%---------%---------%---------%---------%---------%---------%---------
203
\section{API Routines}
204
205
These routines specified here are winscard routines like those in the
206
winscard API provided under Windows{\textregistered}. These are
207
compatible with the Microsoft{\textregistered} API calls. This list of
208
calls is mainly an abstraction of readers. It gives a common API for
209
communication to most readers in a homogeneous fashion.
210
211
Since all functions can produce a wide array of errors, please refer to
212
\S~\vref{Error codes} for a list of error returns.
213
214
For a human readable representation of an error the function
215
\url{pcsc_stringify_error()} is declared in \texttt{pcsclite.h}.
216
This function is not available on Microsoft{\textregistered} winscard
217
API and is pcsc-lite specific.
218
219
220
%---------%---------%---------%---------%---------%---------
221
\subsection{SCardEstablishContext}
222
223
\synopsis
224
\begin{verbatim}
225
#include <winscard.h>
226
227
LONG SCardEstablishContext(DWORD dwScope,
228
LPCVOID pvReserved1,
229
LPCVOID pvReserved2,
230
LPSCARDCONTEXT phContext);
231
\end{verbatim}
232
233
\parameters
234
235
\begin{tabular}{lll}
236
\texttt{dwScope} & IN & Scope of the establishment \\
237
& & This can either be a local or remote connection\\
238
239
\texttt{pvReserved1} & IN & Reserved for future use. Can be used for remote
240
connection \\
241
242
\texttt{pvReserved2} & IN & Reserved for future use \\
243
\texttt{phContext} & OUT & Returned reference to this connection \\
244
\end{tabular}
245
246
\desc
247
248
This function creates a communication context to the PC/SC Resource
249
Manager. This must be the first function called in a PC/SC application.
250
251
\begin{tabular}{|l|l|}
252
\hline
253
Value of \texttt{dwScope} & Meaning\\
254
\hline
255
\hline
256
\texttt{SCARD\_SCOPE\_USER} & Not used\\
257
\hline
258
\texttt{SCARD\_SCOPE\_TERMINAL} & Not used\\
259
\hline
260
\texttt{SCARD\_SCOPE\_GLOBAL} & Not used\\
261
\hline
262
\texttt{SCARD\_SCOPE\_SYSTEM} & Services on the local machine\\
263
\hline
264
\end{tabular}
265
266
% Note: If \texttt{SCARD\_SCOPE\_GLOBAL} is used then \texttt{pvReserved1}
267
% is a string that is the hostname of the machine which the Resource
268
% Manager services reside. If \texttt{NULL} is specified then it defaults
269
% to the localhost.
270
271
\example
272
\begin{verbatim}
273
SCARDCONTEXT hContext;
274
LONG rv;
275
276
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
277
\end{verbatim}
278
279
\returns
280
281
\begin{tabular}{ll}
282
\texttt{SCARD\_S\_SUCCESS} & Successful\\
283
\texttt{SCARD\_E\_INVALID\_VALUE} & Invalid scope type passed
284
\end{tabular}
285
286
287
%---------%---------%---------%---------%---------%---------
288
\subsection{SCardReleaseContext}
289
290
\synopsis
291
\begin{verbatim}
292
#include <winscard.h>
293
294
LONG SCardReleaseContext(SCARDCONTEXT hContext);
295
\end{verbatim}
296
297
\parameters
298
299
\begin{tabular}{lll}
300
\texttt{hContext} & IN & Connection context to be closed
301
\end{tabular}
302
303
\desc
304
305
This function destroys a communication context to the PC/SC Resource
306
Manager. This must be the last function called in a PC/SC application.
307
308
\example
309
\begin{verbatim}
310
SCARDCONTEXT hContext;
311
LONG rv;
312
313
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
314
rv = SCardReleaseContext(hContext);
315
\end{verbatim}
316
317
\returns
318
319
\begin{tabular}{ll}
320
\texttt{SCARD\_S\_SUCCESS} & Successful\\
321
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hContext} handle
322
\end{tabular}
323
324
325
%---------%---------%---------%---------%---------%---------
326
\subsection{SCardListReaders}
327
328
\synopsis
329
\begin{verbatim}
330
#include <winscard.h>
331
332
LONG SCardListReaders(SCARDCONTEXT hContext,
333
LPCSTR mszGroups,
334
LPSTR mszReaders,
335
LPDWORD pcchReaders);
336
\end{verbatim}
337
338
\parameters
339
340
\begin{tabular}{lll}
341
\texttt{hContext} & IN & Connection context to the PC/SC Resource Manager\\
342
\texttt{mszGroups} & IN & List of groups to list readers (not used)\\
343
\texttt{mszReaders} & OUT & Multi-string with list of readers\\
344
\texttt{pcchReaders} & INOUT & Size of multi-string buffer including NULL's
345
\end{tabular}
346
347
\desc
348
349
This function returns a list of currently available readers on the
350
system. \texttt{mszReaders} is a pointer to a character string that is
351
allocated by the application. If the application sends
352
\texttt{mszGroups} and \texttt{mszReaders} as \texttt{NULL} then this
353
function will return the size of the buffer needed to allocate in
354
\texttt{pcchReaders}.
355
356
The reader names is a multi-string and separated by a nul character
357
(\verb+'\0'+) and ended by a double nul character.
358
\verb+"Reader A\0Reader B\0\0"+.
359
360
\example
361
\begin{verbatim}
362
SCARDCONTEXT hContext;
363
LPSTR mszReaders;
364
DWORD dwReaders;
365
LONG rv;
366
367
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
368
rv = SCardListReaders(hContext, NULL, NULL, &dwReaders);
369
mszReaders = (LPSTR)malloc(sizeof(char)*dwReaders);
370
rv = SCardListReaders(hContext, NULL, mszReaders, &dwReaders);
371
\end{verbatim}
372
373
\returns
374
375
\begin{tabular}{ll}
376
\texttt{SCARD\_S\_SUCCESS} & Successful \\
377
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid Scope Handle\\
378
\texttt{SCARD\_E\_INSUFFICIENT\_BUFFER} & Reader buffer not large enough
379
\end{tabular}
380
381
382
%---------%---------%---------%---------%---------%---------
383
\subsection{SCardListReaderGroups}
384
385
\synopsis
386
\begin{verbatim}
387
#include <winscard.h>
388
389
LONG SCardListReaderGroups(SCARDCONTEXT hContext,
390
LPSTR mszGroups,
391
LPDWORD pcchGroups);
392
\end{verbatim}
393
394
\parameters
395
396
\begin{tabular}{lll}
397
\texttt{hContext} & IN & Connection context to the PC/SC Resource Manager\\
398
\texttt{mszGroups} & OUT & List of groups to list readers\\
399
\texttt{pcchGroups} & INOUT & Size of multi-string buffer including NULL's
400
\end{tabular}
401
402
\desc
403
404
This function returns a list of currently available reader groups on the
405
system. \texttt{mszGroups} is a pointer to a character string that is
406
allocated by the application. If the application sends
407
\texttt{mszGroups} as \texttt{NULL} then this function will return the
408
size of the buffer needed to allocate in \texttt{pcchGroups}.
409
410
The group names is a multi-string and separated by a nul character
411
(\verb+'\0'+) and ended by a double nul character.
412
\verb+"SCard$DefaultReaders\0Group 2\0\0"+.
413
414
\example
415
\begin{verbatim}
416
SCARDCONTEXT hContext;
417
LPSTR mszGroups;
418
DWORD dwGroups;
419
LONG rv;
420
421
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
422
rv = SCardListReaderGroups(hContext, NULL, &dwGroups);
423
mszGroups = (LPSTR)malloc(sizeof(char)*dwGroups);
424
rv = SCardListReaderGroups(hContext, mszGroups, &dwGroups);
425
\end{verbatim}
426
427
\returns
428
429
\begin{tabular}{ll}
430
\texttt{SCARD\_S\_SUCCESS} & Successful \\
431
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid Scope Handle\\
432
\texttt{SCARD\_E\_INSUFFICIENT\_BUFFER} & Reader buffer not large enough
433
\end{tabular}
434
435
436
%---------%---------%---------%---------%---------%---------
437
\subsection{SCardConnect}
438
439
\synopsis
440
\begin{verbatim}
441
#include <winscard.h>
442
443
LONG SCardConnect(SCARDCONTEXT hContext,
444
LPCSTR szReader,
445
DWORD dwShareMode,
446
DWORD dwPreferredProtocols,
447
LPSCARDHANDLE phCard,
448
LPDWORD pdwActiveProtocol);
449
\end{verbatim}
450
451
\parameters
452
453
\begin{tabular}{lll}
454
\texttt{hContext} & IN & Connection context to the PC/SC Resource Manager\\
455
\texttt{szReader} & IN & Reader name to connect to\\
456
\texttt{dwShareMode} & IN & Mode of connection type: exclusive or shared\\
457
\texttt{dwPreferredProtocols} & IN & Desired protocol use\\
458
\texttt{phCard} & OUT & Handle to this connection\\
459
\texttt{pdwActiveProtocol} & OUT & Established protocol to this connection.
460
\end{tabular}
461
462
\desc
463
464
This function establishes a connection to the friendly name of
465
the reader specified in \texttt{szReader}. The first connection will
466
power up and perform a reset on the card.
467
468
\begin{tabular}{|l|l|}
469
\hline
470
Value of \texttt{dwScope} & Meaning\\
471
\hline
472
\hline
473
\texttt{SCARD\_SHARE\_SHARED} & This application will allow others to share the reader \\
474
\hline
475
\texttt{SCARD\_SHARE\_EXCLUSIVE} & This application will NOT allow
476
others to share the reader \\
477
\hline
478
\texttt{SCARD\_SHARE\_DIRECT} & not used \\
479
\hline
480
\end{tabular}
481
482
483
\begin{tabular}{|l|l|}
484
\hline
485
Value of \texttt{dwPreferredProtocols} & Meaning \\
486
\hline
487
\hline
488
\texttt{SCARD\_PROTOCOL\_T0} & Use the T=0 protocol \\
489
\hline
490
\texttt{SCARD\_PROTOCOL\_T1} & Use the T=1 protocol \\
491
\hline
492
\texttt{SCARD\_PROTOCOL\_RAW} & Use with memory type cards \\
493
\hline
494
\end{tabular}
495
496
497
\example
498
499
\begin{verbatim}
500
SCARDCONTEXT hContext;
501
SCARDHANDLE hCard;
502
DWORD dwActiveProtocol;
503
LONG rv;
504
505
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
506
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
507
SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
508
\end{verbatim}
509
510
\returns
511
512
\begin{tabular}{ll}
513
\texttt{SCARD\_S\_SUCCESS} & Successful\\
514
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hContext} handle\\
515
\texttt{SCARD\_E\_INVALID\_VALUE} & Invalid sharing mode, requested protocol, or reader name\\
516
\texttt{SCARD\_E\_NOT\_READY} & Could not allocate the desired port\\
517
\texttt{SCARD\_E\_READER\_UNAVAILABLE} & Could not power up the reader or card\\
518
\texttt{SCARD\_E\_SHARING\_VIOLATION} & Someone else has exclusive rights\\
519
\texttt{SCARD\_E\_UNSUPPORTED\_FEATURE} & Protocol not supported\\
520
\end{tabular}
521
522
523
%---------%---------%---------%---------%---------%---------
524
\subsection{SCardReconnect}
525
526
\synopsis
527
528
\begin{verbatim}
529
#include <winscard.h>
530
531
LONG SCardReconnect(SCARDHANDLE hCard,
532
DWORD dwShareMode,
533
DWORD dwPreferredProtocols,
534
DWORD dwInitialization,
535
LPDWORD pdwActiveProtocol);
536
\end{verbatim}
537
538
\parameters
539
540
\begin{tabular}{lll}
541
\texttt{hCard} & IN & Handle to a previous call to connect\\
542
\texttt{dwShareMode} & IN & Mode of connection type: exclusive/shared\\
543
\texttt{dwPreferredProtocols} & IN & Desired protocol use\\
544
\texttt{dwInitialization} & IN & Desired action taken on the card/reader\\
545
\texttt{pdwActiveProtocol} & OUT & Established protocol to this connection\\
546
\end{tabular}
547
548
\desc
549
550
This function reestablishes a connection to a reader that was previously
551
connected to using \texttt{SCardConnect()}. In a multi application
552
environment it is possible for an application to reset the card in
553
shared mode. When this occurs any other application trying to access
554
certain commands will be returned the value
555
\texttt{SCARD\_W\_RESET\_CARD}. When this occurs
556
\texttt{SCardReconnect()} must be called in order to acknowledge that
557
the card was reset and allow it to change it's state accordingly.
558
559
560
\begin{tabular}{|l|l|}
561
\hline
562
Value of \texttt{dwShareMode} & Meaning \\
563
\hline
564
\hline
565
\texttt{SCARD\_SHARE\_SHARED} & This application will allow others to share the
566
reader\\
567
\hline
568
\texttt{SCARD\_SHARE\_EXCLUSIVE} & This application will NOT allow others to
569
share the reader\\
570
\hline
571
\end{tabular}
572
573
\begin{tabular}{|l|l|}
574
\hline
575
Value of \texttt{dwPreferredProtocols} & Meaning \\
576
\hline
577
\hline
578
\texttt{SCARD\_PROTOCOL\_T0} & Use the T=0 protocol \\
579
\hline
580
\texttt{SCARD\_PROTOCOL\_T1} & Use the T=1 protocol \\
581
\hline
582
\texttt{SCARD\_PROTOCOL\_RAW} & Use with memory type cards \\
583
\hline
584
\end{tabular}
585
586
\begin{tabular}{|l|l|}
587
\hline
588
Value of \texttt{dwInitialization} & Meaning \\
589
\hline
590
\hline
591
\texttt{SCARD\_LEAVE\_CARD} & Do nothing \\
592
\hline
593
\texttt{SCARD\_RESET\_CARD} & Reset the card (warm reset) \\
594
\hline
595
\texttt{SCARD\_UNPOWER\_CARD} & Unpower the card (cold reset) \\
596
\hline
597
\texttt{SCARD\_EJECT\_CARD} & Eject the card \\
598
\hline
599
\end{tabular}
600
601
602
\example
603
604
\begin{verbatim}
605
SCARDCONTEXT hContext;
606
SCARDHANDLE hCard;
607
DWORD dwActiveProtocol, dwSendLength, dwRecvLength;
608
LONG rv;
609
BYTE pbRecvBuffer[10];
610
BYTE pbSendBuffer[] = {0xC0, 0xA4, 0x00, 0x00, 0x02, 0x3F, 0x00};
611
612
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
613
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
614
SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
615
dwSendLength = sizeof(pbSendBuffer);
616
dwRecvLength = sizeof(pbRecvBuffer);
617
rv = SCardTransmit(hCard, SCARD_PCI_T0, pbSendBuffer, dwSendLength,
618
&pioRecvPci, pbRecvBuffer, &dwRecvLength);
619
620
/* Card has been reset by another application */
621
if (rv == SCARD_W_RESET_CARD)
622
{
623
rv = SCardReconnect(hCard, SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0,
624
SCARD_RESET_CARD, &dwActiveProtocol);
625
}
626
\end{verbatim}
627
628
629
\returns
630
631
\begin{tabular}{ll}
632
\texttt{SCARD\_S\_SUCCESS} & Successful\\
633
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hCard} handle\\
634
\texttt{SCARD\_E\_NOT\_READY} & Could not allocate the desired port\\
635
\texttt{SCARD\_E\_INVALID\_VALUE} & Invalid sharing mode, requested protocol, or reader name\\
636
\texttt{SCARD\_E\_READER\_UNAVAILABLE} & The reader has been removed\\
637
\texttt{SCARD\_E\_UNSUPPORTED\_FEATURE} & Protocol not supported\\
638
\texttt{SCARD\_E\_SHARING\_VIOLATION} & Someone else has exclusive rights\\
639
\end{tabular}
640
641
642
%---------%---------%---------%---------%---------%---------
643
\subsection{SCardDisconnect}
644
645
\synopsis
646
647
\begin{verbatim}
648
#include <winscard.h>
649
650
LONG SCardDisconnect(SCARDHANDLE hCard, DWORD dwDisposition);
651
\end{verbatim}
652
653
\parameters
654
655
\begin{tabular}{lll}
656
\texttt{hCard} & IN & Connection made from \texttt{SCardConnect} \\
657
\texttt{dwDisposition} & IN & Reader function to execute \\
658
\end{tabular}
659
660
\desc
661
662
This function terminates a connection to the connection made through
663
SCardConnect. dwDisposition can have the following values:
664
665
\begin{tabular}{|l|l|}
666
\hline
667
Value of \texttt{dwDisposition} & Meaning \\
668
\hline
669
\hline
670
\texttt{SCARD\_LEAVE\_CARD} & Do nothing\\
671
\texttt{SCARD\_RESET\_CARD} & Reset the card (warm reset) \\
672
\texttt{SCARD\_UNPOWER\_CARD} & Unpower the card (cold reset) \\
673
\texttt{SCARD\_EJECT\_CARD} & Eject the card\\
674
\hline
675
\end{tabular}
676
677
\example
678
\begin{verbatim}
679
SCARDCONTEXT hContext;
680
SCARDHANDLE hCard;
681
DWORD dwActiveProtocol;
682
LONG rv;
683
684
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
685
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
686
SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
687
rv = SCardDisconnect(hCard, SCARD_UNPOWER_CARD);
688
\end{verbatim}
689
690
\returns
691
692
\begin{tabular}{ll}
693
\texttt{SCARD\_S\_SUCCESS} & Successful \\
694
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hCard} handle \\
695
\texttt{SCARD\_E\_INVALID\_VALUE} & Invalid \texttt{dwDisposition} \\
696
\end{tabular}
697
698
699
%---------%---------%---------%---------%---------%---------
700
\subsection{SCardBeginTransaction}
701
702
\synopsis
703
\begin{verbatim}
704
#include <winscard.h>
705
706
LONG SCardBeginTransaction(SCARDHANDLE hCard);
707
\end{verbatim}
708
709
\parameters
710
711
\begin{tabular}{lll}
712
\texttt{hCard} & IN & Connection made from \texttt{SCardConnect} \\
713
\end{tabular}
714
715
\desc
716
717
This function establishes a temporary exclusive access mode for doing a
718
series of commands or transaction. You might want to use this when you
719
are selecting a few files and then writing a large file so you can make
720
sure that another application will not change the current file. If
721
another application has a lock on this reader or this application is in
722
\texttt{SCARD\_SHARE\_EXCLUSIVE} there will be no action taken.
723
724
\example
725
726
\begin{verbatim}
727
SCARDCONTEXT hContext;
728
SCARDHANDLE hCard;
729
DWORD dwActiveProtocol;
730
LONG rv;
731
732
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
733
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
734
SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
735
rv = SCardBeginTransaction(hCard);
736
737
/* Do some transmit commands */
738
\end{verbatim}
739
740
\returns
741
742
\begin{tabular}{ll}
743
\texttt{SCARD\_S\_SUCCESS} & Successful\\
744
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hCard} handle\\
745
\texttt{SCARD\_E\_SHARING\_VIOLATION} & Someone else has exclusive rights\\
746
\texttt{SCARD\_E\_READER\_UNAVAILABLE} & The reader has been removed\\
747
\end{tabular}
748
749
750
%---------%---------%---------%---------%---------%---------
751
\subsection{SCardEndTransaction}
752
753
\synopsis
754
755
\begin{verbatim}
756
#include <winscard.h>
757
758
LONG SCardEndTransaction(SCARDHANDLE hCard,
759
DWORD dwDisposition);
760
\end{verbatim}
761
762
\parameters
763
764
\begin{tabular}{lll}
765
\texttt{hCard} & IN & Connection made from \texttt{SCardConnect}\\
766
\texttt{dwDisposition} & IN & Action to be taken on the reader\\
767
\end{tabular}
768
769
\desc
770
771
This function ends a previously begun transaction. The calling
772
application must be the owner of the previously begun transaction or an
773
error will occur. \texttt{dwDisposition} can have the following values:
774
The disposition action is not currently used in this release.
775
776
\begin{tabular}{|l|l|}
777
\hline
778
Value of dwDisposition & Meaning \\
779
\hline
780
\hline
781
\texttt{SCARD\_LEAVE\_CARD} & Do nothing\\
782
\texttt{SCARD\_RESET\_CARD} & Reset the card\\
783
\texttt{SCARD\_UNPOWER\_CARD} & Unpower the card\\
784
\texttt{SCARD\_EJECT\_CARD} & Eject the card\\
785
\hline
786
\end{tabular}
787
788
789
\example
790
791
\begin{verbatim}
792
SCARDCONTEXT hContext;
793
SCARDHANDLE hCard;
794
DWORD dwActiveProtocol;
795
LONG rv;
796
797
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
798
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
799
SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
800
rv = SCardBeginTransaction(hCard);
801
802
/* Do some transmit commands */
803
804
rv = SCardEndTransaction(hCard, SCARD_LEAVE_CARD);
805
\end{verbatim}
806
807
\returns
808
809
\begin{tabular}{ll}
810
\texttt{SCARD\_S\_SUCCESS} & Successful\\
811
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hCard} handle\\
812
\texttt{SCARD\_E\_SHARING\_VIOLATION} & Someone else has exclusive rights\\
813
\texttt{SCARD\_E\_READER\_UNAVAILABLE} & The reader has been removed\\
814
\end{tabular}
815
816
817
%---------%---------%---------%---------%---------%---------
818
\subsection{SCardTransmit}
819
820
\synopsis
821
822
\begin{verbatim}
823
#include <winscard.h>
824
825
LONG SCardTransmit(SCARDHANDLE hCard,
826
LPCSCARD_IO_REQUEST pioSendPci,
827
LPCBYTE pbSendBuffer,
828
DWORD cbSendLength,
829
LPSCARD_IO_REQUEST pioRecvPci,
830
LPBYTE pbRecvBuffer,
831
LPDWORD pcbRecvLength);
832
\end{verbatim}
833
834
\parameters
835
836
\begin{tabular}{lll}
837
\texttt{hCard} & IN & Connection made from \texttt{SCardConnect} \\
838
\texttt{pioSendPci} & INOUT & Structure of protocol information\\
839
\texttt{pbSendBuffer} & IN & APDU to send to the card\\
840
\texttt{cbSendLength} & IN & Length of the APDU\\
841
\texttt{pioRecvPci} & INOUT & Structure of protocol information\\
842
\texttt{pbRecvBuffer} & OUT & Response from the card\\
843
\texttt{pcbRecvLength} & INOUT & Length of the response\\
844
\end{tabular}
845
846
\desc
847
848
This function sends an APDU to the smart card contained in the reader
849
connected to by \texttt{SCardConnect()}. The card responds from the
850
APDU and stores this response in \texttt{pbRecvBuffer} and it's length
851
in \texttt{SpcbRecvLength}. \texttt{SSendPci} and \texttt{SRecvPci} are
852
structures containing the following:
853
854
\begin{verbatim}
855
typedef struct {
856
DWORD dwProtocol; /* SCARD_PROTOCOL_T0 or SCARD_PROTOCOL_T1 */
857
DWORD cbPciLength; /* Length of this structure - not used */
858
} SCARD_IO_REQUEST;
859
\end{verbatim}
860
861
\begin{tabular}{|l|l|}
862
\hline
863
Value of \texttt{pioSendPci} & Meaning \\
864
\hline
865
\hline
866
\texttt{SCARD\_PCI\_T0} & Pre defined T=0 PCI structure\\
867
\texttt{SCARD\_PCI\_T1} & Pre defined T=1 PCI structure\\
868
\hline
869
\end{tabular}
870
871
\example
872
873
\begin{verbatim}
874
LONG rv;
875
SCARDCONTEXT hContext;
876
SCARDHANDLE hCard;
877
DWORD dwActiveProtocol, dwSendLength, dwRecvLength;
878
SCARD_IO_REQUEST pioRecvPci;
879
BYTE pbRecvBuffer[10];
880
BYTE pbSendBuffer[] = { 0xC0, 0xA4, 0x00, 0x00, 0x02, 0x3F, 0x00 };
881
882
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
883
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
884
SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
885
dwSendLength = sizeof(pbSendBuffer);
886
dwRecvLength = sizeof(pbRecvBuffer);
887
rv = SCardTransmit(hCard, SCARD_PCI_T0, pbSendBuffer, dwSendLength,
888
&pioRecvPci, pbRecvBuffer, &dwRecvLength);
889
\end{verbatim}
890
891
\returns
892
893
\begin{tabular}{ll}
894
\texttt{SCARD\_S\_SUCCESS} & Successful\\
895
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hCard} handle\\
896
\texttt{SCARD\_E\_NOT\_TRANSACTED} & APDU exchange not successful\\
897
\texttt{SCARD\_E\_PROTO\_MISMATCH} & Connect protocol is different than desired\\
898
\texttt{SCARD\_E\_INVALID\_VALUE} & Invalid Protocol, reader name, etc\\
899
\texttt{SCARD\_E\_READER\_UNAVAILABLE} & The reader has been removed\\
900
\texttt{SCARD\_W\_RESET\_CARD} & The card has been reset by another application\\
901
\texttt{SCARD\_W\_REMOVED\_CARD} & The card has been removed from the reader\\
902
\end{tabular}
903
904
905
%---------%---------%---------%---------%---------%---------
906
\subsection{SCardControl}
907
908
\synopsis
909
910
\begin{verbatim}
911
#include <winscard.h>
912
913
LONG SCardControl(SCARDHANDLE hCard,
914
DWORD dwControlCode,
915
LPCBYTE pbSendBuffer,
916
DWORD cbSendLength,
917
LPBYTE pbRecvBuffer,
918
DWORD pcbRecvLength,
919
LPDWORD lpBytesReturned);
920
\end{verbatim}
921
922
\parameters
923
924
\begin{tabular}{lll}
925
\texttt{hCard} & IN & Connection made from \texttt{SCardConnect}\\
926
\texttt{dwControlCode} & IN & Control code for the operation \\
927
\texttt{pbSendBuffer} & IN & Command to send to the reader\\
928
\texttt{cbSendLength} & IN & Length of the command\\
929
\texttt{pbRecvBuffer} & OUT & Response from the reader\\
930
\texttt{pcbRecvLength} & IN & Length of the response buffer\\
931
\texttt{lpBytesReturned} & OUT & Length of the response\\
932
\end{tabular}
933
934
\desc
935
936
This function sends a command directly to the IFD Handler to be
937
processed by the reader. This is useful for creating client side reader
938
drivers for functions like PIN pads, biometrics, or other extensions to
939
the normal smart card reader that are not normally handled by PC/SC.
940
941
Note: the API of this function changed. In pcsc-lite 1.2.0 and before
942
the API was not Windows{\textregistered} PC/SC compatible. This has been
943
corrected.
944
945
\example
946
947
\begin{verbatim}
948
LONG rv;
949
SCARDCONTEXT hContext;
950
SCARDHANDLE hCard;
951
DWORD dwActiveProtocol, dwSendLength, dwRecvLength;
952
BYTE pbRecvBuffer[10];
953
BYTE pbSendBuffer[] = { 0x06, 0x00, 0x0A, 0x01, 0x01, 0x10 0x00 };
954
955
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
956
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
957
SCARD_PROTOCOL_RAW &hCard, &dwActiveProtocol);
958
dwSendLength = sizeof(pbSendBuffer);
959
dwRecvLength = sizeof(pbRecvBuffer);
960
rv = SCardControl(hCard, 0x42000001, pbSendBuffer, dwSendLength,
961
pbRecvBuffer, sizeof(pbRecvBuffer), &dwRecvLength);
962
\end{verbatim}
963
964
\returns
965
966
\begin{tabular}{ll}
967
\texttt{SCARD\_S\_SUCCESS} & Successful\\
968
\texttt{SCARD\_E\_NOT\_TRANSACTED} & Data exchange not successful\\
969
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hCard} handle\\
970
\texttt{SCARD\_E\_INVALID\_VALUE} & Invalid value was presented\\
971
\texttt{SCARD\_E\_READER\_UNAVAILABLE} & The reader has been removed\\
972
\texttt{SCARD\_W\_RESET\_CARD} & The card has been reset by another application\\
973
\texttt{SCARD\_W\_REMOVED\_CARD} & The card has been removed from the reader\\
974
\end{tabular}
975
976
977
%---------%---------%---------%---------%---------%---------
978
\subsection{SCardStatus}
979
980
\synopsis
981
982
\begin{verbatim}
983
#include <winscard.h>
984
985
LONG SCardStatus(SCARDHANDLE hCard,
986
LPSTR szReaderName,
987
LPDWORD pcchReaderLen,
988
LPDWORD pdwState,
989
LPDWORD pdwProtocol,
990
LPBYTE pbAtr,
991
LPDWORD pcbAtrLen);
992
\end{verbatim}
993
994
\parameters
995
996
\begin{tabular}{lll}
997
\texttt{hCard} & IN & Connection made from \texttt{SCardConnect} \\
998
\texttt{szReaderName} & INOUT & Friendly name of this reader\\
999
\texttt{pcchReaderLen} & INOUT & Size of the \texttt{szReaderName} multistring\\
1000
\texttt{pdwState} & OUT & Current state of this reader\\
1001
\texttt{pdwProtocol} & OUT & Current protocol of this reader\\
1002
\texttt{pbAtr} & OUT & Current ATR of a card in this reader\\
1003
\texttt{pcbAtrLen} & OUT & Length of ATR\\
1004
\end{tabular}
1005
1006
\desc
1007
1008
This function returns the current status of the reader connected to by
1009
\texttt{hCard}. It's friendly name will be stored in
1010
\texttt{szReaderName}. \texttt{pcchReaderLen} will be the size of the
1011
allocated buffer for \texttt{szReaderName}. If this is too small the
1012
function will return with the necessary size in \texttt{pcchReaderLen}.
1013
The current state, and protocol will be stored in \texttt{pdwState} and
1014
\texttt{pdwProtocol} respectively. \texttt{pdwState} is a
1015
\texttt{DWORD} possibly OR'd with the following values:
1016
1017
1018
\begin{tabular}{|l|p{12cm}|}
1019
\hline
1020
Value of \texttt{pdwState} & Meaning \\
1021
\hline
1022
\hline
1023
\texttt{SCARD\_ABSENT} & There is no card in the reader\\
1024
\texttt{SCARD\_PRESENT} & There is a card in the reader, but it has not been moved into position for use\\
1025
\texttt{SCARD\_SWALLOWED} & There is a card in the reader in position for use. The card is not powered\\
1026
\texttt{SCARD\_POWERED} & Power is being provided to the card, but the reader driver is unaware of the mode of the card\\
1027
\texttt{SCARD\_NEGOTIABLE} & The card has been reset and is awaiting PTS negotiation\\
1028
\texttt{SCARD\_SPECIFIC} & The card has been reset and specific communication protocols have been established\\
1029
\hline
1030
\end{tabular}
1031
1032
\begin{tabular}{|l|l|}
1033
\hline
1034
Value of \texttt{dwPreferredProtocols} & Meaning \\
1035
\hline
1036
\hline
1037
\texttt{SCARD\_PROTOCOL\_T0} & Use the T=0 protocol\\
1038
\texttt{SCARD\_PROTOCOL\_T1} & Use the T=1 protocol\\
1039
\hline
1040
\end{tabular}
1041
1042
\example
1043
1044
\begin{verbatim}
1045
SCARDCONTEXT hContext;
1046
SCARDHANDLE hCard;
1047
DWORD dwActiveProtocol;
1048
DWORD dwState, dwProtocol, dwAtrLen, dwReaderLen;
1049
BYTE pbAtr[MAX_ATR_SIZE];
1050
1051
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
1052
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
1053
SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
1054
dwAtrLen = sizeof(pbAtr);
1055
rv=SCardStatus(hCard, NULL, &dwReaderLen, &dwState, &dwProtocol,
1056
pbAtr, &dwAtrLen);
1057
\end{verbatim}
1058
1059
\returns
1060
1061
\begin{tabular}{ll}
1062
\texttt{SCARD\_S\_SUCCESS} & Successful\\
1063
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hCard} handle\\
1064
\texttt{SCARD\_E\_INSUFFICIENT\_BUFFER} & Not enough allocated memory for \texttt{szReaderName}\\
1065
& or for \texttt{pbAtr} \\
1066
\texttt{SCARD\_E\_READER\_UNAVAILABLE} & The reader has been removed\\
1067
\end{tabular}
1068
1069
1070
%---------%---------%---------%---------%---------%---------
1071
\subsection{SCardGetStatusChange}
1072
1073
\synopsis
1074
1075
\begin{verbatim}
1076
#include <winscard.h>
1077
1078
LONG SCardGetStatusChange(SCARDCONTEXT hContext,
1079
DWORD dwTimeout,
1080
LPSCARD_READERSTATE rgReaderStates,
1081
DWORD cReaders);
1082
\end{verbatim}
1083
1084
1085
\parameters
1086
1087
\begin{tabular}{lll}
1088
\texttt{hContext} & IN & Connection context to the PC/SC Resource Manager\\
1089
\texttt{dwTimeout} & IN & Maximum block waiting time for status change, zero for infinite\\
1090
\texttt{rgReaderStates} & INOUT & Structures of readers with current states\\
1091
\texttt{cReaders} & IN & Number of structures\\
1092
\end{tabular}
1093
1094
\desc
1095
1096
This function receives a structure or list of structures containing
1097
reader names. It then blocks for a change in state to occur on any of
1098
the OR'd values contained in \texttt{dwCurrentState} for a maximum
1099
blocking time of \texttt{dwTimeout} or forever if \texttt{INFINITE} is
1100
used. The new event state will be contained in \texttt{dwEventState}.
1101
A status change might be a card insertion or removal event, a change in
1102
ATR, \textit{etc}.
1103
1104
This function will block for reader availability if \texttt{cReaders} is
1105
equal to zero and \texttt{rgReaderStates} is \texttt{NULL}.
1106
1107
\begin{verbatim}
1108
typedef struct {
1109
LPCTSTR szReader; /* Reader name */
1110
LPVOID pvUserData; /* User defined data */
1111
DWORD dwCurrentState; /* Current state of reader */
1112
DWORD dwEventState; /* Reader state after a state change */
1113
DWORD cbAtr; /* ATR Length, usually MAX_ATR_SIZE */
1114
BYTE rgbAtr[MAX_ATR_SIZE]; /* ATR Value */
1115
} SCARD_READERSTATE;
1116
1117
typedef SCARD_READERSTATE *PSCARD_READERSTATE, **LPSCARD_READERSTATE;
1118
\end{verbatim}
1119
1120
\begin{tabular}{|p{5cm}|p{10.5cm}|}
1121
\hline
1122
Value of \texttt{dwCurrentState} and \texttt{dwEventState} & Meaning \\
1123
\hline
1124
\hline
1125
\texttt{SCARD\_STATE\_UNAWARE} & The application is unaware of the
1126
current state, and would like to know. The use of this value results in
1127
an immediate return from state transition monitoring services. This is
1128
represented by all bits set to zero\\
1129
1130
\texttt{SCARD\_STATE\_IGNORE} & This reader should be ignored\\
1131
\texttt{SCARD\_STATE\_CHANGED} & There is a difference between the state
1132
believed by the application, and the state known by the resource
1133
manager. When this bit is set, the application may assume a significant
1134
state change has occurred on this reader\\
1135
1136
\texttt{SCARD\_STATE\_UNKNOWN} & The given reader name is not recognized
1137
by the resource manager. If this bit is set, then
1138
\texttt{SCARD\_STATE\_CHANGED} and \texttt{SCARD\_STATE\_IGNORE} will
1139
also be set\\
1140
1141
\hline
1142
\end{tabular}
1143
1144
\begin{tabular}{|p{5cm}|p{10.5cm}|}
1145
\hline
1146
Value of \texttt{dwCurrentState} and \texttt{ddwEventState} & Meaning \\
1147
\hline
1148
\hline
1149
\texttt{SCARD\_STATE\_UNAVAILABLE} & The actual state of this reader is
1150
not available. If this bit is set, then all the following bits are clear\\
1151
1152
\texttt{SCARD\_STATE\_EMPTY} & There is no card in the reader. If this
1153
bit is set, all the following bits will be clear\\
1154
1155
\texttt{SCARD\_STATE\_PRESENT} & There is a card in the reader\\
1156
\texttt{SCARD\_STATE\_ATRMATCH} & There is a card in the reader with an
1157
ATR matching one of the target cards. If this bit is set,
1158
\texttt{SCARD\_STATE\_PRESENT} will also be set. This bit is only
1159
returned on the SCardLocateCards function\\
1160
1161
\texttt{SCARD\_STATE\_EXCLUSIVE} & The card in the reader is allocated
1162
for exclusive use by another application. If this bit is set,
1163
\texttt{SCARD\_STATE\_PRESENT} will also be set\\
1164
1165
\texttt{SCARD\_STATE\_INUSE} & The card in the reader is in use by one
1166
or more other applications, but may be connected to in shared mode. If
1167
this bit is set, SCARD\_STATE\_PRESENT will also be set\\
1168
1169
\texttt{SCARD\_STATE\_MUTE} & There is an unresponsive card in the reader\\
1170
\hline
1171
\end{tabular}
1172
1173
\example
1174
1175
\begin{verbatim}
1176
SCARDCONTEXT hContext;
1177
SCARDHANDLE hCard;
1178
DWORD dwActiveProtocol, cReaders;
1179
SCARD_READERSTATE_A rgReaderStates[1];
1180
LONG rv;
1181
1182
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
1183
1184
rgReaderStates[0].szReader = strdup("Reader X");
1185
rgReaderStates[0].dwCurrentState = SCARD_STATE_EMPTY;
1186
1187
cReaders = 1;
1188
rv = SCardGetStatusChange(hContext, INFINITE, rgReaderStates, cReaders);
1189
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
1190
SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
1191
\end{verbatim}
1192
1193
1194
\returns
1195
1196
\begin{tabular}{ll}
1197
\texttt{SCARD\_S\_SUCCESS} & Successful\\
1198
\texttt{SCARD\_E\_INVALID\_VALUE} & Invalid States, reader name, etc\\
1199
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hContext} handle\\
1200
\texttt{SCARD\_E\_READER\_UNAVAILABLE} & The reader is unavailable\\
1201
\end{tabular}
1202
1203
1204
%---------%---------%---------%---------%---------%---------
1205
\subsection{SCardCancel}
1206
1207
\synopsis
1208
1209
\begin{verbatim}
1210
#include <winscard.h>
1211
1212
LONG SCardCancel(SCARDCONTEXT hContext);
1213
\end{verbatim}
1214
1215
\parameters
1216
1217
\begin{tabular}{lll}
1218
\texttt{hContext} & IN & Connection context to the PC/SC Resource Manager\\
1219
\end{tabular}
1220
1221
\desc
1222
1223
This function cancels all pending blocking requests on the
1224
\texttt{GetStatusChange()} function.
1225
1226
\example
1227
\begin{verbatim}
1228
SCARDCONTEXT hContext;
1229
DWORD cReaders;
1230
SCARD_READERSTATE rgReaderStates;
1231
LONG rv;
1232
1233
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
1234
1235
rgReaderStates.szReader = strdup("Reader X");
1236
rgReaderStates.dwCurrentState = SCARD_STATE_EMPTY;
1237
1238
/* Spawn off thread for following function */
1239
rv = SCardGetStatusChange(hContext, 0, rgReaderStates, cReaders);
1240
1241
rv = SCardCancel(hContext);
1242
\end{verbatim}
1243
1244
\returns
1245
1246
\begin{tabular}{ll}
1247
\texttt{SCARD\_S\_SUCCESS} & Successful\\
1248
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hContext} handle\\
1249
\end{tabular}
1250
1251
1252
%---------%---------%---------%---------%---------%---------
1253
\subsection{SCardSetTimeout}
1254
1255
\synopsis
1256
1257
\begin{verbatim}
1258
#include <winscard.h>
1259
1260
LONG SCardSetTimeout(SCARDCONTEXT hContext,
1261
DWORD dwTimeout);
1262
\end{verbatim}
1263
1264
\parameters
1265
1266
\begin{tabular}{lll}
1267
\texttt{hContext} & IN & Connection context to the PC/SC Resource Manager\\
1268
\texttt{dwTimeout} & IN & New timeout value\\
1269
\end{tabular}
1270
1271
\desc
1272
1273
This function updates the working waiting time that RPC uses when
1274
waiting for a server function to return. This needs to be updated when
1275
a card command is sent that might take more time than usual.
1276
1277
This command is pcsc-lite specific and does not exist in Windows PC/SC.
1278
1279
\example
1280
1281
\begin{verbatim}
1282
SCARDCONTEXT hContext;
1283
LONG rv;
1284
1285
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
1286
rv = SCardSetTimeout(hContext, 50); /* 50 second timeout */
1287
\end{verbatim}
1288
1289
\returns
1290
1291
\begin{tabular}{ll}
1292
\texttt{SCARD\_S\_SUCCESS} & Successful\\
1293
\texttt{SCARD\_E\_INVALID\_HANDLE} & Invalid \texttt{hContext} handle\\
1294
\end{tabular}
1295
1296
1297
%---------%---------%---------%---------%---------%---------
1298
\subsection{SCardGetAttrib}
1299
1300
\synopsis
1301
1302
\begin{verbatim}
1303
#include <winscard.h>
1304
1305
LONG SCardGetAttrib(SCARDHANDLE hCard,
1306
DWORD dwAttrId,
1307
LPBYTE pbAttr,
1308
LPDWORD pcbAttrLen);
1309
\end{verbatim}
1310
1311
\parameters
1312
1313
\begin{tabular}{lll}
1314
\texttt{hCard} & IN & Connection made from \texttt{SCardConnect}\\
1315
\texttt{dwAttrId} & IN & Identifier for the attribute to get \\
1316
\texttt{pbAttr} & OUT & Pointer to a buffer that receives the attribute \\
1317
\texttt{pcbAttrLen} & IN/OUT & Length of the \texttt{pbAttr} buffer in bytes \\
1318
\end{tabular}
1319
1320
\desc
1321
1322
This function get an attribute from the IFD Handler. The list of
1323
possible attributes is available in the file \texttt{pcsclite.h}.
1324
1325
\begin{itemize}
1326
\item \texttt{SCARD\_ATTR\_ASYNC\_PROTOCOL\_TYPES}
1327
\item \texttt{SCARD\_ATTR\_ATR\_STRING}
1328
\item \texttt{SCARD\_ATTR\_CHANNEL\_ID}
1329
\item \texttt{SCARD\_ATTR\_CHARACTERISTICS}
1330
\item \texttt{SCARD\_ATTR\_CURRENT\_BWT}
1331
\item \texttt{SCARD\_ATTR\_CURRENT\_CLK}
1332
\item \texttt{SCARD\_ATTR\_CURRENT\_CWT}
1333
\item \texttt{SCARD\_ATTR\_CURRENT\_D}
1334
\item \texttt{SCARD\_ATTR\_CURRENT\_EBC\_ENCODING}
1335
\item \texttt{SCARD\_ATTR\_CURRENT\_F}
1336
\item \texttt{SCARD\_ATTR\_CURRENT\_IFSC}
1337
\item \texttt{SCARD\_ATTR\_CURRENT\_IFSD}
1338
\item \texttt{SCARD\_ATTR\_CURRENT\_IO\_STATE}
1339
\item \texttt{SCARD\_ATTR\_CURRENT\_N}
1340
\item \texttt{SCARD\_ATTR\_CURRENT\_PROTOCOL\_TYPE}
1341
\item \texttt{SCARD\_ATTR\_CURRENT\_W}
1342
\item \texttt{SCARD\_ATTR\_DEFAULT\_CLK}
1343
\item \texttt{SCARD\_ATTR\_DEFAULT\_DATA\_RATE}
1344
\item \texttt{SCARD\_ATTR\_DEVICE\_FRIENDLY\_NAME\_A}
1345
\item \texttt{SCARD\_ATTR\_DEVICE\_FRIENDLY\_NAME\_W}
1346
\item \texttt{SCARD\_ATTR\_DEVICE\_IN\_USE}
1347
\item \texttt{SCARD\_ATTR\_DEVICE\_SYSTEM\_NAME\_A}
1348
\item \texttt{SCARD\_ATTR\_DEVICE\_SYSTEM\_NAME\_W}
1349
\item \texttt{SCARD\_ATTR\_DEVICE\_UNIT}
1350
\item \texttt{SCARD\_ATTR\_ESC\_AUTHREQUEST}
1351
\item \texttt{SCARD\_ATTR\_ESC\_CANCEL}
1352
\item \texttt{SCARD\_ATTR\_ESC\_RESET}
1353
\item \texttt{SCARD\_ATTR\_EXTENDED\_BWT}
1354
\item \texttt{SCARD\_ATTR\_ICC\_INTERFACE\_STATUS}
1355
\item \texttt{SCARD\_ATTR\_ICC\_PRESENCE}
1356
\item \texttt{SCARD\_ATTR\_ICC\_TYPE\_PER\_ATR}
1357
\item \texttt{SCARD\_ATTR\_MAX\_CLK}
1358
\item \texttt{SCARD\_ATTR\_MAX\_DATA\_RATE}
1359
\item \texttt{SCARD\_ATTR\_MAX\_IFSD}
1360
\item \texttt{SCARD\_ATTR\_MAXINPUT}
1361
\item \texttt{SCARD\_ATTR\_POWER\_MGMT\_SUPPORT}
1362
\item \texttt{SCARD\_ATTR\_SUPRESS\_T1\_IFS\_REQUEST}
1363
\item \texttt{SCARD\_ATTR\_SYNC\_PROTOCOL\_TYPES}
1364
\item \texttt{SCARD\_ATTR\_USER\_AUTH\_INPUT\_DEVICE}
1365
\item \texttt{SCARD\_ATTR\_USER\_TO\_CARD\_AUTH\_DEVICE}
1366
\item \texttt{SCARD\_ATTR\_VENDOR\_IFD\_SERIAL\_NO}
1367
\item \texttt{SCARD\_ATTR\_VENDOR\_IFD\_TYPE}
1368
\item \texttt{SCARD\_ATTR\_VENDOR\_IFD\_VERSION}
1369
\item \texttt{SCARD\_ATTR\_VENDOR\_NAME}
1370
\end{itemize}
1371
1372
Not all the \texttt{dwAttrId} values listed above may be implemented in
1373
the IFD Handler you are using. And some \texttt{dwAttrId} values not
1374
listed here may be implemented.
1375
1376
\example
1377
1378
\begin{verbatim}
1379
LONG rv;
1380
SCARDCONTEXT hContext;
1381
SCARDHANDLE hCard;
1382
DWORD dwActiveProtocol;
1383
unsigned char pbAtr[MAX_ATR_SIZE];
1384
DWORD dwAtrLen;
1385
1386
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
1387
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
1388
SCARD_PROTOCOL_RAW &hCard, &dwActiveProtocol);
1389
rv = SCardGetAttrib(hCard, SCARD_ATTR_ATR_STRING, pbAtr, &dwAtrLen);
1390
\end{verbatim}
1391
1392
\returns
1393
1394
\begin{tabular}{ll}
1395
\texttt{SCARD\_S\_SUCCESS} & Successful\\
1396
\texttt{SCARD\_E\_NOT\_TRANSACTED} & Data exchange not successful\\
1397
\texttt{SCARD\_E\_INSUFFICIENT\_BUFFER} & Reader buffer not large enough \\
1398
\end{tabular}
1399
1400
1401
%---------%---------%---------%---------%---------%---------
1402
\subsection{SCardSetAttrib}
1403
1404
\synopsis
1405
1406
\begin{verbatim}
1407
#include <winscard.h>
1408
1409
LONG SCardSetAttrib(SCARDHANDLE hCard,
1410
DWORD dwAttrId,
1411
LPCBYTE pbAttr,
1412
DWORD cbAttrLen);
1413
\end{verbatim}
1414
1415
\parameters
1416
1417
\begin{tabular}{lll}
1418
\texttt{hCard} & IN & Connection made from \texttt{SCardConnect}\\
1419
\texttt{dwAttrId} & IN & Identifier for the attribute to get \\
1420
\texttt{pbAttr} & IN & Pointer to a buffer that receives the attribute \\
1421
\texttt{pcbAttrLen} & IN & Length of the \texttt{pbAttr} buffer in bytes \\
1422
\end{tabular}
1423
1424
\desc
1425
1426
This function set an attribute of the IFD Handler. The list of
1427
attributes you can set is dependent on the IFD Handler you are using.
1428
1429
\example
1430
1431
\begin{verbatim}
1432
LONG rv;
1433
SCARDCONTEXT hContext;
1434
SCARDHANDLE hCard;
1435
DWORD dwActiveProtocol;
1436
unsigned char pbAtr[MAX_ATR_SIZE];
1437
DWORD dwAtrLen;
1438
1439
rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
1440
rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED,
1441
SCARD_PROTOCOL_RAW &hCard, &dwActiveProtocol);
1442
rv = SCardSetAttrib(hCard, 0x42000001, "\x12\x34\x56", 3);
1443
\end{verbatim}
1444
1445
\returns
1446
1447
\begin{tabular}{ll}
1448
\texttt{SCARD\_S\_SUCCESS} & Successful\\
1449
\texttt{SCARD\_E\_NOT\_TRANSACTED} & Data exchange not successful\\
1450
\end{tabular}
1451
1452
1453
%---------%---------%---------%---------%---------%---------
1454
\subsection{pcsc\_stringify\_error}
1455
1456
\synopsis
1457
1458
\begin{verbatim}
1459
#include <pcsclite.h>
1460
1461
char *pcsc_stringify_error(long error);
1462
\end{verbatim}
1463
1464
\desc
1465
1466
This function return a human readable text for the given PC/SC error
1467
code.
1468
1469
\example
1470
1471
1472
\begin{verbatim}
1473
SCARDCONTEXT hContext;
1474
LONG rv;
1475
1476
rv = SCardEstablishContext(SCARD\_SCOPE\_SYSTEM, NULL, NULL, &hContext);
1477
if (rv != SCARD_S_SUCCESS)
1478
printf("SCardReleaseContext: %s (0x%lX)\n", pcsc_stringify_error(rv), rv);
1479
\end{verbatim}
1480
1481
1482
%---------%---------%---------%---------%---------%---------%---------
1483
\section{Multithreading and contexts}
1484
1485
From version 1.2.0 pcsc-lite is much more multithreading friendly.
1486
1487
You have to follow some rules:
1488
1489
\begin{itemize}
1490
\item For security reasons, a context can only be released (using
1491
\texttt{SCardReleaseContext()}) by the thread that created it.
1492
1493
\item To access different readers (\emph{i.e.} cards) in different
1494
threads, each thread must use a different context (not necessarily
1495
created by this thread itself).
1496
1497
\end{itemize}
1498
1499
Each thread should create his own context with
1500
\texttt{SCardEstablishContext()} and should release it with
1501
\texttt{SCardReleaseContext()} when the context is not necessary any
1502
more.
1503
1504
If different threads share a same context, the calls to different
1505
functions of the pcsc-lite API are stored in a queue and the executions
1506
serialised for this context because there is a mutex shared for all the
1507
(critical) operations of this context.
1508
1509
1510
%---------%---------%---------%---------%---------%---------
1511
\bibliographystyle{plain}
1512
\bibliography{pcsc-lite}
1513
1514
1515
\end{document}
1516
Loggerhead is a web-based interface for Breezy
Version: 2.0.1