vlc_playlist.h:
authorSigmund Augdal Helberg <sigmunau@videolan.org>
Thu, 14 Aug 2003 13:02:55 +0000 (13:02 +0000)
committerSigmund Augdal Helberg <sigmunau@videolan.org>
Thu, 14 Aug 2003 13:02:55 +0000 (13:02 +0000)
   * added a duration field to the playlist item struct
vlc_playlist.h, playlist.c:
   * turned playlist_AddName into playlist_AddExt and made it take an extra
   argument( the duration )
   * doxygenize comments
modules/demux/m3u.c, modules/gui/macosx/playlist.m:
   * use playlist_AddExt

include/vlc_playlist.h
modules/demux/m3u.c
modules/gui/macosx/playlist.m
src/playlist/playlist.c

index 4fa587c..e438e55 100644 (file)
@@ -2,7 +2,7 @@
  * vlc_playlist.h : Playlist functions
  *****************************************************************************
  * Copyright (C) 1999, 2000, 2001, 2002 VideoLAN
- * $Id: vlc_playlist.h,v 1.11 2003/07/23 01:13:47 gbazin Exp $
+ * $Id: vlc_playlist.h,v 1.12 2003/08/14 13:02:55 sigmunau Exp $
  *
  * Authors: Samuel Hocevar <sam@zoy.org>
  *
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
-/*****************************************************************************
- * playlist_item_t: playlist item
- *****************************************************************************/
+/**
+ *  \file
+ *  This file contain structures and function prototypes related
+ *  to the playlist in vlc
+ */
+
+/**
+ * \defgroup vlc_playlist Playlist
+ * Brief description. Longer description
+ * @{
+ */
+
+/**
+ * playlist item
+ * \see playlist_t
+ */
 struct playlist_item_t
 {
-    char *     psz_name;
-    char *     psz_uri; 
-    char **    ppsz_options;
-    int        i_options;
-    int        i_type;   /* unused yet */
-    int        i_status; /* unused yet */
-    vlc_bool_t b_autodeletion;
+    char *     psz_name;       /**< text describing this item */
+    char *     psz_uri;        /**< mrl of this item */
+    mtime_t    i_duration;     /**< A hint about the duration of this
+                                * item, in miliseconds*/
+    char **    ppsz_options;   /**< options passed with the :foo=bar syntax */
+    int        i_options;      /**< number of items in the
+                                * ppsz_options array */
+    int        i_type;         /**< unused yet */
+    int        i_status;       /**< unused yet */
+    vlc_bool_t b_autodeletion; /**< Indicates wether this item is to
+                                * be deleted after playback. True mean
+                                * that this item is to be deleted
+                                * after playback, false otherwise */
 };
 
-/*****************************************************************************
- * playlist_t: playlist structure
- *****************************************************************************
- * The structure contains information about the size and browsing mode of
- * the playlist, a change lock, a dynamic array of playlist items, and a
- * current item which is an exact copy of one of the array members.
- *****************************************************************************/
+/**
+ * Playlist status
+ */
+typedef enum { PLAYLIST_STOPPED,PLAYLIST_RUNNING,PLAYLIST_PAUSED } playlist_status_t;
+
+/**
+ * Structure containing information about the playlist
+ */
 struct playlist_t
 {
     VLC_COMMON_MEMBERS
+/**
+   \name playlist_t
+   These members are uniq to playlist_t
+*/
+/*@{*/
+    int                   i_index;  /**< current index into the playlist */
+    playlist_status_t     i_status; /**< current status of playlist */
+    int                   i_size;   /**< total size of the list */
 
-    int                   i_index;                          /* current index */
-    int                   i_status;
-    int                   i_size;                              /* total size */
-
-    playlist_item_t **    pp_items;
+    playlist_item_t **    pp_items; /**< array of pointers to the
+                                     * playlist items */
 
-    input_thread_t *      p_input;
+    input_thread_t *      p_input;  /**< the input thread ascosiated
+                                     * with the current item */
+    /*@}*/
 };
 
-/*****************************************************************************
- * Playlist status
- *****************************************************************************/
-#define PLAYLIST_STOPPED 0
-#define PLAYLIST_RUNNING 1
-#define PLAYLIST_PAUSED  2
-
 /*****************************************************************************
  * Prototypes
  *****************************************************************************/
