[Pmplib-commits] SF.net SVN: pmplib: [252] trunk/pmplib

[<ny...@us...>]

Revision: 252
          http://svn.sourceforge.net/pmplib/?rev=252&view=rev
Author:   nyaochi
Date:     2007-01-08 01:01:37 -0800 (Mon, 08 Jan 2007)

Log Message:
-----------
- Documentation for PMPlib Helper API (pmplib_*).
- Define @default and @assert paragraphs in Doxyfile

Modified Paths:
--------------
    trunk/pmplib/doc/Doxyfile
    trunk/pmplib/include/pmp.h
    trunk/pmplib/lib/pmp/pmp.c

Modified: trunk/pmplib/doc/Doxyfile
===================================================================
--- trunk/pmplib/doc/Doxyfile	2007-01-07 19:38:17 UTC (rev 251)
+++ trunk/pmplib/doc/Doxyfile	2007-01-08 09:01:37 UTC (rev 252)
@@ -34,7 +34,8 @@
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 8
-ALIASES                = 
+ALIASES                = "assert=\par Assertions:\n" \
+                         "default=\par Default Value:\n"
 OPTIMIZE_OUTPUT_FOR_C  = YES
 OPTIMIZE_OUTPUT_JAVA   = NO
 BUILTIN_STL_SUPPORT    = NO

Modified: trunk/pmplib/include/pmp.h
===================================================================
--- trunk/pmplib/include/pmp.h	2007-01-07 19:38:17 UTC (rev 251)
+++ trunk/pmplib/include/pmp.h	2007-01-08 09:01:37 UTC (rev 252)
@@ -28,12 +28,26 @@
 #define	PMPAPI	__declspec(dllexport)
 #else
 #define	PMPAPI
