X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media_list.h;h=32304ee4304c2fb3272a922947123884a1f59f07;hb=fd3ef9055df9088e6c1fd544a9d26a71f465d0cb;hp=1274df2dd94d64575ca855b0b703f95a51c892c0;hpb=5766213f77a685253976323373e9b11998c8aa0a;p=vlc

diff --git a/include/vlc/libvlc_media_list.h b/include/vlc/libvlc_media_list.h
index 1274df2dd9..32304ee430 100644
--- a/include/vlc/libvlc_media_list.h
+++ b/include/vlc/libvlc_media_list.h
@@ -33,27 +33,22 @@
 extern "C" {
 # endif
 
-/*****************************************************************************
- * Media List
- *****************************************************************************/
-/** \defgroup libvlc_media_list libvlc_media_list
+/** \defgroup libvlc_media_list LibVLC media list
  * \ingroup libvlc
- * LibVLC Media List, a media list holds multiple media descriptors
+ * A LibVLC media list holds multiple @ref libvlc_media_t media descriptors.
  * @{
  */
 
 typedef struct libvlc_media_list_t libvlc_media_list_t;
-typedef struct libvlc_media_list_view_t libvlc_media_list_view_t;
 
 /**
  * Create an empty media list.
  *
- * \param p_libvlc libvlc instance
- * \param p_e an initialized exception pointer
- * \return empty media list
+ * \param p_instance libvlc instance
+ * \return empty media list, or NULL on error
  */
 VLC_PUBLIC_API libvlc_media_list_t *
-    libvlc_media_list_new( libvlc_instance_t *, libvlc_exception_t * );
+    libvlc_media_list_new( libvlc_instance_t *p_instance );
 
 /**
  * Release media list created with libvlc_media_list_new().
@@ -61,7 +56,7 @@ VLC_PUBLIC_API libvlc_media_list_t *
  * \param p_ml a media list created with libvlc_media_list_new()
  */
 VLC_PUBLIC_API void
-    libvlc_media_list_release( libvlc_media_list_t * );
+    libvlc_media_list_release( libvlc_media_list_t *p_ml );
 
 /**
  * Retain reference to a media list
@@ -69,12 +64,11 @@ VLC_PUBLIC_API void
  * \param p_ml a media list created with libvlc_media_list_new()
  */
 VLC_PUBLIC_API void
-    libvlc_media_list_retain( libvlc_media_list_t * );
+    libvlc_media_list_retain( libvlc_media_list_t *p_ml );
 
-VLC_DEPRECATED_API void
-    libvlc_media_list_add_file_content( libvlc_media_list_t * p_mlist,
-                                        const char * psz_uri,
-                                        libvlc_exception_t * p_e );
+VLC_DEPRECATED_API int
+    libvlc_media_list_add_file_content( libvlc_media_list_t * p_ml,
+                                        const char * psz_uri );
 
 /**
  * Associate media instance with this media list instance.
@@ -82,13 +76,10 @@ VLC_DEPRECATED_API void
  * The libvlc_media_list_lock should NOT be held upon entering this function.
  *
  * \param p_ml a media list instance
- * \param p_mi media instance to add
- * \param p_e initialized exception object
+ * \param p_md media instance to add
  */
 VLC_PUBLIC_API void
-    libvlc_media_list_set_media( libvlc_media_list_t *,
-                                            libvlc_media_t *,
-                                            libvlc_exception_t *);
+libvlc_media_list_set_media( libvlc_media_list_t *p_ml, libvlc_media_t *p_md );
 
 /**
  * Get media instance from this media list instance. This action will increase
@@ -96,63 +87,55 @@ VLC_PUBLIC_API void
  * The libvlc_media_list_lock should NOT be held upon entering this function.
  *
  * \param p_ml a media list instance
- * \param p_e initialized exception object
  * \return media instance
  */
 VLC_PUBLIC_API libvlc_media_t *
-    libvlc_media_list_media( libvlc_media_list_t *,
-                                        libvlc_exception_t *);
+    libvlc_media_list_media( libvlc_media_list_t *p_ml );
 
 /**
  * Add media instance to media list
  * The libvlc_media_list_lock should be held upon entering this function.
  *
  * \param p_ml a media list instance
- * \param p_mi a media instance
- * \param p_e initialized exception object
+ * \param p_md a media instance
+ * \return 0 on success, -1 if the media list is read-only
  */
-VLC_PUBLIC_API void
-    libvlc_media_list_add_media( libvlc_media_list_t *,
-                                            libvlc_media_t *,
-                                            libvlc_exception_t * );
+VLC_PUBLIC_API int
+libvlc_media_list_add_media( libvlc_media_list_t *p_ml, libvlc_media_t *p_md );
 
 /**
  * Insert media instance in media list on a position
  * The libvlc_media_list_lock should be held upon entering this function.
  *
  * \param p_ml a media list instance
- * \param p_mi a media instance
+ * \param p_md a media instance
  * \param i_pos position in array where to insert
- * \param p_e initialized exception object
+ * \return 0 on success, -1 if the media list si read-only
  */
-VLC_PUBLIC_API void
-    libvlc_media_list_insert_media( libvlc_media_list_t *,
-                                               libvlc_media_t *,
-                                               int,
-                                               libvlc_exception_t * );
+VLC_PUBLIC_API int
+libvlc_media_list_insert_media( libvlc_media_list_t *p_ml,
+                                libvlc_media_t *p_md, int i_pos );
+
 /**
  * Remove media instance from media list on a position
  * The libvlc_media_list_lock should be held upon entering this function.
  *
  * \param p_ml a media list instance
  * \param i_pos position in array where to insert
- * \param p_e initialized exception object
+ * \return 0 on success, -1 if the list is read-only or the item was not found
  */
-VLC_PUBLIC_API void
-    libvlc_media_list_remove_index( libvlc_media_list_t *, int,
-                                    libvlc_exception_t * );
+VLC_PUBLIC_API int
+libvlc_media_list_remove_index( libvlc_media_list_t *p_ml, int i_pos );
 
 /**
  * Get count on media list items
  * The libvlc_media_list_lock should be held upon entering this function.
  *
  * \param p_ml a media list instance
- * \param p_e initialized exception object
  * \return number of items in media list
  */
 VLC_PUBLIC_API int
-    libvlc_media_list_count( libvlc_media_list_t * p_mlist,
-                             libvlc_exception_t * p_e );
+    libvlc_media_list_count( libvlc_media_list_t *p_ml );
 
 /**
  * List media instance in media list at a position
@@ -160,26 +143,24 @@ VLC_PUBLIC_API int
  *
  * \param p_ml a media list instance
  * \param i_pos position in array where to insert
- * \param p_e initialized exception object
- * \return media instance at position i_pos and libvlc_media_retain() has been called to increase the refcount on this object.
+ * \return media instance at position i_pos, or NULL if not found.
+ * In case of success, libvlc_media_retain() is called to increase the refcount
+ * on the media.
  */
 VLC_PUBLIC_API libvlc_media_t *
-    libvlc_media_list_item_at_index( libvlc_media_list_t *, int,
-                                     libvlc_exception_t * );
+    libvlc_media_list_item_at_index( libvlc_media_list_t *p_ml, int i_pos );
 /**
  * Find index position of List media instance in media list.
  * Warning: the function will return the first matched position.
  * The libvlc_media_list_lock should be held upon entering this function.
  *
  * \param p_ml a media list instance
- * \param p_mi media list instance
- * \param p_e initialized exception object
+ * \param p_md media list instance
  * \return position of media instance
  */
 VLC_PUBLIC_API int
-    libvlc_media_list_index_of_item( libvlc_media_list_t *,
-                                     libvlc_media_t *,
-                                     libvlc_exception_t * );
+    libvlc_media_list_index_of_item( libvlc_media_list_t *p_ml,
+                                     libvlc_media_t *p_md );
 
 /**
  * This indicates if this media list is read-only from a user point of view
@@ -188,7 +169,7 @@ VLC_PUBLIC_API int
  * \return 0 on readonly, 1 on readwrite
  */
 VLC_PUBLIC_API int
-    libvlc_media_list_is_readonly( libvlc_media_list_t * p_mlist );
+    libvlc_media_list_is_readonly( libvlc_media_list_t * p_ml );
 
 /**
  * Get lock on media list items
@@ -196,7 +177,7 @@ VLC_PUBLIC_API int
  * \param p_ml a media list instance
  */
 VLC_PUBLIC_API void
-    libvlc_media_list_lock( libvlc_media_list_t * );
+    libvlc_media_list_lock( libvlc_media_list_t *p_ml );
 
 /**
  * Release lock on media list items
@@ -205,45 +186,17 @@ VLC_PUBLIC_API void
  * \param p_ml a media list instance
  */
 VLC_PUBLIC_API void
-    libvlc_media_list_unlock( libvlc_media_list_t * );
-
-/**
- * Get a flat media list view of media list items
- *
- * \param p_ml a media list instance
- * \param p_ex an excpetion instance
- * \return flat media list view instance
- */
-VLC_PUBLIC_API libvlc_media_list_view_t *
-    libvlc_media_list_flat_view( libvlc_media_list_t *,
-                                 libvlc_exception_t * );
-
-/**
- * Get a hierarchical media list view of media list items
- *
- * \param p_ml a media list instance
- * \param p_ex an exception instance
- * \return hierarchical media list view instance
- */
-VLC_PUBLIC_API libvlc_media_list_view_t *
-    libvlc_media_list_hierarchical_view( libvlc_media_list_t *,
-                                         libvlc_exception_t * );
-
-VLC_PUBLIC_API libvlc_media_list_view_t *
-    libvlc_media_list_hierarchical_node_view( libvlc_media_list_t * p_ml,
-                                              libvlc_exception_t * p_ex);
+    libvlc_media_list_unlock( libvlc_media_list_t *p_ml );
 
 /**
  * Get libvlc_event_manager from this media list instance.
  * The p_event_manager is immutable, so you don't have to hold the lock
  *
  * \param p_ml a media list instance
- * \param p_ex an excpetion instance
  * \return libvlc_event_manager
  */
 VLC_PUBLIC_API libvlc_event_manager_t *
-    libvlc_media_list_event_manager( libvlc_media_list_t *,
-                                     libvlc_exception_t * );
+    libvlc_media_list_event_manager( libvlc_media_list_t *p_ml );
 
 /** @} media_list */