@@ -76,16 +96,21 @@ void           playlist_Destroy  ( playlist_t * );
 #define playlist_Prev(p) playlist_Command(p,PLAYLIST_SKIP,-1)
 #define playlist_Skip(p,i) playlist_Command(p,PLAYLIST_SKIP,i)
 #define playlist_Goto(p,i) playlist_Command(p,PLAYLIST_GOTO,i)
-VLC_EXPORT( void, playlist_Command, ( playlist_t *, int, int ) );
+VLC_EXPORT( void, playlist_Command, ( playlist_t *, playlist_command_t, int ) );
 
 VLC_EXPORT( int,  playlist_Add,    ( playlist_t *, const char *, const char **, int, int, int ) );
-VLC_EXPORT( int,  playlist_AddName, (playlist_t *,const char *,const char *, const char **, int, int,int ) );
+VLC_EXPORT( int,  playlist_AddExt,    ( playlist_t *, const char *, const char *, mtime_t, const char **, int, int, int ) );
 VLC_EXPORT( int,  playlist_AddItem, ( playlist_t *, playlist_item_t *, int, int ) );
 VLC_EXPORT( int,  playlist_Delete, ( playlist_t *, int ) );
 VLC_EXPORT( int,  playlist_Move, ( playlist_t *, int, int ) );
 VLC_EXPORT( int,  playlist_LoadFile, ( playlist_t *, const char * ) );
 VLC_EXPORT( int,  playlist_SaveFile, ( playlist_t *, const char * ) );
 
+/**
+ *  tell if a playlist is currently playing.
+ *  \param p_playlist the playlist to check
+ *  \return true if playlist is playing, false otherwise
+ */
 static inline vlc_bool_t playlist_IsPlaying( playlist_t * p_playlist )
 {
     vlc_bool_t b_playing;
@@ -97,6 +122,11 @@ static inline vlc_bool_t playlist_IsPlaying( playlist_t * p_playlist )
     return( b_playing );
 }
 
+/**
+ *  tell if a playlist is currently empty
+ *  \param p_playlist the playlist to check
+ *  \return true if the playlist is empty, false otherwise
+ */
 static inline vlc_bool_t playlist_IsEmpty( playlist_t * p_playlist )
 {
     vlc_bool_t b_empty;
@@ -107,3 +137,7 @@ static inline vlc_bool_t playlist_IsEmpty( playlist_t * p_playlist )
 
     return( b_empty );
 }
+
+/**
+ * @}
+ */
index e3dd77e..0eacb48 100644 (file)
@@ -2,7 +2,7 @@
  * m3u.c: a meta demux to parse pls, m3u, asx et b4s playlists
  *****************************************************************************
  * Copyright (C) 2001 VideoLAN
- * $Id: m3u.c,v 1.23 2003/07/23 01:13:47 gbazin Exp $
+ * $Id: m3u.c,v 1.24 2003/08/14 13:02:55 sigmunau Exp $
  *
  * Authors: Sigmund Augdal <sigmunau@idi.ntnu.no>
  *          Gildas Bazin <gbazin@netcourrier.com>
