[Pcsclite-cvs-commit] CVS PCSC/src
CVS User rousseau
ludovic.rousseau@free.fr
Tue, 12 Apr 2005 12:09:12 +0000
Update of /cvsroot/pcsclite/PCSC/src
In directory haydn:/tmp/cvs-serv11706/src
Modified Files:
atrhandler.c atrhandler.h debuglog.c dyn_hpux.c dyn_macosx.c
dyn_unix.c dyn_win32.c eventhandler.c eventhandler.h hotplug.h
hotplug_generic.c hotplug_libusb.c hotplug_linux.c
hotplug_macosx.c ifdwrapper.c ifdwrapper.h pcscdaemon.c
powermgt_generic.c powermgt_generic.h prothandler.c
prothandler.h readerfactory.c readerfactory.h strlcpycat.h
sys_unix.c testpcsc.c thread_unix.c thread_win32.c winscard.c
winscard_clnt.c winscard_msg.c winscard_msg.h winscard_scf.c
winscard_svc.c winscard_svc.h
Log Message:
add (some) Doxygen documentation
Thanks to Luiz Reuter Silva Torro for the patch
--- /cvsroot/pcsclite/PCSC/src/atrhandler.c 2005/03/01 09:17:03 1.17
+++ /cvsroot/pcsclite/PCSC/src/atrhandler.c 2005/04/12 12:09:04 1.18
@@ -1,14 +1,21 @@
/*
- * This keeps track of smartcard protocols, timing issues
- * and ATR handling.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999-2004
* David Corcoran <corcoran@linuxnet.com>
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: atrhandler.c,v 1.17 2005/03/01 09:17:03 rousseau Exp $
+ * $Id: atrhandler.c,v 1.18 2005/04/12 12:09:04 rousseau Exp $
+ */
+
+/**
+ * @file
+ *
+ * @brief This keeps track of smartcard protocols, timing issues
+ * and ATR (Answer-to-Reset) handling.
+ *
+ * @note use ./configure --enable-debugatr to enable debug messages
+ * to be logged.
*/
#include "config.h"
@@ -19,12 +26,19 @@
#include "debuglog.h"
#include "atrhandler.h"
-/*
- * Uncomment the following for ATR debugging
+/**
+ * Uncomment the following for ATR debugging
* or use ./configure --enable-debugatr
*/
/* #define ATR_DEBUG */
+/**
+ * @brief
+ * @param psExtension
+ * @param pucAtr
+ * @param dwLength
+ * @return
+ */
short ATRDecodeAtr(PSMARTCARD_EXTENSION psExtension,
PUCHAR pucAtr, DWORD dwLength)
{
@@ -44,7 +58,7 @@
#endif
if (dwLength < 2)
- return 0; /* Atr must have TS and T0 */
+ return 0; /** @retval 0 Atr must have TS and T0 */
/*
* Zero out the bitmasks
@@ -67,7 +81,7 @@
else
{
memset(psExtension, 0x00, sizeof(SMARTCARD_EXTENSION));
- return 0;
+ return 0; /** @retval 0 Unable to decode TS byte */
}
/*
@@ -129,7 +143,7 @@
SCARD_PROTOCOL_T1;
break;
default:
- return 0;
+ return 0; /** @retval 0 Unable to decode LNS */
}
}
@@ -193,7 +207,7 @@
break;
default:
- return 0;
+ return 0; /** @retval 0 Unable do decode T protocol */
}
}
} else
@@ -202,7 +216,7 @@
if (p > MAX_ATR_SIZE)
{
memset(psExtension, 0x00, sizeof(SMARTCARD_EXTENSION));
- return 0;
+ return 0; /** @retval 0 Maximum attribute size */
}
/* next interface characters index */
@@ -243,6 +257,6 @@
psExtension->CardCapabilities.AvailableProtocols);
#endif
- return 1;
+ return 1; /** @retval 1 Success */
}
--- /cvsroot/pcsclite/PCSC/src/atrhandler.h 2003/10/18 17:19:36 1.4
+++ /cvsroot/pcsclite/PCSC/src/atrhandler.h 2005/04/12 12:09:05 1.5
@@ -1,13 +1,16 @@
/*
- * This keeps track of smartcard protocols, timing issues
- * and ATR handling.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999
* David Corcoran <corcoran@linuxnet.com>
*
- * $Id: atrhandler.h,v 1.4 2003/10/18 17:19:36 aet-guest Exp $
+ * $Id: atrhandler.h,v 1.5 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This keeps track of smartcard protocols, timing issues
+ * and Answer to Reset ATR handling.
*/
#ifndef __atrhandler_h__
--- /cvsroot/pcsclite/PCSC/src/debuglog.c 2005/04/12 07:42:15 1.40
+++ /cvsroot/pcsclite/PCSC/src/debuglog.c 2005/04/12 12:09:05 1.41
@@ -1,6 +1,4 @@
/*
- * This handles debugging.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999-2002
@@ -8,9 +6,14 @@
* Copyright (C) 1999-2005
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: debuglog.c,v 1.40 2005/04/12 07:42:15 rousseau Exp $
+ * $Id: debuglog.c,v 1.41 2005/04/12 12:09:05 rousseau Exp $
*/
+/**
+ * @file
+ * @brief This handles debugging.
+ */
+
#include "config.h"
#ifdef HAVE_SYSLOG_H
#include <syslog.h>
@@ -29,8 +32,10 @@
#include "strlcpycat.h"
#include "misc.h"
-/* Max string size when dumping a 256 bytes longs APDU
- * Should be bigger than 256*3+30 */
+/**
+ * Max string size when dumping a 256 bytes longs APDU
+ * Should be bigger than 256*3+30
+ */
#define DEBUG_BUF_SIZE 2048
static char LogSuppress = DEBUGLOG_LOG_ENTRIES;
@@ -255,6 +260,23 @@
log_xxd(PCSC_LOG_INFO, "SW: ", (const unsigned char *)buffer, len);
}
+/**
+ * @brief This function return a human readable text for the given PC/SC error code.
+ *
+ * @param[in] pcscError Error code to be translated to text.
+ *
+ * @return Text representing de error code passed.
+ *
+ * @test
+ * @code
+ * SCARDCONTEXT hContext;
+ * LONG rv;
+ * rv = SCardEstablishContext(SCARD\_SCOPE\_SYSTEM, NULL, NULL, &hContext);
+ * if (rv != SCARD_S_SUCCESS)
+ * printf("SCardReleaseContext: %s (0x%lX)\n",
+ * pcsc_stringify_error(rv), rv);
+ * @endcode
+ */
char* pcsc_stringify_error(long pcscError)
{
static char strError[75];
--- /cvsroot/pcsclite/PCSC/src/dyn_hpux.c 2005/02/22 14:40:25 1.11
+++ /cvsroot/pcsclite/PCSC/src/dyn_hpux.c 2005/04/12 12:09:05 1.12
@@ -1,6 +1,4 @@
/*
- * This abstracts dynamic library loading functions and timing.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2001
@@ -8,7 +6,12 @@
* Copyright (C) 2004
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: dyn_hpux.c,v 1.11 2005/02/22 14:40:25 rousseau Exp $
+ * $Id: dyn_hpux.c,v 1.12 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/*
+ * @file
+ * @brief This abstracts dynamic library loading functions and timing.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/dyn_macosx.c 2005/02/22 14:40:26 1.10
+++ /cvsroot/pcsclite/PCSC/src/dyn_macosx.c 2005/04/12 12:09:05 1.11
@@ -1,12 +1,15 @@
/*
- * This abstracts dynamic library loading functions and timing.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2000
* David Corcoran <corcoran@linuxnet.com>
*
- * $Id: dyn_macosx.c,v 1.10 2005/02/22 14:40:26 rousseau Exp $
+ * $Id: dyn_macosx.c,v 1.11 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This abstracts dynamic library loading functions and timing.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/dyn_unix.c 2005/04/12 07:38:44 1.14
+++ /cvsroot/pcsclite/PCSC/src/dyn_unix.c 2005/04/12 12:09:05 1.15
@@ -1,6 +1,4 @@
/*
- * This abstracts dynamic library loading functions and timing.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999
@@ -8,7 +6,12 @@
* Copyright (C) 2004
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: dyn_unix.c,v 1.14 2005/04/12 07:38:44 rousseau Exp $
+ * $Id: dyn_unix.c,v 1.15 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This abstracts dynamic library loading functions and timing.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/dyn_win32.c 2005/02/22 14:40:26 1.9
+++ /cvsroot/pcsclite/PCSC/src/dyn_win32.c 2005/04/12 12:09:05 1.10
@@ -1,12 +1,15 @@
/*
- * This abstracts dynamic library loading functions and timing.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999
* David Corcoran <corcoran@linuxnet.com>
*
- * $Id: dyn_win32.c,v 1.9 2005/02/22 14:40:26 rousseau Exp $
+ * $Id: dyn_win32.c,v 1.10 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This abstracts dynamic library loading functions and timing.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/eventhandler.c 2005/02/22 14:40:26 1.31
+++ /cvsroot/pcsclite/PCSC/src/eventhandler.c 2005/04/12 12:09:05 1.32
@@ -1,7 +1,4 @@
/*
- * This keeps track of card insertion/removal events
- * and updates ATR, protocol, and status information.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2000
@@ -9,7 +6,13 @@
* Copyright (C) 2004
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: eventhandler.c,v 1.31 2005/02/22 14:40:26 rousseau Exp $
+ * $Id: eventhandler.c,v 1.32 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This keeps track of card insertion/removal events
+ * and updates ATR, protocol, and status information.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/eventhandler.h 2004/06/17 13:43:37 1.6
+++ /cvsroot/pcsclite/PCSC/src/eventhandler.h 2005/04/12 12:09:05 1.7
@@ -1,7 +1,4 @@
/*
- * This handles card insertion/removal events, updates ATR,
- * protocol, and status information.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999
@@ -9,7 +6,13 @@
* Copyright (C) 2004
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: eventhandler.h,v 1.6 2004/06/17 13:43:37 rousseau Exp $
+ * $Id: eventhandler.h,v 1.7 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This handles card insertion/removal events, updates ATR,
+ * protocol, and status information.
*/
#ifndef __eventhandler_h__
@@ -20,11 +23,11 @@
{
#endif
- /*
+ /**
+ * @typedef
* Define an exported public reader state structure so each
* application gets instant notification of changes in state.
*/
-
typedef struct pubReaderStatesList
{
LONG readerID;
--- /cvsroot/pcsclite/PCSC/src/hotplug.h 2004/03/18 10:08:50 1.6
+++ /cvsroot/pcsclite/PCSC/src/hotplug.h 2005/04/12 12:09:05 1.7
@@ -1,12 +1,15 @@
/*
- * This provides a search API for hot pluggble devices.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2000-2003
* David Corcoran <corcoran@linuxnet.com>
*
- * $Id: hotplug.h,v 1.6 2004/03/18 10:08:50 rousseau Exp $
+ * $Id: hotplug.h,v 1.7 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This provides a search API for hot pluggble devices.
*/
#ifndef __hotplug_h__
--- /cvsroot/pcsclite/PCSC/src/hotplug_generic.c 2004/08/06 12:12:20 1.9
+++ /cvsroot/pcsclite/PCSC/src/hotplug_generic.c 2005/04/12 12:09:05 1.10
@@ -1,24 +1,25 @@
/*
- * This provides a search API for hot pluggble devices.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2000-2003
* David Corcoran <corcoran@linuxnet.com>
*
- * $Id: hotplug_generic.c,v 1.9 2004/08/06 12:12:20 rousseau Exp $
+ * $Id: hotplug_generic.c,v 1.10 2005/04/12 12:09:05 rousseau Exp $
*/
-#include "config.h"
-#include "pcsclite.h"
-
-/*
+/**
+ * @file
+ * @brief This provides a search API for hot pluggble devices.
+ *
* Check for platforms that have their own specific support.
- * It's more easy and flexible to do it here, rather than
+ * It's easier and flexible to do it here, rather than
* with automake conditionals in src/Makefile.am.
* No, it's still not a perfect solution design wise.
*/
+#include "config.h"
+#include "pcsclite.h"
+
#if !defined(__APPLE__) && !defined(HAVE_LIBUSB) && !defined(__linux__)
LONG HPSearchHotPluggables(void)
--- /cvsroot/pcsclite/PCSC/src/hotplug_libusb.c 2005/02/22 14:40:26 1.33
+++ /cvsroot/pcsclite/PCSC/src/hotplug_libusb.c 2005/04/12 12:09:05 1.34
@@ -1,6 +1,4 @@
/*
- * This provides a search API for hot pluggble devices.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2001-2004
@@ -9,7 +7,12 @@
* Toni Andjelkovic <toni@soth.at>
* Damien Sauveron <damien.sauveron@labri.fr>
*
- * $Id: hotplug_libusb.c,v 1.33 2005/02/22 14:40:26 rousseau Exp $
+ * $Id: hotplug_libusb.c,v 1.34 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This provides a search API for hot pluggble devices.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/hotplug_linux.c 2005/02/22 14:40:26 1.32
+++ /cvsroot/pcsclite/PCSC/src/hotplug_linux.c 2005/04/12 12:09:05 1.33
@@ -1,6 +1,4 @@
/*
- * This provides a search API for hot pluggble devices.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2001-2003
@@ -10,7 +8,12 @@
* The USB code was based partly on Johannes Erdfelt
* libusb code found at libusb.sourceforge.net
*
- * $Id: hotplug_linux.c,v 1.32 2005/02/22 14:40:26 rousseau Exp $
+ * $Id: hotplug_linux.c,v 1.33 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This provides a search API for hot pluggble devices.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/hotplug_macosx.c 2005/02/22 14:40:26 1.23
+++ /cvsroot/pcsclite/PCSC/src/hotplug_macosx.c 2005/04/12 12:09:05 1.24
@@ -1,6 +1,4 @@
/*
- * This provides a search API for hot pluggble devices.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2002-2004
@@ -8,7 +6,12 @@
* Ludovic Rousseau <ludovic.rousseau@free.fr>
* David Corcoran <corcoran@linuxnet.com>
*
- * $Id: hotplug_macosx.c,v 1.23 2005/02/22 14:40:26 rousseau Exp $
+ * $Id: hotplug_macosx.c,v 1.24 2005/04/12 12:09:05 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This provides a search API for hot pluggble devices.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/ifdwrapper.c 2005/02/22 14:40:26 1.29
+++ /cvsroot/pcsclite/PCSC/src/ifdwrapper.c 2005/04/12 12:09:06 1.30
@@ -1,6 +1,4 @@
/*
- * This wraps the dynamic ifdhandler functions.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999-2004
@@ -8,7 +6,12 @@
* Damien Sauveron <damien.sauveron@labri.fr>
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: ifdwrapper.c,v 1.29 2005/02/22 14:40:26 rousseau Exp $
+ * $Id: ifdwrapper.c,v 1.30 2005/04/12 12:09:06 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This wraps the dynamic ifdhandler functions.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/ifdwrapper.h 2004/06/18 08:32:01 1.8
+++ /cvsroot/pcsclite/PCSC/src/ifdwrapper.h 2005/04/12 12:09:06 1.9
@@ -1,14 +1,17 @@
/*
- * This wraps the dynamic ifdhandler functions. The abstraction will
- * eventually allow multiple card slots in the same terminal.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999-2004
* David Corcoran <corcoran@linuxnet.com>
* Ludovic Rousseau <ludovic.rouseau@free.fr>
*
- * $Id: ifdwrapper.h,v 1.8 2004/06/18 08:32:01 rousseau Exp $
+ * $Id: ifdwrapper.h,v 1.9 2005/04/12 12:09:06 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This wraps the dynamic ifdhandler functions. The abstraction will
+ * eventually allow multiple card slots in the same terminal.
*/
#ifndef __ifdwrapper_h__
--- /cvsroot/pcsclite/PCSC/src/pcscdaemon.c 2005/03/22 11:00:59 1.57
+++ /cvsroot/pcsclite/PCSC/src/pcscdaemon.c 2005/04/12 12:09:06 1.58
@@ -1,13 +1,20 @@
/*
- * This is the main pcscd daemon.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999-2005
* David Corcoran <corcoran@linuxnet.com>
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: pcscdaemon.c,v 1.57 2005/03/22 11:00:59 rousseau Exp $
+ * $Id: pcscdaemon.c,v 1.58 2005/04/12 12:09:06 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This is the main pcscd daemon.
+ *
+ * The function \c main() starts up the communication environment.\n
+ * Then an endless loop is calld to look for Client connections. For each
+ * Client connection a call to \c CreateContextThread() is done.
*/
#include "config.h"
@@ -67,14 +74,19 @@
*/
}
-/*
- * The Message Queue Listener function
+/**
+ * @brief The Server's Message Queue Listener function.
+ *
+ * An endless loop calls the function \c SHMProcessEventsServer() to check for
+ * messages sent by clients.
+ * If the message is valid, \c CreateContextThread() is called to serve this
+ * request.
*/
void SVCServiceRunLoop(void)
{
int rsp;
LONG rv;
- DWORD dwClientID;
+ DWORD dwClientID; /* Connection ID used to reference the Client */
rsp = 0;
rv = 0;
--- /cvsroot/pcsclite/PCSC/src/powermgt_generic.c 2004/08/06 12:12:20 1.6
+++ /cvsroot/pcsclite/PCSC/src/powermgt_generic.c 2005/04/12 12:09:06 1.7
@@ -1,12 +1,15 @@
/*
- * This handles power management routines.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2000-2003
* David Corcoran <corcoran@linuxnet.com>
*
- * $Id: powermgt_generic.c,v 1.6 2004/08/06 12:12:20 rousseau Exp $
+ * $Id: powermgt_generic.c,v 1.7 2005/04/12 12:09:06 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This handles power management routines.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/powermgt_generic.h 2004/06/17 06:44:01 1.3
+++ /cvsroot/pcsclite/PCSC/src/powermgt_generic.h 2005/04/12 12:09:06 1.4
@@ -1,12 +1,15 @@
/*
- * This handles power management routines.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2002
* David Corcoran <corcoran@linuxnet.com>
*
- * $Id: powermgt_generic.h,v 1.3 2004/06/17 06:44:01 rousseau Exp $
+ * $Id: powermgt_generic.h,v 1.4 2005/04/12 12:09:06 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This handles power management routines.
*/
#ifndef __powermgt_generic_h__
--- /cvsroot/pcsclite/PCSC/src/prothandler.c 2005/02/22 14:40:26 1.17
+++ /cvsroot/pcsclite/PCSC/src/prothandler.c 2005/04/12 12:09:06 1.18
@@ -1,6 +1,4 @@
/*
- * This handles protocol defaults, PTS, etc.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999
@@ -8,7 +6,12 @@
* Copyright (C) 2004
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: prothandler.c,v 1.17 2005/02/22 14:40:26 rousseau Exp $
+ * $Id: prothandler.c,v 1.18 2005/04/12 12:09:06 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This handles protocol defaults, PTS, etc.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/prothandler.h 2004/06/29 07:49:00 1.6
+++ /cvsroot/pcsclite/PCSC/src/prothandler.h 2005/04/12 12:09:06 1.7
@@ -1,6 +1,4 @@
/*
- * This handles protocol defaults, PTS, etc.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999
@@ -8,7 +6,12 @@
* Copyright (C) 2004
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: prothandler.h,v 1.6 2004/06/29 07:49:00 rousseau Exp $
+ * $Id: prothandler.h,v 1.7 2005/04/12 12:09:06 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This handles protocol defaults, PTS, etc.
*/
#ifndef __prothandler_h__
--- /cvsroot/pcsclite/PCSC/src/readerfactory.c 2005/03/02 15:18:25 1.70
+++ /cvsroot/pcsclite/PCSC/src/readerfactory.c 2005/04/12 12:09:06 1.71
@@ -1,6 +1,4 @@
/*
- * This keeps track of a list of currently available reader structures.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999-2004
@@ -8,7 +6,12 @@
* Damien Sauveron <damien.sauveron@labri.fr>
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: readerfactory.c,v 1.70 2005/03/02 15:18:25 rousseau Exp $
+ * $Id: readerfactory.c,v 1.71 2005/04/12 12:09:06 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This keeps track of a list of currently available reader structures.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/readerfactory.h 2004/08/13 20:31:46 1.21
+++ /cvsroot/pcsclite/PCSC/src/readerfactory.h 2005/04/12 12:09:07 1.22
@@ -1,6 +1,4 @@
/*
- * This keeps track of a list of currently available reader structures.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999
@@ -8,7 +6,12 @@
* Copyright (C) 2004
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: readerfactory.h,v 1.21 2004/08/13 20:31:46 rousseau Exp $
+ * $Id: readerfactory.h,v 1.22 2005/04/12 12:09:07 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This keeps track of a list of currently available reader structures.
*/
#ifndef __readerfactory_h__
--- /cvsroot/pcsclite/PCSC/src/strlcpycat.h 2004/09/07 08:35:00 1.1
+++ /cvsroot/pcsclite/PCSC/src/strlcpycat.h 2005/04/12 12:09:08 1.2
@@ -1,12 +1,15 @@
/*
- * prototypes of strlcpy()/strlcat() imported from OpenBSD
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2004
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: strlcpycat.h,v 1.1 2004/09/07 08:35:00 rousseau Exp $
+ * $Id: strlcpycat.h,v 1.2 2005/04/12 12:09:08 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief prototypes of strlcpy()/strlcat() imported from OpenBSD
*/
#ifndef HAVE_STRLCPY
--- /cvsroot/pcsclite/PCSC/src/sys_unix.c 2005/04/12 07:38:44 1.16
+++ /cvsroot/pcsclite/PCSC/src/sys_unix.c 2005/04/12 12:09:08 1.17
@@ -6,7 +6,12 @@
* Copyright (C) 1999
* David Corcoran <corcoran@linuxnet.com>
*
- * $Id: sys_unix.c,v 1.16 2005/04/12 07:38:44 rousseau Exp $
+ * $Id: sys_unix.c,v 1.17 2005/04/12 12:09:08 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This handles abstract system level calls.
*/
#include "config.h"
@@ -29,6 +34,12 @@
#include "debuglog.h"
#include "misc.h"
+/**
+ * @brief Make system wide initialization.
+ *
+ * @return Eror code.
+ * @retval 0 Success.
+ */
INTERNAL int SYS_Initialize(void)
{
/*
@@ -37,16 +48,36 @@
return 0;
}
+/**
+ * @brief Attempts to create a directory with some permissions.
+ *
+ * @param[in] path Path of the directory to be created.
+ * @param[in] perms Permissions to the new directory.
+ *
+ * @return Eror code.
+ * @retval 0 Success.
+ * @retval -1 An error occurred.
+ */
INTERNAL int SYS_Mkdir(char *path, int perms)
{
return mkdir(path, perms);
}
+/**
+ * @brief Gets the running process's ID.
+ *
+ * @return PID.
+ */
INTERNAL int SYS_GetPID(void)
{
return getpid();
}
+/**
+ * @brief Makes the current process sleep for some seconds.
+ *
+ * @param[in] iTimeVal Number of seconds to sleep.
+ */
INTERNAL int SYS_Sleep(int iTimeVal)
{
#ifdef HAVE_NANOSLEEP
@@ -60,6 +91,11 @@
#endif
}
+/**
+ * @brief Makes the current process sleep for some microseconds.
+ *
+ * @param[in] iTimeVal Number of microseconds to sleep.
+ */
INTERNAL int SYS_USleep(int iTimeVal)
{
#ifdef HAVE_NANOSLEEP
@@ -74,16 +110,45 @@
#endif
}
+/**
+ * @brief Opens/creates a file.
+ *
+ * @param[in] pcFile path to the file.
+ * @param[in] flags Open and read/write choices.
+ * @param[in] mode Permissions to the file.
+ *
+ * @return File descriptor.
+ * @retval >0 The file descriptor.
+ * @retval -1 An error ocurred.
+ */
INTERNAL int SYS_OpenFile(char *pcFile, int flags, int mode)
{
return open(pcFile, flags, mode);
}
+/**
+ * @brief Opens/creates a file.
+ *
+ * @param[in] iHandle File descriptor.
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 An error ocurred.
+ */
INTERNAL int SYS_CloseFile(int iHandle)
{
return close(iHandle);
}
+/**
+ * @brief Removes a file.
+ *
+ * @param[in] pcFile path to the file.
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 An error ocurred.
+ */
INTERNAL int SYS_RemoveFile(char *pcFile)
{
return remove(pcFile);
@@ -129,6 +194,15 @@
return chmod(pcFile, mode);
}
+/**
+ * @brief Makes a non-blocking request to lock a file exclusively.
+ *
+ * @param[in] iHandle File descriptor.
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 An error ocurred.
+ */
INTERNAL int SYS_LockFile(int iHandle)
{
#ifdef HAVE_FLOCK
@@ -145,6 +219,15 @@
#endif
}
+/**
+ * @brief Makes a blocking request to lock a file exclusively.
+ *
+ * @param[in] iHandle File descriptor.
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 An error ocurred.
+ */
INTERNAL int SYS_LockAndBlock(int iHandle)
{
#ifdef HAVE_FLOCK
@@ -161,6 +244,15 @@
#endif
}
+/**
+ * @brief Unlocks the file.
+ *
+ * @param[in] iHandle File descriptor.
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 An error ocurred.
+ */
INTERNAL int SYS_UnlockFile(int iHandle)
{
#ifdef HAVE_FLOCK
@@ -194,11 +286,28 @@
return write(iHandle, pcBuffer, iLength);
}
+/**
+ * @brief Gets the memory page size.
+ *
+ * The page size is used when calling the \c SYS_MemoryMap() and
+ * \c SYS_PublicMemoryMap() functions.
+ *
+ * @return Number of bytes per page.
+ */
INTERNAL int SYS_GetPageSize(void)
{
return getpagesize();
}
+/**
+ * @brief Map the file \p iFid in memory for reading and writing.
+ *
+ * @param[in] iSize Size of the memmory mapped.
+ * @param[in] iFid File which will be mapped in memory.
+ * @param[in] iOffset Start point of the file to be mapped in memory.
+ *
+ * @return Address of the memory map.
+ */
INTERNAL void *SYS_MemoryMap(int iSize, int iFid, int iOffset)
{
@@ -218,6 +327,15 @@
return vAddress;
}
+/**
+ * @brief Map the file \p iFid in memory only for reading.
+ *
+ * @param[in] iSize Size of the memmory mapped.
+ * @param[in] iFid File which will be mapped in memory.
+ * @param[in] iOffset Start point of the file to be mapped in memory.
+ *
+ * @return Address of the memory map.
+ */
INTERNAL void *SYS_PublicMemoryMap(int iSize, int iFid, int iOffset)
{
@@ -228,6 +346,16 @@
return vAddress;
}
+/**
+ * @brief Writes the changes made in a memory map to the disk mapped file.
+ *
+ * @param[in] begin Start of the block to be written
+ * @param[in] lenght Lenght of the block to be written
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 An error ocurred.
+ */
INTERNAL int SYS_MMapSynchronize(void *begin, int length)
{
int flags = 0;
@@ -243,6 +371,16 @@
return fork();
}
+/**
+ * @brief put the process to run in the background.
+ *
+ * @param[in] nochdir if zero, change the current directory to "/".
+ * @param[in] noclose if zero, redirect standard imput/output/error to /dev/nulll.
+ *
+ * @return error code.
+ * @retval 0 success.
+ * @retval -1 an error ocurred.
+ */
INTERNAL int SYS_Daemon(int nochdir, int noclose)
{
#ifdef HAVE_DAEMON
--- /cvsroot/pcsclite/PCSC/src/testpcsc.c 2004/10/03 12:58:55 1.25
+++ /cvsroot/pcsclite/PCSC/src/testpcsc.c 2005/04/12 12:09:08 1.26
@@ -1,6 +1,4 @@
/*
- * This is a test program for pcsc-lite.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999
@@ -8,7 +6,12 @@
* Copyright (C) 2004
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: testpcsc.c,v 1.25 2004/10/03 12:58:55 rousseau Exp $
+ * $Id: testpcsc.c,v 1.26 2005/04/12 12:09:08 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This is a test program for pcsc-lite.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/thread_unix.c 2005/04/12 07:38:44 1.18
+++ /cvsroot/pcsclite/PCSC/src/thread_unix.c 2005/04/12 12:09:08 1.19
@@ -1,6 +1,4 @@
/*
- * This handles thread function abstraction.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2000-2004
@@ -8,7 +6,12 @@
* Damien Sauveron <damien.sauveron@labri.fr>
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: thread_unix.c,v 1.18 2005/04/12 07:38:44 rousseau Exp $
+ * $Id: thread_unix.c,v 1.19 2005/04/12 12:09:08 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This handles thread function abstraction.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/thread_win32.c 2004/08/02 21:52:17 1.6
+++ /cvsroot/pcsclite/PCSC/src/thread_win32.c 2005/04/12 12:09:08 1.7
@@ -1,12 +1,15 @@
/*
- * This handles thread and mutex functions for Windows.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2003
* Jamie Nicolson / Netscape Communications Corporation
*
- * $Id: thread_win32.c,v 1.6 2004/08/02 21:52:17 rousseau Exp $
+ * $Id: thread_win32.c,v 1.7 2005/04/12 12:09:08 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This handles thread and mutex functions for Windows.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/winscard.c 2005/03/01 09:22:52 1.51
+++ /cvsroot/pcsclite/PCSC/src/winscard.c 2005/04/12 12:09:08 1.52
@@ -1,14 +1,80 @@
/*
- * This handles smartcard reader communications.
- * This is the heart of the M$ smartcard API.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999-2004
* David Corcoran <corcoran@linuxnet.com>
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: winscard.c,v 1.51 2005/03/01 09:22:52 rousseau Exp $
+ * $Id: winscard.c,v 1.52 2005/04/12 12:09:08 rousseau Exp $
+ */
+
+/**
+ * @mainpage MUSCLE PC/SC-Lite API Documentation
+ *
+ * @section Introduction
+ *
+ * This document contains the reference API calls for communicating to the MUSCLE
+ * PC/SC Smart Card Resource Manager. PC/SC is a standard proposed by the PC/SC
+ * workgroup [2] which is a conglomerate of representative from major smart card
+ * manufacturers and other companies. This specification tries to abstract the
+ * smart card layer into a high level API so that smart cards and their readers
+ * can be accessed in a homogeneous fashion.
+ *
+ * This toolkit was written in ANSI C that can be used with most compilers and does
+ * NOT use complex and large data structures such as vectors, etc. The C API
+ * emulates the winscard API that is used on the Windows platform. It is contained
+ * in the library libpcsclite.so that is linked to your application.
+ *
+ * I would really like to hear from you. If you have any feedback either on this
+ * documentation or on the MUSCLE project please feel free to email me at:
+ * corcoran@musclecard.com.
+ *
+ *
+ * @section API Routines
+ *
+ * These routines specified here are winscard routines like those in the winscard
+ * API provided under Windows(R). These are compatible with the
+ * Microsoft(R) API calls. This list of calls is mainly an abstraction
+ * of readers. It gives a common API for communication to most readers in a
+ * homogeneous fashion.
+ *
+ * Since all functions can produce a wide array of errors, please refer to ยง Error
+ * codes for a list of error returns.
+ *
+ * For a human readable representation of an error the function
+ * pcsc_stringify_error() is declared in pcsclite.h. This function is not
+ * available on Microsoft(R) winscard API and is pcsc-lite specific.
+ *
+ * @section Internals
+ *
+ * PC/SC Lite is formed by a server deamon (pcscd) and a client library
+ * (libpcsclite.la) that communicate via IPC.
+ *
+ * The file \em winscard_clnt.c in the client-side exposes the API for applications.\n
+ * The file \em winscard.c has the server-side counterpart functions present in
+ * \em winscard_clnt.c.\n
+ * The file \em winscard_msg.c is the communication interface between \em winscard_clnt.c
+ * and \em winscard.c.\n
+ * The file pcscdaemon.c has the main server-side function, including a loop for
+ * accepting client requests.\n
+ * The file \em winscard_svc.c has the functions called by \em pcscdaemon.c to
+ * serve clients requests.
+ *
+ * When a function from \em winscard_clnt.c is called by a client application, it
+ * calls a function in \m winscard_msg.c to send the message to \em pcscdaemon.c.
+ * When \em pcscdaemon.c a client detects a request arrived, it calls \em winscard_svc.c
+ * which identifies what command the message contains and requests \em winscard.c
+ * to execute the command.\n
+ * Meanwhile winscard_clnt.c waits for the response until a timeout occurs.
+ */
+
+/**
+ * @file
+ * @brief This handles smartcard reader communications.
+ * This is the heart of the M$ smartcard API.
+ *
+ * Here are the main server-side functions which execute the requests from the
+ * clients.
*/
#include "config.h"
@@ -28,20 +94,45 @@
#include "sys_generic.h"
#include "eventhandler.h"
-#define SCARD_PROTOCOL_ANY_OLD 0x1000 /* used for backward compatibility */
+/** used for backward compatibility */
+#define SCARD_PROTOCOL_ANY_OLD 0x1000
-/*
- * Some defines for context stack
- */
+/* Some defines for context stack. */
+/** Some defines for context stack. */
#define SCARD_LAST_CONTEXT 1
+/** Some defines for context stack. */
#define SCARD_NO_CONTEXT 0
+/** Some defines for context stack. */
#define SCARD_EXCLUSIVE_CONTEXT -1
+/** Some defines for context stack. */
#define SCARD_NO_LOCK 0
SCARD_IO_REQUEST g_rgSCardT0Pci = { SCARD_PROTOCOL_T0, 8 };
SCARD_IO_REQUEST g_rgSCardT1Pci = { SCARD_PROTOCOL_T1, 8 };
SCARD_IO_REQUEST g_rgSCardRawPci = { SCARD_PROTOCOL_RAW, 8 };
+/**
+ * @brief Creates an Application Context for a client.
+ *
+ * This must be the first function called in a PC/SC application.
+ *
+ * @param[in] dwScope Scope of the establishment.
+ * This can either be a local or remote connection.
+ * <ul>
+ * <li>SCARD_SCOPE_USER - Not used.
+ * <li>SCARD_SCOPE_TERMINAL - Not used.
+ * <li>SCARD_SCOPE_GLOBAL - Not used.
+ * <li>SCARD_SCOPE_SYSTEM - Services on the local machine.
+ * </ul>
+ * @param[in] pvReserved1 Reserved for future use. Can be used for remote connection.
+ * @param[in] pvReserved2 Reserved for future use.
+ * @param[out] phContext Returned Application Context.
+ *
+ * @return Connection status.
+ * @retval SCARD_S_SUCCESS Successful.
+ * @retval SCARD_E_INVALID_VALUE Invalid scope type passed.
+ * @retval SCARD_E_INVALID_PARAMETER phContext is null.
+ */
LONG SCardEstablishContext(DWORD dwScope, LPCVOID pvReserved1,
LPCVOID pvReserved2, LPSCARDCONTEXT phContext)
{
--- /cvsroot/pcsclite/PCSC/src/winscard_clnt.c 2005/03/02 15:12:49 1.54
+++ /cvsroot/pcsclite/PCSC/src/winscard_clnt.c 2005/04/12 12:09:08 1.55
@@ -1,7 +1,4 @@
/*
- * This handles smartcard reader communications and
- * forwarding requests over message queues.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 1999-2004
@@ -9,7 +6,15 @@
* Damien Sauveron <damien.sauveron@labri.fr>
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: winscard_clnt.c,v 1.54 2005/03/02 15:12:49 rousseau Exp $
+ * $Id: winscard_clnt.c,v 1.55 2005/04/12 12:09:08 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This handles smartcard reader communications and
+ * forwarding requests over message queues.
+ *
+ * Here is exposed the API for client applications.
*/
#include "config.h"
@@ -32,12 +37,17 @@
#include "winscard_msg.h"
-#define SCARD_PROTOCOL_ANY_OLD 0x1000 /* used for backward compatibility */
+/** used for backward compatibility */
+#define SCARD_PROTOCOL_ANY_OLD 0x1000
#ifndef min
#define min(a,b) (((a) < (b)) ? (a) : (b))
#endif
+/**
+ * Represents an Application Context Channel.
+ * A channel belongs to an Application Context (\c _psContextMap).
+ */
struct _psChannelMap
{
SCARDHANDLE hCard;
@@ -46,21 +56,45 @@
typedef struct _psChannelMap CHANNEL_MAP, *PCHANNEL_MAP;
+/**
+ * @brief Represents the an Application Context on the Client side.
+ *
+ * An Application Context contains Channels (\c psChannelMap).
+ */
static struct _psContextMap
{
- DWORD dwClientID;
- SCARDCONTEXT hContext;
+ DWORD dwClientID; /** Client Connection ID */
+ SCARDCONTEXT hContext; /** Application Context ID */
DWORD contextBlockStatus;
- PCSCLITE_THREAD_T TID; /* Thread owner of this context */
- PCSCLITE_MUTEX_T mMutex; /* Mutex for this context */
+ PCSCLITE_THREAD_T TID; /** Thread owner of this context */
+ PCSCLITE_MUTEX_T mMutex; /** Mutex for this context */
CHANNEL_MAP psChannelMap[PCSCLITE_MAX_APPLICATION_CONTEXT_CHANNELS];
} psContextMap[PCSCLITE_MAX_APPLICATION_CONTEXTS];
+/**
+ * Make sure the initialization code is executed only once.
+ */
static short isExecuted = 0;
+
+/**
+ * Memory mapped address used to read status information about the readers.
+ * Each element in the vector \c readerStates makes references to a part of
+ * the memory mapped.
+ */
static int mapAddr = 0;
+/**
+ * Ensure that some functions be accessed in thread-safe mode.
+ * These function's names finishes with "TH".
+ */
static PCSCLITE_MUTEX clientMutex = PTHREAD_MUTEX_INITIALIZER;
+/**
+ * Pointers to a memory mapped area used to read status information about the
+ * readers.
+ * Each element in the vector \c readerStates makes references to a part of
+ * the memory mapped \c mapAddr.
+ */
static PREADER_STATE readerStates[PCSCLITE_MAX_READERS_CONTEXTS];
SCARD_IO_REQUEST g_rgSCardT0Pci = { SCARD_PROTOCOL_T0, 8 };
@@ -91,6 +125,38 @@
static LONG SCardEstablishContextTH(DWORD, LPCVOID, LPCVOID, LPSCARDCONTEXT);
+/**
+ * @brief Creates an Application Context to the PC/SC Resource Manager.
+
+ * This must be the first function called in a PC/SC application.
+ * This is a thread-safe wrapper to the function \c SCardEstablishContextTH().
+ *
+ * @param[in] dwScope Scope of the establishment.
+ * This can either be a local or remote connection.
+ * <ul>
+ * <li>SCARD_SCOPE_USER - Not used.
+ * <li>SCARD_SCOPE_TERMINAL - Not used.
+ * <li>SCARD_SCOPE_GLOBAL - Not used.
+ * <li>SCARD_SCOPE_SYSTEM - Services on the local machine.
+ * </ul>
+ * @param[in] pvReserved1 Reserved for future use. Can be used for remote connection.
+ * @param[in] pvReserved2 Reserved for future use.
+ * @param[out] phContext Returned Application Context.
+ *
+ * @return Connection status.
+ * @retval SCARD_S_SUCCESS Successful.
+ * @retval SCARD_E_NO_SERVICE The server is not runing
+ * @retval SCARD_E_INVALID_VALUE Invalid scope type passed.
+ * @retval SCARD_E_INVALID_PARAMETER phContext is null.
+ *
+ * @test
+ * @code
+ * SCARDCONTEXT hContext;
+ * LONG rv;
+ * ...
+ * rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
+ * @endcode
+ */
LONG SCardEstablishContext(DWORD dwScope, LPCVOID pvReserved1,
LPCVOID pvReserved2, LPSCARDCONTEXT phContext)
{
@@ -104,6 +170,31 @@
return rv;
}
+/**
+ * @brief Creates a communication context to the PC/SC Resource
+ * Manager.
+ *
+ * This function shuld not be called directly. Instead, the thread-safe
+ * function \c SCardEstablishContext() should be called.
+ *
+ * @param[in] dwScope Scope of the establishment.
+ * This can either be a local or remote connection.
+ * <ul>
+ * <li>SCARD_SCOPE_USER - Not used.
+ * <li>SCARD_SCOPE_TERMINAL - Not used.
+ * <li>SCARD_SCOPE_GLOBAL - Not used.
+ * <li>SCARD_SCOPE_SYSTEM - Services on the local machine.
+ * </ul>
+ * @param[in] pvReserved1 Reserved for future use. Can be used for remote connection.
+ * @param[in] pvReserved2 Reserved for future use.
+ * @param[out] phContext Returned reference to this connection.
+ *
+ * @return Connection status.
+ * @retval SCARD_S_SUCCESS Successful.
+ * @retval SCARD_E_NO_SERVICE The server is not runing
+ * @retval SCARD_E_INVALID_PARAMETER phContext is null.
+ * @retval SCARD_E_INVALID_VALUE Invalid scope type passed.
+ */
static LONG SCardEstablishContextTH(DWORD dwScope, LPCVOID pvReserved1,
LPCVOID pvReserved2, LPSCARDCONTEXT phContext)
{
@@ -118,11 +209,16 @@
else
*phContext = 0;
+ /* Check if the server is running */
if (SCardCheckDaemonAvailability() != SCARD_S_SUCCESS)
return SCARD_E_NO_SERVICE;
/*
- * Do this only once
+ * Do this only once:
+ * - Initialize debug of need.
+ * - Set up the memory mapped structures for reader states.
+ * - Allocate each reader structure.
+ * - Initialize context struct.
*/
if (isExecuted == 0)
{
@@ -156,7 +252,7 @@
pageSize = SYS_GetPageSize();
/*
- * Allocate each reader structure
+ * Allocate each reader structure in the memory map
*/
for (i = 0; i < PCSCLITE_MAX_READERS_CONTEXTS; i++)
{
@@ -171,6 +267,9 @@
}
}
+ /*
+ * Initializes the application contexts and all channels for each one
+ */
for (i = 0; i < PCSCLITE_MAX_APPLICATION_CONTEXTS; i++)
{
int j;
@@ -210,6 +309,7 @@
return SCARD_E_NO_MEMORY;
}
+ /* Establishes a connection to the server */
if (SHMClientSetupSession(&dwClientID) != 0)
{
SYS_CloseFile(mapAddr);
@@ -258,6 +358,9 @@
return SCARD_E_INVALID_VALUE;
}
+ /*
+ * Try to establish an Application Context with the server
+ */
scEstablishStruct.dwScope = dwScope;
scEstablishStruct.phContext = 0;
@@ -269,7 +372,7 @@
return SCARD_E_NO_SERVICE;
/*
- * Read a message from the server
+ * Read the response from the server
*/
rv = SHMClientRead(&msgStruct, dwClientID, PCSCLITE_CLIENT_ATTEMPTS);
@@ -286,12 +389,29 @@
/*
* Allocate the new hContext - if allocator full return an error
*/
-
rv = SCardAddContext(*phContext, dwClientID);
return rv;
}
+/**
+ * @brief This function destroys a communication context to the PC/SC Resource
+ * Manager. This must be the last function called in a PC/SC application.
+ *
+ * @param[in] hContext Connection context to be closed.
+ *
+ * @return Connection status.
+ * @retval SCARD_S_SUCCESS Successful.
+ *
+ * @test
+ * @code
+ * SCARDCONTEXT hContext;
+ * LONG rv;
+ * ...
+ * rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
+ * rv = SCardReleaseContext(hContext);
+ * @endcode
+ */
LONG SCardReleaseContext(SCARDCONTEXT hContext)
{
LONG rv;
@@ -361,6 +481,18 @@
return scReleaseStruct.rv;
}
+/**
+ * @deprecated
+ * This function is not in Microsoft(R) WinSCard API and is deprecated
+ * in pcsc-lite API.
+ * The function does not do anything except returning \c SCARD_S_SUCCESS.
+ *
+ * @param[in] hContext Connection context to the PC/SC Resource Manager.
+ * @param[in] dwTimeout New timeout value.
+ *
+ * @return Error code.
+ * @retval SCARD_S_SUCCESS Successful.
+ */
LONG SCardSetTimeout(SCARDCONTEXT hContext, DWORD dwTimeout)
{
/*
@@ -370,6 +502,54 @@
return SCARD_S_SUCCESS;
}
+/**
+ * This function establishes a connection to the friendly name of the reader
+ * specified in szReader. The first connection will power up and perform a
+ * reset on the card.
+ *
+ * @param[in] hContext Connection context to the PC/SC Resource Manager.
+ * @param[in] szReader Reader name to connect to.
+ * @param[in] dwShareMode Mode of connection type: exclusive or shared.
+ * <ul>
+ * <li>SCARD_SHARE_SHARED - This application will allow others to share the reader.
+ * <li>SCARD_SHARE_EXCLUSIVE - This application will NOT allow others to share the reader.
+ * <li>SCARD_SHARE_DIRECT - Direct control of the reader, even without a card.
+ * SCARD_SHARE_DIRECT can be used before using SCardControl() to send
+ * control commands to the reader even if a card is not present in
+ * the reader.
+ * </ul>
+ * @param[in] dwPreferredProtocols Desired protocol use.
+ * <ul>
+ * <li>SCARD_PROTOCOL_T0 - Use the T=0 protocol.
+ * <li>SCARD_PROTOCOL_T1 - Use the T=1 protocol.
+ * <li>SCARD_PROTOCOL_RAW - Use with memory type cards.
+ * </ul>
+ * dwPreferredProtocols is a bit mask of acceptable protocols for the
+ * connection. You can use (SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1) if you
+ * do not have a preferred protocol.
+ * @param[out] phCard Handle to this connection.
+ * @param[out] pdwActiveProtocol Established protocol to this connection.
+ *
+ * @return Error code.
+ * @retval SCARD_S_SUCCESS Successful.
+ * @retval SCARD_E_INVALID_HANDLE Invalid hContext handle.
+ * @retval SCARD_E_INVALID_VALUE Invalid sharing mode, requested protocol, or reader name.
+ * @retval SCARD_E_NOT_READY Could not allocate the desired port.
+ * @retval SCARD_E_READER_UNAVAILABLE Could not power up the reader or card.
+ * @retval SCARD_E_SHARING_VIOLATION Someone else has exclusive rights.
+ * @retval SCARD_E_UNSUPPORTED_FEATURE Protocol not supported.
+ *
+ * @test
+ * @code
+ * SCARDCONTEXT hContext;
+ * SCARDHANDLE hCard;
+ * DWORD dwActiveProtocol;
+ * LONG rv;
+ * ...
+ * rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
+ * rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
+ * @endcode
+ */
LONG SCardConnect(SCARDCONTEXT hContext, LPCTSTR szReader,
DWORD dwShareMode, DWORD dwPreferredProtocols, LPSCARDHANDLE phCard,
LPDWORD pdwActiveProtocol)
@@ -464,6 +644,71 @@
return scConnectStruct.rv;
}
+/**
+ * @brief This function reestablishes a connection to a reader that was previously
+ * connected to using SCardConnect().
+ *
+ * In a multi application environment it is possible for an application to reset
+ * the card in shared mode. When this occurs any other application trying to
+ * access certain commands will be returned the value SCARD_W_RESET_CARD. When
+ * this occurs SCardReconnect() must be called in order to acknowledge that
+ * the card was reset and allow it to change it's state accordingly.
+ *
+ * @param[in] hCard Handle to a previous call to connect.
+ * @param[in] dwShareMode Mode of connection type: exclusive/shared.
+ * <ul>
+ * <li>SCARD_SHARE_SHARED - This application will allow others to share the reader.
+ * <li>SCARD_SHARE_EXCLUSIVE - This application will NOT allow others to share the reader.
+ * </ul>
+ * @param[in] dwPreferredProtocols Desired protocol use.
+ * <ul>
+ * <li>SCARD_PROTOCOL_T0 - Use the T=0 protocol.
+ * <li>SCARD_PROTOCOL_T1 - Use the T=1 protocol.
+ * <li>SCARD_PROTOCOL_RAW - Use with memory type cards.
+ * </ul>
+ * \p dwPreferredProtocols is a bit mask of acceptable protocols for
+ * the connection. You can use (SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1)
+ * if you do not have a preferred protocol.
+ * @param[in] dwInitialization Desired action taken on the card/reader.
+ * <ul>
+ * <li>SCARD_LEAVE_CARD - Do nothing.
+ * <li>SCARD_RESET_CARD - Reset the card (warm reset).
+ * <li>SCARD_UNPOWER_CARD - Unpower the card (cold reset).
+ * <li>SCARD_EJECT_CARD - Eject the card.
+ * </ul>
+ * @param[out] pdwActiveProtocol Established protocol to this connection.
+ *
+ * @return Error code.
+ * @retval SCARD_S_SUCCESS Successful.
+ * @retval SCARD_E_INVALID_HANDLE Invalid \p hCard handle.
+ * @retval SCARD_E_NOT_READY Could not allocate the desired port.
+ * @retval SCARD_E_INVALID_VALUE Invalid sharing mode, requested protocol, or reader name.
+ * @retval SCARD_E_READER_UNAVAILABLE The reader has been removed.
+ * @retval SCARD_E_UNSUPPORTED_FEATURE Protocol not supported.
+ * @retval SCARD_E_SHARING_VIOLATION Someone else has exclusive rights.
+ *
+ * @test
+ * @code
+ * SCARDCONTEXT hContext;
+ * SCARDHANDLE hCard;
+ * DWORD dwActiveProtocol, dwSendLength, dwRecvLength;
+ * LONG rv;
+ * BYTE pbRecvBuffer[10];
+ * BYTE pbSendBuffer[] = {0xC0, 0xA4, 0x00, 0x00, 0x02, 0x3F, 0x00};
+ * ...
+ * rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
+ * rv = SCardConnect(hContext, "Reader X", SCARD_SHARE_SHARED, SCARD_PROTOCOL_T0, &hCard, &dwActiveProtocol);
+ * ...
+ * dwSendLength = sizeof(pbSendBuffer);
+ * dwRecvLength = sizeof(pbRecvBuffer);
+ * rv = SCardTransmit(hCard, SCARD_PCI_T0, pbSendBuffer, dwSendLength, &pioRecvPci, pbRecvBuffer, &dwRecvLength);
+ * / * Card has been reset by another application * /
+ * if (rv == SCARD_W_RESET_CARD)
[769 lines skipped]
--- /cvsroot/pcsclite/PCSC/src/winscard_msg.c 2005/04/12 07:38:44 1.27
+++ /cvsroot/pcsclite/PCSC/src/winscard_msg.c 2005/04/12 12:09:09 1.28
@@ -1,6 +1,4 @@
/*
- * This is responsible for client/server transport.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2001-2004
@@ -8,7 +6,16 @@
* Damien Sauveron <damien.sauveron@labri.fr>
* Ludoic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: winscard_msg.c,v 1.27 2005/04/12 07:38:44 rousseau Exp $
+ * $Id: winscard_msg.c,v 1.28 2005/04/12 12:09:09 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This is responsible for client/server communication.
+ *
+ * A file based socket (\c commonSocket) is used to send/receive only messages
+ * among clients and server.\n
+ * The messages' data are passed throw a memory mapped file: \c sharedSegmentMsg.
*/
#include "config.h"
@@ -35,13 +42,42 @@
#include "sys_generic.h"
#include "misc.h"
+/**
+ * Socket to a file, used for clients-server comminication.
+ */
static int commonSocket = 0;
+/**
+ * @brief Wrapper for the \c SHMMessageReceive() function.
+ *
+ * Called by clients to read the server responses.
+ *
+ * @param[out] msgStruct Message read.
+ * @param[in] dwClientID Client socket handle.
+ * @param[in] blockamount Timeout in milliseconds.
+ *
+ * @return Error code.
+ * @retval @see SHMMessageReceive().
+ */
INTERNAL int SHMClientRead(psharedSegmentMsg msgStruct, DWORD dwClientID, int blockamount)
{
return SHMMessageReceive(msgStruct, dwClientID, blockamount);
}
+/**
+ * @brief Prepares a communication channel for the client to talk to the server.
+ *
+ * This is called by the application to create a socket for local IPC with the
+ * server. The socket is associated to the file \c PCSCLITE_CSOCK_NAME.
+ *
+ * @param[out] pdwClientID Client Connection ID.
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 Can not create the socket.
+ * @retval -1 The socket can not open a connection.
+ * @retval -1 Can not set the socket to non-blocking.
+ */
INTERNAL int SHMClientSetupSession(PDWORD pdwClientID)
{
struct sockaddr_un svc_addr;
@@ -79,12 +115,34 @@
return 0;
}
+/**
+ * @brief Closes the socket used by the client to communicate with the server.
+ *
+ * @param[in] dwClientID Client socket handle to be closed.
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ */
INTERNAL int SHMClientCloseSession(DWORD dwClientID)
{
SYS_CloseFile(dwClientID);
return 0;
}
+/**
+ * @brief Prepares the communication channel used by the server to talk to the
+ * clients.
+ *
+ * This is called by the server to create a socket for local IPC with the
+ * clients. The socket is associated to the file \c PCSCLITE_CSOCK_NAME.
+ * Each client will open a connection to this socket.
+ *
+ * @return Error code.
+ * @retval 0 Success
+ * @retval -1 Can not create the socket.
+ * @retval -1 Can not bind the socket to the file \c PCSCLITE_CSOCK_NAME.
+ * @retval -1 Can not put the socket in listen mode.
+ */
INTERNAL int SHMInitializeCommonSegment(void)
{
static struct sockaddr_un serv_adr;
@@ -129,6 +187,18 @@
return 0;
}
+/**
+ * @brief Accepts a Client connection.
+ *
+ * Called by \c SHMProcessEventsServer().
+ *
+ * @param[out] pdwClientID Connection ID used to reference the Client.
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 Can not establish the connection.
+ * @retval -1 Can not set the connection to non-blocking mode.
+ */
INTERNAL int SHMProcessCommonChannelRequest(PDWORD pdwClientID)
{
socklen_t clnt_len;
@@ -161,6 +231,20 @@
return 0;
}
+/**
+ * @brief Looks for messages sent by clients.
+ *
+ * This is called by the Server's function \c SVCServiceRunLoop().
+ *
+ * @param[out] pdwClientID Connection ID used to reference the Client.
+ * @param[in] blockTime Timeout (not used).
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 Error accessing the communication channel.
+ * @retval -1 Can not set the connection to non-blocking mode.
+ * @retval 2 Timeout.
+ */
INTERNAL int SHMProcessEventsServer(PDWORD pdwClientID, int blocktime)
{
fd_set read_fd;
@@ -212,6 +296,11 @@
return -1;
}
+/**
+ * @brief
+ *
+ * Called by \c ContextThread().
+ */
INTERNAL int SHMProcessEventsContext(PDWORD pdwClientID, psharedSegmentMsg msgStruct, int blocktime)
{
fd_set read_fd;
@@ -269,6 +358,15 @@
}
+/**
+ * @brief Sends a menssage from client to server or vice-versa.
+ *
+ * Writes the message in the shared file \c filedes.
+ *
+ * @param[in] msgStruct Message to be sent.
+ * @param[in] filedes Socket handle.
+ * @param[in] blockAmount Timeout in milliseconds.
+ */
INTERNAL int SHMMessageSend(psharedSegmentMsg msgStruct, int filedes,
int blockAmount)
{
@@ -381,6 +479,21 @@
return retval;
}
+/**
+ * @brief Called by the Client to get the reponse from the server or vice-versa.
+ *
+ * Reads the message from the file \c filedes.
+ *
+ * @param[out] msgStruct Message read.
+ * @param[in] filedes Socket handle.
+ * @param[in] blockAmount Timeout in milliseconds.
+ *
+ * @return Error code.
+ * @retval 0 Success.
+ * @retval -1 Timeout.
+ * @retval -1 Socket is closed.
+ * @retval -1 A signal was received.
+ */
INTERNAL int SHMMessageReceive(psharedSegmentMsg msgStruct, int filedes,
int blockAmount)
{
@@ -493,6 +606,22 @@
return retval;
}
+/**
+ * @brief Wrapper for the \c SHMMessageSend() function.
+ *
+ * Called by clients to send messages to the server.
+ * The parameters \p command and \p data are set in the \c sharedSegmentMsg
+ * struct in order to be sent.
+ *
+ * @param[in] command Command to be sent.
+ * @param[in] dwClientID Client socket handle.
+ * @param[in] size Size of the message (\p data).
+ * @param[in] blockAmount Timeout to the operation in ms.
+ * @param[in] data Data to be sent.
+ *
+ * @return Error code.
+ * @retval @see SHMMessageSend().
+ */
INTERNAL int WrapSHMWrite(unsigned int command, DWORD dwClientID,
unsigned int size, unsigned int blockAmount, void *data)
{
@@ -513,6 +642,15 @@
return SHMMessageSend(&msgStruct, dwClientID, blockAmount);
}
+/**
+ * @brief Closes the communications channel used by the server to talk to the
+ * clients.
+ *
+ * The socket used is closed and the file it is bound to is removed.
+ *
+ * @param[in] sockValue Socket to be closed.
+ * @param[in] pcFilePath File used by the socket.
+ */
INTERNAL void SHMCleanupSharedSegment(int sockValue, char *pcFilePath)
{
SYS_CloseFile(sockValue);
--- /cvsroot/pcsclite/PCSC/src/winscard_msg.h 2004/06/17 06:44:01 1.11
+++ /cvsroot/pcsclite/PCSC/src/winscard_msg.h 2005/04/12 12:09:09 1.12
@@ -1,7 +1,4 @@
/*
- * This defines some structures and defines to be used over
- * the transport layer.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2001-2004
@@ -9,13 +6,21 @@
* Damien Sauveron <damien.sauveron@labri.fr>
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: winscard_msg.h,v 1.11 2004/06/17 06:44:01 rousseau Exp $
+ * $Id: winscard_msg.h,v 1.12 2005/04/12 12:09:09 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This defines some structures and #defines to be used over
+ * the transport layer.
*/
#ifndef __winscard_msg_h__
#define __winscard_msg_h__
+/** Major version of the current message protocol */
#define PROTOCOL_VERSION_MAJOR 2
+/** Minor version of the current message protocol */
#define PROTOCOL_VERSION_MINOR 0
#ifdef __cplusplus
@@ -23,12 +28,23 @@
{
#endif
+ /**
+ * @brief General structure for client/serve message data exchange.
+ *
+ * It is used in the calls of \c SHMMessageSend and \c SHMMessageReceive.
+ * The field \c data is interpreted according to the values of the fields
+ * \c mtype and \c command. The possible structs the \c data field can
+ * represent are: \c version_struct \c client_struct \c establish_struct
+ * \c release_struct \c connect_struct \c reconnect_struct
+ * \c disconnect_struct \c begin_struct \c end_struct \c cancel_struct
+ * \c status_struct \c transmit_struct \c control_struct \c getset_struct
+ */
typedef struct rxSharedSegment
{
- unsigned int mtype;
+ unsigned int mtype; /** one of the \c pcsc_adm_commands */
unsigned int user_id;
unsigned int group_id;
- unsigned int command;
+ unsigned int command; /** one of the \c pcsc_msg_commands */
unsigned int dummy; /* was request_id in pcsc-lite <= 1.2.0 */
time_t date;
unsigned char key[PCSCLITE_MSG_KEY_LEN];
@@ -36,6 +52,9 @@
}
sharedSegmentMsg, *psharedSegmentMsg;
+ /**
+ * Command types available to use in the field \c sharedSegmentMsg.mtype.
+ */
enum pcsc_adm_commands
{
CMD_FUNCTION = 0xF1,
@@ -48,6 +67,9 @@
CMD_VERSION = 0xF8
};
+ /**
+ * @brief Commands available to use in the field \c sharedSegmentMsg.command.
+ */
enum pcsc_msg_commands
{
SCARD_ESTABLISH_CONTEXT = 0x01,
@@ -68,6 +90,9 @@
SCARD_SET_ATTRIB = 0x10
};
+ /**
+ * @brief Information transmitted in \c CMD_VERSION Messages.
+ */
struct version_struct
{
int major;
@@ -82,6 +107,11 @@
};
typedef struct client_struct client_struct;
+ /**
+ * @brief Information contained in \c SCARD_ESTABLISH_CONTEXT Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct establish_struct
{
DWORD dwScope;
@@ -90,6 +120,11 @@
};
typedef struct establish_struct establish_struct;
+ /**
+ * @brief Information contained in \c SCARD_RELEASE_CONTEXT Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct release_struct
{
SCARDCONTEXT hContext;
@@ -97,6 +132,11 @@
};
typedef struct release_struct release_struct;
+ /**
+ * @brief contained in \c SCARD_CONNECT Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct connect_struct
{
SCARDCONTEXT hContext;
@@ -109,6 +149,11 @@
};
typedef struct connect_struct connect_struct;
+ /**
+ * @brief contained in \c SCARD_RECONNECT Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct reconnect_struct
{
SCARDHANDLE hCard;
@@ -120,6 +165,11 @@
};
typedef struct reconnect_struct reconnect_struct;
+ /**
+ * @brief contained in \c SCARD_DISCONNECT Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct disconnect_struct
{
SCARDHANDLE hCard;
@@ -128,6 +178,11 @@
};
typedef struct disconnect_struct disconnect_struct;
+ /**
+ * @brief contained in \c SCARD_BEGIN_TRANSACTION Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct begin_struct
{
SCARDHANDLE hCard;
@@ -135,6 +190,11 @@
};
typedef struct begin_struct begin_struct;
+ /**
+ * @brief contained in \c SCARD_END_TRANSACTION Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct end_struct
{
SCARDHANDLE hCard;
@@ -143,6 +203,11 @@
};
typedef struct end_struct end_struct;
+ /**
+ * @brief contained in \c SCARD_CANCEL Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct cancel_struct
{
SCARDHANDLE hCard;
@@ -150,6 +215,11 @@
};
typedef struct cancel_struct cancel_struct;
+ /**
+ * @brief contained in \c SCARD_STATUS Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct status_struct
{
SCARDHANDLE hCard;
@@ -163,6 +233,11 @@
};
typedef struct status_struct status_struct;
+ /**
+ * @brief contained in \c SCARD_TRANSMIT Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct transmit_struct
{
SCARDHANDLE hCard;
@@ -176,6 +251,11 @@
};
typedef struct transmit_struct transmit_struct;
+ /**
+ * @brief contained in \c SCARD_CONTROL Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct control_struct
{
SCARDHANDLE hCard;
@@ -189,6 +269,11 @@
};
typedef struct control_struct control_struct;
+ /**
+ * @brief contained in \c SCARD_GET_ATTRIB and \c Messages.
+ *
+ * These data are passed throw the field \c sharedSegmentMsg.data.
+ */
struct getset_struct
{
SCARDHANDLE hCard;
--- /cvsroot/pcsclite/PCSC/src/winscard_scf.c 2005/02/28 08:49:23 1.19
+++ /cvsroot/pcsclite/PCSC/src/winscard_scf.c 2005/04/12 12:09:10 1.20
@@ -1,6 +1,4 @@
/*
- * This provides PC/SC to SCF shimming.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2002
@@ -9,7 +7,12 @@
* Copyright (C) 2005
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: winscard_scf.c,v 1.19 2005/02/28 08:49:23 rousseau Exp $
+ * $Id: winscard_scf.c,v 1.20 2005/04/12 12:09:10 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This provides PC/SC to SCF shimming.
*/
#include "config.h"
--- /cvsroot/pcsclite/PCSC/src/winscard_svc.c 2005/02/22 14:40:26 1.31
+++ /cvsroot/pcsclite/PCSC/src/winscard_svc.c 2005/04/12 12:09:11 1.32
@@ -1,7 +1,4 @@
/*
- * This demarshalls functions over the message queue and keeps
- * track of clients and their handles.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2001-2004
@@ -9,7 +6,17 @@
* Damien Sauveron <damien.sauveron@labri.fr>
* Ludovic Rousseau <ludovic.rousseau@free.fr>
*
- * $Id: winscard_svc.c,v 1.31 2005/02/22 14:40:26 rousseau Exp $
+ * $Id: winscard_svc.c,v 1.32 2005/04/12 12:09:11 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This demarshalls functions over the message queue and keeps
+ * track of clients and their handles.
+ *
+ * Each Client message is deald by creating a thread (\c CreateContextThread).
+ * The thread establishes reands and demarshalls the message and calls the
+ * appropriate function to threat it.
*/
#include "config.h"
@@ -25,16 +32,24 @@
#include "sys_generic.h"
#include "thread_generic.h"
+/**
+ * @brief Represents the an Application Context on the Server side.
+ *
+ * An Application Context contains Channels (\c hCard).
+ */
static struct _psContext
{
SCARDCONTEXT hContext;
SCARDHANDLE hCard[PCSCLITE_MAX_APPLICATION_CONTEXT_CHANNELS];
- DWORD dwClientID;
- PCSCLITE_THREAD_T pthThread; /* Event polling thread */
- sharedSegmentMsg msgStruct;
- int protocol_major, protocol_minor;
+ DWORD dwClientID; /* Connection ID used to reference the Client. */
+ PCSCLITE_THREAD_T pthThread; /* Event polling thread's ID */
+ sharedSegmentMsg msgStruct; /* Msg sent by the Client */
+ int protocol_major, protocol_minor; /* Protocol number agreed between client and server*/
} psContext[PCSCLITE_MAX_APPLICATIONS_CONTEXTS];
+/**
+ * @brief Index of an avaiable Application Context slot in \c psContext.
+ */
static DWORD dwNextContextIndex;
LONG MSGCheckHandleAssociation(SCARDHANDLE, DWORD);
@@ -53,6 +68,16 @@
return 1;
}
+/**
+ * @brief Creates threads to handle messages received from Clients.
+ *
+ * @param[in] pdwClientID Connection ID used to reference the Client.
+ *
+ * @return Error code.
+ * @retval SCARD_S_SUCCESS Success.
+ * @retval SCARD_F_INTERNAL_ERROR Exceded the maximum number of simultaneous Application Contexts.
+ * @retval SCARD_E_NO_MEMORY Error creating the Context Thread.
+ */
LONG CreateContextThread(PDWORD pdwClientID)
{
int i;
@@ -93,6 +118,14 @@
* connections
*/
+/**
+ * @brief Handles messages received from Clients.
+ *
+ * For each Client message a new instance of this thread is created.
+ *
+ * @param[in] pdwIndex Index of an avaiable Application Context slot in
+ * \c psContext.
+ */
static void ContextThread(DWORD* pdwIndex)
{
LONG rv;
@@ -179,6 +212,21 @@
}
}
+/**
+ * @Find out which message was sent by the Client and execute the right task.
+ *
+ * According to the command type sent by the client (\c pcsc_msg_commands),
+ * cast the message data to the correct struct so that is can be demarshalled.
+ * Then call the appropriate function to handle the request.
+ *
+ * Possible structs are: \c establish_struct \c release_struct
+ * \c connect_struct \c reconnect_struct \c disconnect_struct \c begin_struct
+ * \c cancel_struct \c end_struct \c status_struct \c transmit_struct
+ * \c control_struct \c getset_struct.
+ *
+ * @param[in] msgStruct Message to be demarshalled and executed.
+ * param[in] dwContextIndex
+ */
LONG MSGFunctionDemarshall(psharedSegmentMsg msgStruct, DWORD dwContextIndex)
{
LONG rv;
--- /cvsroot/pcsclite/PCSC/src/winscard_svc.h 2004/06/17 06:44:01 1.6
+++ /cvsroot/pcsclite/PCSC/src/winscard_svc.h 2005/04/12 12:09:11 1.7
@@ -1,14 +1,17 @@
/*
- * This demarshalls functions over the message queue and
- * keeps track of clients and their handles.
- *
* MUSCLE SmartCard Development ( http://www.linuxnet.com )
*
* Copyright (C) 2001-2004
* David Corcoran <corcoran@linuxnet.com>
* Damien Sauveron <damien.sauveron@labri.fr>
*
- * $Id: winscard_svc.h,v 1.6 2004/06/17 06:44:01 rousseau Exp $
+ * $Id: winscard_svc.h,v 1.7 2005/04/12 12:09:11 rousseau Exp $
+ */
+
+/**
+ * @file
+ * @brief This demarshalls functions over the message queue and
+ * keeps track of clients and their handles.
*/
#ifndef __winscard_svc_h__