/*****************************************************************************
* libvlc_media_list.h: libvlc_media_list API
*****************************************************************************
- * Copyright (C) 1998-2005 the VideoLAN team
+ * Copyright (C) 1998-2008 the VideoLAN team
* $Id$
*
* Authors: Pierre d'Herbemont
#ifndef LIBVLC_MEDIA_LIST_H
#define LIBVLC_MEDIA_LIST_H 1
+/**
+ * \file
+ * This file defines libvlc_media_list API
+ */
+
# ifdef __cplusplus
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;
+
/**
* Create an empty media list.
*
- * \param p_libvlc the event manager
- * \param i_event_type the desired event to which we want to unregister
- * \param f_callback the function to call when i_event_type occurs
- * \param p_e an initialized exception pointer
+ * \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().
+ *
+ * \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
+ *
+ * \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.
+ * If another media instance was present it will be released.
+ * The libvlc_media_list_lock should NOT be held upon entering this function.
+ *
+ * \param p_ml a media list instance
+ * \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
+ * the refcount on the media instance.
+ * The libvlc_media_list_lock should NOT be held upon entering this function.
+ *
+ * \param p_ml a media list instance
+ * \return media instance
+ */
VLC_PUBLIC_API libvlc_media_t *
- libvlc_media_list_media( libvlc_media_list_t *,
- libvlc_exception_t *);
-
-VLC_PUBLIC_API void
- libvlc_media_list_add_media( libvlc_media_list_t *,
- libvlc_media_t *,
- libvlc_exception_t * );
-VLC_PUBLIC_API void
- libvlc_media_list_insert_media( libvlc_media_list_t *,
- libvlc_media_t *,
- int,
- libvlc_exception_t * );
-VLC_PUBLIC_API void
- libvlc_media_list_remove_index( libvlc_media_list_t *, int,
- 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_md a media instance
+ * \return 0 on success, -1 if the media list is read-only
+ */
VLC_PUBLIC_API int
- libvlc_media_list_count( libvlc_media_list_t * p_mlist,
- libvlc_exception_t * p_e );
+libvlc_media_list_add_media( libvlc_media_list_t *p_ml, libvlc_media_t *p_md );
-VLC_PUBLIC_API libvlc_media_t *
- libvlc_media_list_item_at_index( libvlc_media_list_t *, int,
- libvlc_exception_t * );
+/**
+ * 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_md a media instance
+ * \param i_pos position in array where to insert
+ * \return 0 on success, -1 if the media list si read-only
+ */
VLC_PUBLIC_API int
- libvlc_media_list_index_of_item( libvlc_media_list_t *,
- libvlc_media_t *,
- libvlc_exception_t * );
+libvlc_media_list_insert_media( libvlc_media_list_t *p_ml,
+ libvlc_media_t *p_md, int i_pos );
-/* This indicates if this media list is read-only from a user point of view */
+/**
+ * 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
+ * \return 0 on success, -1 if the list is read-only or the item was not found
+ */
VLC_PUBLIC_API int
- libvlc_media_list_is_readonly( libvlc_media_list_t * p_mlist );
-
-VLC_PUBLIC_API void
- libvlc_media_list_lock( libvlc_media_list_t * );
-VLC_PUBLIC_API void
- libvlc_media_list_unlock( libvlc_media_list_t * );
-
-VLC_PUBLIC_API libvlc_media_list_view_t *
- libvlc_media_list_flat_view( libvlc_media_list_t *,
- libvlc_exception_t * );
-
-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 *,
- libvlc_exception_t * );
-
-VLC_PUBLIC_API libvlc_event_manager_t *
- libvlc_media_list_event_manager( libvlc_media_list_t *,
- libvlc_exception_t * );
-
-/*****************************************************************************
- * Media List View
- *****************************************************************************/
-/** \defgroup libvlc_media_list_view libvlc_media_list_view
- * \ingroup libvlc_media_list
- * LibVLC Media List View, represent a media_list using a different layout
- * @{ */
-
-VLC_PUBLIC_API void
- libvlc_media_list_view_retain( libvlc_media_list_view_t * p_mlv );
-
-VLC_PUBLIC_API void
- libvlc_media_list_view_release( libvlc_media_list_view_t * p_mlv );
-
-VLC_PUBLIC_API libvlc_event_manager_t *
- libvlc_media_list_view_event_manager( libvlc_media_list_view_t * p_mlv );
+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
+ * \return number of items in media list
+ */
VLC_PUBLIC_API int
- libvlc_media_list_view_count( libvlc_media_list_view_t * p_mlv,
- libvlc_exception_t * p_e );
+ libvlc_media_list_count( libvlc_media_list_t *p_ml );
+/**
+ * List media instance in media list at 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
+ * \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_view_item_at_index( libvlc_media_list_view_t * p_mlv,
- int index,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API libvlc_media_list_view_t *
- libvlc_media_list_view_children_at_index( libvlc_media_list_view_t * p_mlv,
- int index,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API libvlc_media_list_view_t *
- libvlc_media_list_view_children_for_item( libvlc_media_list_view_t * p_mlv,
- libvlc_media_t * p_md,
- libvlc_exception_t * p_e );
-
-
+ 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_md media list instance
+ * \return position of media instance
+ */
VLC_PUBLIC_API int
- libvlc_media_list_view_index_of_item( libvlc_media_list_view_t * p_mlv,
- libvlc_media_t * p_md,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API void
- libvlc_media_list_view_insert_at_index( libvlc_media_list_view_t * p_mlv,
- libvlc_media_t * p_md,
- int index,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API void
- libvlc_media_list_view_remove_at_index( libvlc_media_list_view_t * p_mlv,
- int index,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API void
- libvlc_media_list_view_add_item( libvlc_media_list_view_t * p_mlv,
- libvlc_media_t * p_md,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API libvlc_media_list_t *
- libvlc_media_list_view_parent_media_list( libvlc_media_list_view_t * p_mlv,
- libvlc_exception_t * p_e );
+ libvlc_media_list_index_of_item( libvlc_media_list_t *p_ml,
+ libvlc_media_t *p_md );
-/** @} media_list_view */
-
-/*****************************************************************************
- * Media List Player
- *****************************************************************************/
-/** \defgroup libvlc_media_list_player libvlc_media_list_player
- * \ingroup libvlc_media_list_player
- * LibVLC Media List Player, play a media_list. You can see that as a media
- * instance subclass
- * @{
+/**
+ * This indicates if this media list is read-only from a user point of view
+ *
+ * \param p_ml media list instance
+ * \return 0 on readonly, 1 on readwrite
*/
-VLC_PUBLIC_API libvlc_media_list_player_t *
- libvlc_media_list_player_new( libvlc_instance_t * p_instance,
- libvlc_exception_t * p_e );
-VLC_PUBLIC_API void
- libvlc_media_list_player_release( libvlc_media_list_player_t * p_mlp );
-
-VLC_PUBLIC_API void
- libvlc_media_list_player_set_media_player(
- libvlc_media_list_player_t * p_mlp,
- libvlc_media_player_t * p_mi,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API void
- libvlc_media_list_player_set_media_list(
- libvlc_media_list_player_t * p_mlp,
- libvlc_media_list_t * p_mlist,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API void
- libvlc_media_list_player_play( libvlc_media_list_player_t * p_mlp,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API void
- libvlc_media_list_player_pause( libvlc_media_list_player_t * p_mlp,
- libvlc_exception_t * p_e );
-
VLC_PUBLIC_API int
- libvlc_media_list_player_is_playing( libvlc_media_list_player_t * p_mlp,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API libvlc_state_t
- libvlc_media_list_player_get_state( libvlc_media_list_player_t * p_mlp,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API void
- libvlc_media_list_player_play_item_at_index(
- libvlc_media_list_player_t * p_mlp,
- int i_index,
- libvlc_exception_t * p_e );
-
-VLC_PUBLIC_API void
- libvlc_media_list_player_play_item(
- libvlc_media_list_player_t * p_mlp,
- libvlc_media_t * p_md,
- libvlc_exception_t * p_e );
+ libvlc_media_list_is_readonly( libvlc_media_list_t * p_ml );
+/**
+ * Get lock on media list items
+ *
+ * \param p_ml a media list instance
+ */
VLC_PUBLIC_API void
- libvlc_media_list_player_stop( libvlc_media_list_player_t * p_mlp,
- libvlc_exception_t * p_e );
+ libvlc_media_list_lock( libvlc_media_list_t *p_ml );
+/**
+ * Release lock on media list items
+ * The libvlc_media_list_lock should be held upon entering this function.
+ *
+ * \param p_ml a media list instance
+ */
VLC_PUBLIC_API void
- libvlc_media_list_player_next( libvlc_media_list_player_t * p_mlp,
- libvlc_exception_t * p_e );
+ libvlc_media_list_unlock( libvlc_media_list_t *p_ml );
-/** @} media_list_player */
+/**
+ * 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
+ * \return libvlc_event_manager
+ */
+VLC_PUBLIC_API libvlc_event_manager_t *
+ libvlc_media_list_event_manager( libvlc_media_list_t *p_ml );
/** @} media_list */
projects / vlc / blobdiff