@@ -551,9 +551,9 @@ static void ProcessLine ( input_thread_t *p_input, playlist_t *p_playlist,
 
     if( b_next && *ppsz_uri )
     {
-        playlist_AddName( p_playlist,
-                          *ppsz_name ? *ppsz_name : *ppsz_uri, *ppsz_uri,
-                          0, 0, PLAYLIST_INSERT, *pi_position );
+        playlist_AddExt( p_playlist, *ppsz_uri,
+                         *ppsz_name ? *ppsz_name : *ppsz_uri, -1, 
+                         0, 0, PLAYLIST_INSERT, *pi_position );
         (*pi_position)++;
         if( *ppsz_name )
         {
index cfe780a..5cc8683 100644 (file)
@@ -2,7 +2,7 @@
  * playlist.m: MacOS X interface plugin
  *****************************************************************************
  * Copyright (C) 2002-2003 VideoLAN
- * $Id: playlist.m,v 1.29 2003/07/27 23:05:41 hartman Exp $
+ * $Id: playlist.m,v 1.30 2003/08/14 13:02:55 sigmunau Exp $
  *
  * Authors: Jon Lech Johansen <jon-vl@nanocrew.net>
  *          Derk-Jan Hartman <thedj@users.sourceforge.net>
@@ -335,7 +335,7 @@ int MacVersion102 = -1;
             }
         }
         
-        playlist_AddName( p_playlist, [o_url fileSystemRepresentation], [o_name UTF8String],
+        playlist_AddExt( p_playlist, [o_name UTF8String], [o_url fileSystemRepresentation], -1, 
             (ppsz_options != NULL ) ? (const char **)ppsz_options : 0, i_total_options,
             i_mode, i_position == -1 ? PLAYLIST_END : i_position + i_item );
 
index 44cc833..17bc089 100644 (file)
@@ -2,7 +2,7 @@
  * playlist.c : Playlist management functions
  *****************************************************************************
  * Copyright (C) 1999-2001 VideoLAN
- * $Id: playlist.c,v 1.43 2003/07/23 01:13:48 gbazin Exp $
+ * $Id: playlist.c,v 1.44 2003/08/14 13:02:55 sigmunau Exp $
  *
  * Authors: Samuel Hocevar <sam@zoy.org>
  *
@@ -42,11 +42,13 @@ static void PlayItem  ( playlist_t * );
 
 static void Poubellize ( playlist_t *, input_thread_t * );
 
-/*****************************************************************************
- * playlist_Create: create playlist
- *****************************************************************************
+/**
+ * Create playlist
+ *
  * Create a playlist structure.
- *****************************************************************************/
+ * \param p_parent the vlc object that is to be the parent of this playlist
+ * \return a pointer to the created playlist, or NULL on error
+ */
 playlist_t * __playlist_Create ( vlc_object_t *p_parent )
 {
     playlist_t *p_playlist;
@@ -90,11 +92,12 @@ playlist_t * __playlist_Create ( vlc_object_t *p_parent )
     return p_playlist;
 }
 
-/*****************************************************************************
- * playlist_Destroy: destroy the playlist
- *****************************************************************************
+/**
+ * Destroy the playlist.
+ *
  * Delete all items in the playlist and free the playlist structure.
- *****************************************************************************/
+ * \param p_playlist the playlist structure to destroy
+ */
 void playlist_Destroy( playlist_t * p_playlist )
 {
     p_playlist->b_die = 1;
@@ -106,30 +109,38 @@ void playlist_Destroy( playlist_t * p_playlist )
     vlc_object_destroy( p_playlist );
 }
 
-/*****************************************************************************
- * playlist_Add: add an item to the playlist
- *****************************************************************************
- * Add an item to the playlist at position i_pos. If i_pos is PLAYLIST_END,
- * add it at the end regardless of the playlist current size.
- *****************************************************************************/
+/**
+ * Add an MRL to the playlist. This is a simplified version of
+ * playlist_AddExt inculded for convenince. It equals calling playlist_AddExt
+ * with psz_name == psz_target and i_duration == -1
+ */
+
 int playlist_Add( playlist_t *p_playlist, const char *psz_target,
                   const char **ppsz_options, int i_options,
                   int i_mode, int i_pos )
 {
-    return playlist_AddName( p_playlist, psz_target, psz_target,
-                             ppsz_options, i_options, i_mode, i_pos );
+    return playlist_AddExt( p_playlist, psz_target, psz_target, -1,
+                            ppsz_options, i_options, i_mode, i_pos );
 }
 
-/*****************************************************************************
- * playlist_AddName: add an item to the playlist with his name
- *****************************************************************************
- * Add an item to the playlist at position i_pos. If i_pos is PLAYLIST_END,
- * add it at the end regardless of the playlist current size.
- *****************************************************************************/
-int playlist_AddName( playlist_t *p_playlist, const char *psz_name, 
-                      const char *psz_uri,
-                      const char **ppsz_options, int i_options,
-                      int i_mode, int i_pos )
+/**
+ * Add a MRL into the playlist.
+ *
+ * \param p_playlist the playlist to add into
+ * \param psz_target the mrl to add to the playlist
+ * \param psz_name a text giving a name or description of this item
+ * \param i_duration a hint about the duration of this item, in miliseconds, or
+ *        -1 if unknown.
+ * \param i_mode the mode used when adding
+ * \param i_pos the possition in the playlist where to add. If this is
+ *        PLAYLIST_END the item will be added at the end of the playlist
+ *        regardless of it's size
+ * \return always returns 0
+*/
+int playlist_AddExt( playlist_t *p_playlist, const char * psz_uri,
+                     const char * psz_name, mtime_t i_duration,
+                     const char **ppsz_options, int i_options, int i_mode,
+                     int i_pos )
 {
     playlist_item_t * p_item;
 
@@ -141,6 +152,7 @@ int playlist_AddName( playlist_t *p_playlist, const char *psz_name,
 
     p_item->psz_name = strdup( psz_name );
     p_item->psz_uri  = strdup( psz_uri );
+    p_item->i_duration = i_duration;
     p_item->i_type = 0;
     p_item->i_status = 0;
     p_item->b_autodeletion = VLC_FALSE;
@@ -161,6 +173,17 @@ int playlist_AddName( playlist_t *p_playlist, const char *psz_name,
     return playlist_AddItem( p_playlist, p_item, i_mode, i_pos );
 }
 
+/**
+ * Add a playlist item into a playlist
+ *
+ * \param p_playlist the playlist to insert into
+ * \param p_item the playlist item to insert
+ * \param i_mode the mode used when adding
+ * \param i_pos the possition in the playlist where to add. If this is
+ *        PLAYLIST_END the item will be added at the end of the playlist
+ *        regardless of it's size
+ * \return always returns 0
+*/
 int playlist_AddItem( playlist_t *p_playlist, playlist_item_t * p_item,
                 int i_mode, int i_pos)
 {
@@ -280,11 +303,13 @@ int playlist_AddItem( playlist_t *p_playlist, playlist_item_t * p_item,
     return 0;
 }
 
-/*****************************************************************************
- * playlist_Delete: delete an item from the playlist
- *****************************************************************************
- * Delete the item in the playlist with position i_pos.
- *****************************************************************************/
+/**
+ * delete an item from a playlist.
+ *
+ * \param p_playlist the playlist to remove from.
+ * \param i_pos the position of the item to remove
+ * \return returns 0
+ */
 int playlist_Delete( playlist_t * p_playlist, int i_pos )
 {
     vlc_value_t     val;
@@ -335,12 +360,17 @@ int playlist_Delete( playlist_t * p_playlist, int i_pos )
     return 0;
 }
 
-/*****************************************************************************
- * playlist_Move: move an item in the playlist
- *****************************************************************************
+/**
+ * Move an item in a playlist
+ *
  * Move the item in the playlist with position i_pos before the current item
  * at position i_newpos.
- *****************************************************************************/
+ * \param p_playlist the playlist to move items in
+ * \param i_pos the position of the item to move
+ * \param i_newpos the position of the item that will be behind the moved item
+ *        after the move
+ * \return returns 0
+ */
 int playlist_Move( playlist_t * p_playlist, int i_pos, int i_newpos)
 {
     vlc_value_t     val;
@@ -400,12 +430,15 @@ int playlist_Move( playlist_t * p_playlist, int i_pos, int i_newpos)
     return 0;
 }
 
-/*****************************************************************************
- * playlist_Command: do a playlist action
- *****************************************************************************
+/**
+ * Do a playlist action
  *
- *****************************************************************************/
-void playlist_Command( playlist_t * p_playlist, int i_command, int i_arg )
+ * \param p_playlist the playlist to do the command on
+ * \param i_command the command to do
+ * \param i_arg the argument to the command. See playlist_command_t for details
+ */
+ void playlist_Command( playlist_t * p_playlist, playlist_command_t i_command,
+                       int i_arg )
 {
     vlc_mutex_lock( &p_playlist->object_lock );
 
@@ -470,7 +503,6 @@ void playlist_Command( playlist_t * p_playlist, int i_command, int i_arg )
 
     return;
 }
-
 /* Following functions are local */
 
 /*****************************************************************************