X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media_list.h;h=32304ee4304c2fb3272a922947123884a1f59f07;hb=31150350679286f873c94fc670ddbafddaed7163;hp=1c09546d352e7d3008f1565dc9d44c8f645f552b;hpb=e0105d9b23a08eeedf89b869628644e38df4e8dd;p=vlc diff --git a/include/vlc/libvlc_media_list.h b/include/vlc/libvlc_media_list.h index 1c09546d35..32304ee430 100644 --- a/include/vlc/libvlc_media_list.h +++ b/include/vlc/libvlc_media_list.h @@ -1,7 +1,7 @@ /***************************************************************************** * 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 @@ -21,232 +21,182 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/ -#ifndef _LIBVLC_MEDIA_LIST_H -#define _LIBVLC_MEDIA_LIST_H 1 +#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 MediaList +/** \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_descriptor( libvlc_media_list_t *, - libvlc_media_descriptor_t *, - libvlc_exception_t *); - -VLC_PUBLIC_API libvlc_media_descriptor_t * - libvlc_media_list_media_descriptor( libvlc_media_list_t *, - libvlc_exception_t *); +libvlc_media_list_set_media( libvlc_media_list_t *p_ml, libvlc_media_t *p_md ); -VLC_PUBLIC_API void - libvlc_media_list_add_media_descriptor( libvlc_media_list_t *, - libvlc_media_descriptor_t *, - libvlc_exception_t * ); -VLC_PUBLIC_API void - libvlc_media_list_insert_media_descriptor( libvlc_media_list_t *, - libvlc_media_descriptor_t *, - int, - libvlc_exception_t * ); -VLC_PUBLIC_API void - libvlc_media_list_remove_index( libvlc_media_list_t *, int, - libvlc_exception_t * ); +/** + * 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 *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_descriptor_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_descriptor_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 MediaListView - * \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 ); - -VLC_PUBLIC_API libvlc_media_descriptor_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_descriptor_t * p_md, - 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_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_descriptor_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_descriptor_t * p_md, - int index, - libvlc_exception_t * p_e ); + libvlc_media_list_index_of_item( libvlc_media_list_t *p_ml, + libvlc_media_t *p_md ); -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_descriptor_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 ); - -/** @} media_list_view */ - -/***************************************************************************** - * Media List Player - *****************************************************************************/ -/** defgroup libvlc_media_list_player MediaListPlayer - * \ingroup libvlc - * 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_instance( - libvlc_media_list_player_t * p_mlp, - libvlc_media_instance_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_descriptor_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 */