-#endif
+#endif/*PMP_EXPORTS*/
 
 #ifdef	__cplusplus
 extern "C" {
 #endif/*__cplusplus*/
 
+
+/**
+ * @mainpage PMPlib API Documentation
+ *
+ *	@section intro Introduction
+ *	
+ *	This is the documentation for the PMPlib API. 
+ */
+
+/** 
+ * \addtogroup pmp PMPlib APIs
+ * @{ 
+ */
+
 /*
  * Forward structure declarations.
  */
@@ -129,7 +143,14 @@
 
 
 /**
- * The root interface for a portable media device.
+ * The root interface for portable media device.
+ *	This structure represents the basic interface that is common to any
+ *	portal media devices. It defines several member variables and pure
+ *	virtual functions to access the implementation for the target device.
+ *	Use pmplib_create() function to obtain the instance suitable for a
+ *	specific device.
+ *
+ *	@see	pmplib_create
  */
 struct tag_pmp_t {
 	/**
@@ -237,6 +258,11 @@
 };
 
 typedef result_t (*pmp_create_t)(pmp_t** pmp, const ucs2char_t* path_to_device, const char *devid);
+
+/**
+ * Prototype for the callback function for receiving device identifiers.
+ *	
+ */
 typedef void (*pmp_enumerate_devid_callback_t)(void *instance, const char *devid);
 typedef result_t (*pmp_enumerate_devid_t)(pmp_enumerate_devid_callback_t callback, void *instance);
 
@@ -245,20 +271,186 @@
 PMPAPI result_t pmp_record_copy(pmp_music_record_t* dst, const pmp_music_record_t* src);
 PMPAPI uint32_t pmp_interlocked_increment(uint32_t* count);
 PMPAPI uint32_t pmp_interlocked_decrement(uint32_t* count);
+PMPAPI void pmp_copy_environment(pmp_environment_t* dst, const pmp_environment_t* src);
 
-struct tag_pmplib_t; typedef struct tag_pmplib_t pmplib_t;
 
+
+
+
+
+/**
+ * @defgroup pmplib PMPlib Helper API
+ *
+ *	This API provides the utility for selecting a PMPlib driver from a number
+ *	of installed ones. Because the PMPlib project implements a number of
+ *	drivers for different portable media devices, an application must choose
+ *	a suitable driver that matches to the target device. Using this API, an
+ *	application can query a driver suitable for the portable media device
+ *	specified by the mount location (root directory of the device) and/or
+ *	string identifier. An application can also enumerate the string
+ *	identifiers of the drivers installed in the system.
+ *
+ *	An application must call pmplib_init() function to initialize the API
+ *	and obtain the pointer to a ::pmplib_t instance that is used for subsequent
+ *	calls of the API.
+ *	The application can query an interface to a PMPlib driver by using
+ *	pmplib_create() function. A list of installed device identifiers is
+ *	obtained by receiving callback notifications invoked by
+ *	pmplib_enumerate_devid() function. The application must terminate this
+ *	API by calling pmplib_finish() function.
+ *
+ *	This is an example of querying an interface to the driver that matches to
+ *	the device connected to the mount point (Win32 path "D:\"):
+ *
+ *	@code
+ * #include <ucs2char.h>
+ * #include <pmp.h>
+ * 
+ * int main(int argc, char *argv[])
+ * {
+ *     result_t ret = 0;
+ *     pmp_t* pmp = NULL;
+ *     pmplib_t* pmplib = NULL;
+ *     static const ucs2char_t path[] = {'D',':','\\',0};
+ *
+ *     // Initialize the PMPlib Helper API.
+ *     if ((ret = pmplib_init(&pmplib)) != 0) {
+ *         // Failed to initialize the API.
+ *         goto error_exit;
+ *     }
+ *
+ *     // Query an interface to the PMPlib driver suitable for the path.
+ *     if ((ret = pmplib_create(pmplib, &pmp, path, NULL)) != 0) {
+ *         // Failed to find a suitable driver.
+ *         goto error_exit;
+ *     }
+ *     
+ *     // Processing with the driver.
+ *     ...
+ *
+ *     // Release the driver.
+ *     pmp->release(pmp);
+ *
+ *     // Terminate the helper API.
+ *     pmplib_finish(pmplib);
+ *     return 0;
+ *
+ * error_exit:
+ *     // Error handling.
+ *     ...
+ *     return 1;
+ * }
+ *	@endcode
+ *
+ *	@{
+ */
+
+struct tag_pmplib_t;
+
+/**
+ * The structure for the PMPlib Helper API.
+ *	An application should use a pointer to this structure as a handle value
+ *	for this API. Call pmplib_init() function to obtain a pointer to this
+ *	structure and pmplib_finish() function to terminate this API. Access to
+ *	a member in this structure is prohibited since it is reserved for the
+ *	internal use of the library implementation only.
+ */
+typedef struct tag_pmplib_t pmplib_t;
+
+/**
+ * Initialize the PMPlib helper library.
+ *
+ *	This function loads the drivers installed in the system to prepare them.
+ *	
+ *	@retval	ptr_pmplib		The pointer to the buffer to receive the pointer
+ *							to the ::pmplib_t instance initialized by this
+ *							function.
+ *	@retval	result_t		The status code.
+ *
+ *	@assert
+ *		@code ptr_pmplib != NULL @endcode
+ *
+ *	@note
+ *		Call this function before using any other functions in this API. 
+ */
 PMPAPI result_t pmplib_init(pmplib_t** ptr_pmplib);
 
+/**
+ * Uninitialize the PMPlib helper library.
+ *
+ *	This function detatch the drivers loaded by pmplib_init() function.
+ *	
+ *	@param	pmplib			The pointer to the ::pmplib_t instance.
+ *	@retval	result_t		The status code.
+ *
+ *	@assert
+ *		@code ptr_pmplib != NULL @endcode
+ *
+ *	@note
+ *		Call this function to terminate this API.
+ */
 PMPAPI result_t pmplib_finish(pmplib_t* pmplib);
 
-PMPAPI result_t pmplib_create(pmplib_t* pmplib, pmp_t** pmp, const ucs2char_t* path_to_device, const char *id);
+/**
+ * Query a driver and create a ::pmp_t instance.
+ *
+ *	This function queries the driver suitable for the portable media device
+ *	specified by the mount location and/or identifier, and returns the
+ *	interface to the driver (::pmp_t instance). An application must specify
+ *	parameter \a path_to_device. If parameter \a id is not \c NULL, this
+ *	function constructs a ::pmp_t instance of the driver with the device
+ *	identifier. If the parameter \a id is \c NULL, this function tries to
+ *	recognize the model of the device based on the content under the location
+ *	(\a path_to_device). If successful, the interface to the driver will be
+ *	returned to the \a pmp argument.
+ *
+ *	@param	pmplib			The pointer to the ::pmplib_t instance.
+ *	@param	path_to_device	A UCS-2 string representing the location of the
+ *							target device. This parameter cannot be \c NULL.
+ *	@param	id				A C-string representing the device identifier of
+ *							the target device. If this argument is \c NULL,
+ *							this function tries to recognize the model of the
+ *							device based on the location (\a path_to_device).
+ *	@retval	ptr_pmp			The pointer to the buffer to receive the pointer
+ *							to the driver interface (::pmp_t instance).
+ *	@retval	result_t		The status code.
+ *
+ *	@assert
+ *		@code pmplib != NULL @endcode
+ *		@code ptr_pmp != NULL @endcode
+ *		@code path_to_device != NULL @endcode
+ */
+PMPAPI result_t pmplib_create(pmplib_t* pmplib, pmp_t** ptr_pmp, const ucs2char_t* path_to_device, const char *id);
 
+/**
+ * Enumerate device identifiers of the installed drivers.
+ *	
+ *	This function enumerates the device identifiers of the installed drivers,
+ *	and invokes the \a callback function for each identifier.
+ *
+ *	@param	pmplib			The pointer to the ::pmplib_t instance.
+ *	@param	callback		The pointer to the callback function to receive
+ *							device identifiers.
+ *	@param	instance		A user-defined instance value. The callback
+ *							function will receive the same value so that it can
+ *							distinguish the caller.
+ *	@retval	result_t		The status code.
+ *
+ *	@assert
+ *		@code pmplib != NULL @endcode
+ *		@code callback != NULL @endcode
+ */
 PMPAPI result_t pmplib_enumerate_devid(pmplib_t* pmplib, pmp_enumerate_devid_callback_t callback, void *instance);
 
-PMPAPI void pmplib_copy_environment(pmp_environment_t* dst,	const pmp_environment_t* src);
+/** 
+ * @} 
+ */
 
+/** 
+ * @} 
+ */
 
+
 #ifdef	__cplusplus
 }
 #endif/*__cplusplus*/

Modified: trunk/pmplib/lib/pmp/pmp.c
===================================================================
--- trunk/pmplib/lib/pmp/pmp.c	2007-01-07 19:38:17 UTC (rev 251)
+++ trunk/pmplib/lib/pmp/pmp.c	2007-01-08 09:01:37 UTC (rev 252)
@@ -63,7 +63,7 @@
 	return 0;
 }
 
-void pmplib_copy_environment(pmp_environment_t* dst, const pmp_environment_t* src)
+void pmp_copy_environment(pmp_environment_t* dst, const pmp_environment_t* src)
 {
 	memcpy(dst, src, sizeof(*src));
 }


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.