[Pcsclite-cvs-commit] r3057 - /trunk/PCSC/src/winscard_clnt.c

[rousseau at users.alioth.debian.org]

Author: rousseau
Date: Mon Jul  7 08:46:26 2008
New Revision: 3057

URL: http://svn.debian.org/wsvn/pcsclite/?sc=1&rev=3057
Log:
Doxygen document the use of SCARD_AUTOALLOCATE for SCardListReaders()
and SCardListReaderGroups()

Modified:
    trunk/PCSC/src/winscard_clnt.c

Modified: trunk/PCSC/src/winscard_clnt.c
URL: http://svn.debian.org/wsvn/pcsclite/trunk/PCSC/src/winscard_clnt.c?rev=3057&op=diff
==============================================================================
--- trunk/PCSC/src/winscard_clnt.c (original)
+++ trunk/PCSC/src/winscard_clnt.c Mon Jul  7 08:46:26 2008
@@ -2973,10 +2973,14 @@
 
 /**
  * This function returns a list of currently available readers on the system.
+ *
  * \p mszReaders is a pointer to a character string that is allocated by the
  * application.  If the application sends \p mszGroups and \p mszReaders as
  * NULL then this function will return the size of the buffer needed to
  * allocate in \p pcchReaders.
+ *
+ * If \c *pcchReaders is equal to \ref SCARD_AUTOALLOCATE then the function
+ * will allocate itself the needed memory. Use SCardFreeMemory() to release it.
  *
  * @ingroup API
  * @param[in] hContext Connection context to the PC/SC Resource Manager.
@@ -3003,6 +3007,18 @@
  * mszReaders = malloc(sizeof(char)*dwReaders);
  * rv = SCardListReaders(hContext, NULL, mszReaders, &dwReaders);
  * @endcode
+ *
+ * @code
+ * SCARDCONTEXT hContext;
+ * LPSTR mszReaders;
+ * DWORD dwReaders;
+ * LONG rv;
+ * ...
+ * rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
+ * dwReaders = SCARD_AUTOALLOCATE
+ * rv = SCardListReaders(hContext, NULL, (LPSTR)&mszReaders, &dwReaders);
+ * rv = SCardFreeMemory(hContext, mszReaders);
+ * @endcode
  */
 LONG SCardListReaders(SCARDCONTEXT hContext, LPCSTR mszGroups,
 	LPSTR mszReaders, LPDWORD pcchReaders)
@@ -3152,6 +3168,10 @@
  * The group names is a multi-string and separated by a nul character (\c
  * '\\0') and ended by a double nul character like
  * \c "SCard$DefaultReaders\\0Group 2\\0\\0".
+ *
+ * If \c *pcchGroups is equal to \ref SCARD_AUTOALLOCATE then the function
+ * will allocate itself the needed memory. Use SCardFreeMemory() to release it.
+ *
  * @ingroup API
  * @param[in] hContext Connection context to the PC/SC Resource Manager.
  * @param[out] mszGroups List of groups to list readers.
@@ -3174,6 +3194,18 @@
  * rv = SCardListReaderGroups(hContext, NULL, &dwGroups);
  * mszGroups = malloc(sizeof(char)*dwGroups);
  * rv = SCardListReaderGroups(hContext, mszGroups, &dwGroups);
+ * @endcode
+ *
+ * @code
+ * SCARDCONTEXT hContext;
+ * LPSTR mszGroups;
+ * DWORD dwGroups;
+ * LONG rv;
+ * ...
+ * rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
+ * dwGroups = SCARD_AUTOALLOCATE;
+ * rv = SCardListReaderGroups(hContext, (LPSTR)&mszGroups, &dwGroups);
+ * rv = SCardFreeMemory(hContext, mszGroups);
  * @endcode
  */
 LONG SCardListReaderGroups(SCARDCONTEXT hContext, LPSTR mszGroups,