[Pcsclite-cvs-commit] PCSC/doc ifdhandler-3.tex,1.1,1.2

rousseau@haydn.debian.org rousseau@haydn.debian.org


Update of /cvsroot/pcsclite/PCSC/doc
In directory haydn:/tmp/cvs-serv10528

Modified Files:
	ifdhandler-3.tex 
Log Message:
- add documentation for LTPBundleFindValueWithKey, debug_msg and debug_xxd
- ifdhandler.h moved in PCSC/ifdhandler.h


Index: ifdhandler-3.tex
===================================================================
RCS file: /cvsroot/pcsclite/PCSC/doc/ifdhandler-3.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- ifdhandler-3.tex	10 May 2004 12:49:45 -0000	1.1
+++ ifdhandler-3.tex	11 Jun 2004 07:40:56 -0000	1.2
@@ -47,7 +47,7 @@
 \title{MUSCLE PC/SC IFD Driver API}
 \author{David Corcoran \& Ludovic Rousseau\\
 \url{corcoran@musclecard.com}, \url{ludovic.rousseau@free.fr}}
-\date{May 10, 2004}
+\date{June 11, 2004}
 
 \begin{document}
 
@@ -73,7 +73,7 @@
 \hline
 3.0.1 & August 9, 2004 & latest PDF only version \\
 \hline
-3.1.0 & May 7, 2004 & reformat using \LaTeX{} and correct bugs \\
+3.1.0 & June 11, 2004 & reformat using \LaTeX{} and correct bugs \\
 \hline
 \end{tabular}
 
@@ -314,7 +314,7 @@
 \synopsis
 
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHCreateChannel(DWORD Lun,
     DWORD Channel);
@@ -389,7 +389,7 @@
 
 \synopsis
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHCreateChannelByName(DWORD Lun,
     LPSTR deviceName);
@@ -464,7 +464,7 @@
 
 \synopsis
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHCloseChannel(DWORD Lun);
 \end{verbatim}
@@ -495,7 +495,7 @@
 
 \synopsis
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHGetCapabilities(DWORD Lun,
     DWORD Tag,
@@ -562,7 +562,7 @@
 
 \synopsis
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHSetCapabilities(DWORD Lun,
     DWORD Tag,
@@ -609,7 +609,7 @@
 
 \synopsis
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHSetProtocolParameters(DWORD Lun,
     DWORD Protocol,
@@ -670,7 +670,7 @@
 
 \synopsis
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHPowerICC(DWORD Lun,
     DWORD Action,
@@ -747,7 +747,7 @@
 
 \synopsis
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHTransmitToICC(DWORD Lun,
     SCARD_IO_HEADER SendPci,
@@ -847,7 +847,7 @@
 
 \synopsis
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHControl(DWORD Lun,
     DWORD dwControlCode,
@@ -916,7 +916,7 @@
 
 \synopsis
 \begin{verbatim}
-#include <ifdhandler.h>
+#include <PCSC/ifdhandler.h>
 
 RESPONSECODE IFDHICCPresence(DWORD Lun);
 \end{verbatim}
@@ -942,6 +942,115 @@
 \texttt{IFD\_ICC\_NOT\_PRESENT} & ICC is not present\\
 \texttt{IFD\_COMMUNICATION\_ERROR} & An error has occurred
 \end{tabular}
+
+
+%---------%---------%---------%---------%---------%---------%---------
+\section{API provided by pcsc-lite}
+
+pcsc-lite also provides some API to ease the development of the driver.
+
+
+%---------%---------%---------%---------%---------%---------
+\subsection{LTPBundleFindValueWithKey}
+
+\synopsis
+\begin{verbatim}
+#include <PCSC/parser.h>
+
+int LTPBundleFindValueWithKey(char *fileName,
+    char *tokenKey,
+    char *tokenValue,
+    int tokenIndice);
+\end{verbatim}
+
+\parameters
+
+\begin{tabular}{lll}
+\texttt{fileName} & IN & configuration file name \\
+\texttt{tokenKey} & IN & searched token string \\
+\texttt{tokenValue} & OUT & found token value \\
+\texttt{tokenIndice} & IN & indice of the desired token in an array \\
+\end{tabular}
+
+\desc
+
+This function is used to parse the \texttt{Info.plist} configuration
+file. The \texttt{tokenIndice} field is used to get the n-th element of
+an array.
+
+\returns
+
+\begin{tabular}{ll}
+\texttt{-1} & Error\\
+\texttt{0} & No error \\
+\texttt{1} & Configuration file not found \\
+\end{tabular}
+
+
+%---------%---------%---------%---------%---------%---------
+\subsection{debug\_msg}
+
+\synopsis
+\begin{verbatim}
+#include <PCSC/debuglog.h>
+
+void debug_msg(const char *fmt,
+    ...);
+\end{verbatim}
+
+\parameters
+
+\begin{tabular}{lll}
+\texttt{fmt} & IN & format string as in \texttt{printf()} \\
+\texttt{...} & IN & optionnal parameters as in \texttt{printf()} \\
+\end{tabular}
+
+\desc
+
+This function is used by the driver to send debug information. The
+advantage of using the same debug function as pcsc-lite is that you also
+benefit from the debug redirection provided by pcsc-lite. For example
+you can use \texttt{pcscd --foreground} to start \texttt{pcscd} and keep
+it in the forground with the debug sent to stderr. You will then get
+\texttt{pcscd} and the driver' debug messages in the same place.
+
+\example
+\begin{verbatim}
+#define DebugLogB(fmt, data) debug_msg("%s:%d:%s " fmt, \
+    __FILE__, __LINE__, __FUNCTION__, data)
+
+DebugLogB("received bytes: %d", r);
+\end{verbatim}
+
+
+%---------%---------%---------%---------%---------%---------
+\subsection{debug\_xxd}
+
+\synopsis
+\begin{verbatim}
+#include <PCSC/debuglog.h>
+
+void debug_xxd(const char *msg,
+    const unsigned char *buffer,
+    const int size);
+\end{verbatim}
+
+\parameters
+
+\begin{tabular}{lll}
+\texttt{msg} & IN & text string \\
+\texttt{buffer} & IN & buffer you want to dump in hex \\
+\texttt{size} & IN & size of the buffer \\
+\end{tabular}
+
+\desc
+
+Same idea as \texttt{debug\_msg()} put print the hex dump of a buffer.
+
+\example
+\begin{verbatim}
+debug_xxd("received frame: ", buff, buff_size);
+\end{verbatim}
 
 
 %---------%---------%---------%---------%---------%---------%---------