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

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

Revision: 276
          http://svn.sourceforge.net/pmplib/?rev=276&view=rev
Author:   nyaochi
Date:     2007-01-24 19:06:49 -0800 (Wed, 24 Jan 2007)

Log Message:
-----------
Document playlist reader/writer API.

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

Modified: trunk/pmplib/include/pmp.h
===================================================================
--- trunk/pmplib/include/pmp.h	2007-01-25 02:29:25 UTC (rev 275)
+++ trunk/pmplib/include/pmp.h	2007-01-25 03:06:49 UTC (rev 276)
@@ -398,10 +398,67 @@
 	 */
 	result_t (*get_records)(pmp_music_t* music, pmp_music_record_t* records, uint32_t* num_records);
 
+	/**
+	 * Set a list of music playlists.
+	 *
+	 *	This function sets a list of music playlists. PMPlib will generate the
+	 *	playlists on the device based on this list.
+	 *
+	 *	This function does not write out any content on the player immediately;
+	 *	playlist generation is prolonged until the device is closed by
+	 *	pmp->close() call.
+	 *	
+	 *	@param	music		The pointer to the pmp_music_t interface.
+	 *	@param	playlists	An array of music playlists.
+	 *	@param	num_playlists	The number of elements in \a playlists array.
+	 *	@retval	result_t	The status code after this operation.
+	 *
+	 *	@assert
+	 *		@code music != NULL @endcode
+	 *		@code playlists != NULL @endcode
+	 */
 	result_t (*set_playlists)(pmp_music_t* music, const pmp_playlist_t* playlists, uint32_t num_playlists);
+
+	/**
+	 * Get a list of music playlists.
+	 *
+	 *	This function gets the list of music playlists in the device or set by
+	 *	\a set_playlists call.
+	 *
+	 *	If the argument \a playlists is NULL, this function returns the number
+	 *	of music playlists to the variable whose address is specified by the
+	 *	argument \a num_playlists. You can use this for determining the size of
+	 *	array \a playlists necessary to obtain all playlists.
+	 *
+	 *	If the argument \a playlists is not NULL, this function copies the
+	 *	current music playlists to the array whose address is specified by the
+	 *	argument \a playlists and whose size is specified by the variable
+	 *	pointed by the argument \a num_playlists.
+	 *
+	 *	@param	music		The pointer to the pmp_music_t interface.
+	 *	@param	playlists	An array of music playlists.
+	 *	@param	num_playlists	The pointer to the variable presenting the
+	 *							number of elements in \a playlists array.
+	 *	@retval	result_t	The status code after this operation.
+	 *
+	 *	@assert
+	 *		@code music != NULL @endcode
+	 *		@code num_playlists != NULL @endcode
+	 */
 	result_t (*get_playlists)(pmp_music_t* music, pmp_playlist_t* playlists, uint32_t* num_playlists);
 
-	result_t (*dump)(pmp_music_t* pmpdb, FILE *fp, int level);
+	/**
+	 * Dump the music database.
+	 *
+	 *	@param	music		The pointer to the pmp_music_t interface.
+	 *	@param	fp			The pointer to an output stream.
+	 *	@param	flag		The flags.
+	 *	@retval	result_t	The status code after this operation.
+	 *
+	 *	@assert
+	 *		@code music != NULL @endcode
+	 */
+	result_t (*dump)(pmp_music_t* music, FILE *fp, int flag);
 };
 
 


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