[Pmplib-commits] SF.net SVN: pmplib: [274] trunk/pmplib/include/pmp.h

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

Revision: 274
          http://svn.sourceforge.net/pmplib/?rev=274&view=rev
Author:   nyaochi
Date:     2007-01-24 15:07:42 -0800 (Wed, 24 Jan 2007)

Log Message:
-----------
Document set_records and get_records functions in pmp_music_t.

Modified Paths:
--------------
    trunk/pmplib/include/pmp.h

Modified: trunk/pmplib/include/pmp.h
===================================================================
--- trunk/pmplib/include/pmp.h	2007-01-24 10:26:45 UTC (rev 273)
+++ trunk/pmplib/include/pmp.h	2007-01-24 23:07:42 UTC (rev 274)
@@ -205,6 +205,7 @@
 
 /**
  * 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.
@@ -216,13 +217,15 @@
 struct tag_pmp_t {
 	/**
 	 * Pointer for the internal use.
-	 *	This member variable is reserved for the internal use of the
-	 *	library. Do not modify the value.
+	 *
+	 *	This member variable is reserved for the internal use of the library.
+	 *	Do not modify the value.
 	 */
 	void* instance;
 
 	/**
 	 * Reference counter.
+	 *
 	 *	This member variable is reserved for the library to manage the
 	 *	reference counter. Do not modify the value directly. Call
 	 *	member functions add_ref() and release() to increase and
@@ -232,6 +235,7 @@
 
 	/**
 	 * Open flags.
+	 *
 	 *	This member variable is reserved for the library to store the
 	 *	flags specified in open() function. Do not modify the value.
 	 */
@@ -308,12 +312,92 @@
 	ucs2char_t **entries;
 } pmp_playlist_t;
 
+/**
+ * Interface for organizing music files.
+ *
+ *	This interface is responsible for several operations relevant to music
+ *	files in a portable media device. The major operations are:
+ *	- setting a list of music records for building a music database
+ *	- getting a list of music records from the existing music database
+ *	- dumping the existing music database in a text format
+ *	- setting a list of music files for generating
+ *	- getting a list of music playlists used by the device
+ *
+ *	You cannot create an instance of this structure by yourself. Access
+ *	pmp_t::music member to obtain this interface.
+ */
 struct tag_pmp_music_t {
+	/**
+	 * Pointer for the internal use.
+	 *
+	 *	This member variable is reserved for the internal use of the library.
+	 *	Do not modify the value.
+	 */
 	void* instance;
+
+	/**
+	 * The pointer to pmp_t interface.
+	 *
+	 *	@assert
+	 *		@code this->pmp->music == this @endcode
+	 */
 	pmp_t* pmp;
 
+	/**
+	 * Set a list of music records.
+	 *
+	 *	This function sets a list of music records that provide a complete
+	 *	information about all music files on a device. Based on this list,
+	 *	PMPlib will build a music database on the device.
+	 *
+	 *	This function does not write out any content on the player immediately
+	 *	for the following reason. Some portable devices manage a music database
+	 *	and playlists separately, but some integrate playlist information into
+	 *	a music database. In the latter case, PMPlib cannot build a music
+	 *	database until a definitive list of playlists is obtained. In order to
+	 *	support various devices in a unified interface, this function reserves
+	 *	a future update of the music database; a database update is prolonged
+	 *	until the device is closed by pmp->close() call.
+	 *	
+	 *	@param	music		The pointer to the pmp_music_t interface.
+	 *	@param	records		An array of music records.
+	 *	@param	num_records	The number of elements in \a records array.
+	 *	@retval	result_t	The status code after this operation.
+	 *
+	 *	@assert
+	 *		@code music != NULL @endcode
+	 *		@code records != NULL @endcode
+	 */
 	result_t (*set_records)(pmp_music_t* music, const pmp_music_record_t* records, uint32_t num_records);
+
+	/**
+	 * Get a list of music records.
+	 *
+	 *	This function gets the list of music records in the existing music
+	 *	database or set by \a set_records call.
+	 *
+	 *	If the argument \a records is NULL, this function returns the number of
+	 *	music records to the variable whose address is specified by the
+	 *	argument \a num_records. You can use this for determining the size of
+	 *	array \a records necessary to obtain all records from this function.
+	 *
+	 *	If the argument \a records is not NULL, this function copies the
+	 *	current music records to the array whose address is specified by the
+	 *	argument \a records and whose size is specified by the variable
+	 *	pointed by the argument \a num_records.
+	 *
+	 *	@param	music		The pointer to the pmp_music_t interface.
+	 *	@param	records		An array of music records.
+	 *	@param	num_records	The pointer to the variable presenting the number
+	 *						of elements in \a records array.
+	 *	@retval	result_t	The status code after this operation.
+	 *
+	 *	@assert
+	 *		@code music != NULL @endcode
+	 *		@code num_records != NULL @endcode
+	 */
 	result_t (*get_records)(pmp_music_t* music, pmp_music_record_t* records, uint32_t* num_records);
+
 	result_t (*set_playlists)(pmp_music_t* music, const pmp_playlist_t* playlists, uint32_t num_playlists);
 	result_t (*get_playlists)(pmp_music_t* music, pmp_playlist_t* playlists, uint32_t* num_playlists);
 


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