git.sesse.net Git - vlc/blob - include/vlc/libvlc_media_list.h

   1 /*****************************************************************************
   2  * libvlc_media_list.h:  libvlc_media_list API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2008 the VideoLAN team
   5  * $Id$
   6  *
   7  * Authors: Pierre d'Herbemont
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifndef LIBVLC_MEDIA_LIST_H
  25 #define LIBVLC_MEDIA_LIST_H 1
  26
  27 /**
  28  * \file
  29  * This file defines libvlc_media_list API
  30  */
  31
  32 # ifdef __cplusplus
  33 extern "C" {
  34 # endif
  35
  36 /*****************************************************************************
  37  * Media List
  38  *****************************************************************************/
  39 /** \defgroup libvlc_media_list libvlc_media_list
  40  * \ingroup libvlc
  41  * LibVLC Media List, a media list holds multiple media descriptors
  42  * @{
  43  */
  44
  45 typedef struct libvlc_media_list_t libvlc_media_list_t;
  46
  47 /**
  48  * Create an empty media list.
  49  *
  50  * \param p_instance libvlc instance
  51  * \return empty media list, or NULL on error
  52  */
  53 VLC_PUBLIC_API libvlc_media_list_t *
  54     libvlc_media_list_new( libvlc_instance_t *p_instance );
  55
  56 /**
  57  * Release media list created with libvlc_media_list_new().
  58  *
  59  * \param p_ml a media list created with libvlc_media_list_new()
  60  */
  61 VLC_PUBLIC_API void
  62     libvlc_media_list_release( libvlc_media_list_t *p_ml );
  63
  64 /**
  65  * Retain reference to a media list
  66  *
  67  * \param p_ml a media list created with libvlc_media_list_new()
  68  */
  69 VLC_PUBLIC_API void
  70     libvlc_media_list_retain( libvlc_media_list_t *p_ml );
  71
  72 VLC_DEPRECATED_API int
  73     libvlc_media_list_add_file_content( libvlc_media_list_t * p_ml,
  74                                         const char * psz_uri );
  75
  76 /**
  77  * Associate media instance with this media list instance.
  78  * If another media instance was present it will be released.
  79  * The libvlc_media_list_lock should NOT be held upon entering this function.
  80  *
  81  * \param p_ml a media list instance
  82  * \param p_md media instance to add
  83  */
  84 VLC_PUBLIC_API void
  85 libvlc_media_list_set_media( libvlc_media_list_t *p_ml, libvlc_media_t *p_md );
  86
  87 /**
  88  * Get media instance from this media list instance. This action will increase
  89  * the refcount on the media instance.
  90  * The libvlc_media_list_lock should NOT be held upon entering this function.
  91  *
  92  * \param p_ml a media list instance
  93  * \return media instance
  94  */
  95 VLC_PUBLIC_API libvlc_media_t *
  96     libvlc_media_list_media( libvlc_media_list_t *p_ml );
  97
  98 /**
  99  * Add media instance to media list
 100  * The libvlc_media_list_lock should be held upon entering this function.
 101  *
 102  * \param p_ml a media list instance
 103  * \param p_md a media instance
 104  * \return 0 on success, -1 if the media list is read-only
 105  */
 106 VLC_PUBLIC_API int
 107 libvlc_media_list_add_media( libvlc_media_list_t *p_ml, libvlc_media_t *p_md );
 108
 109 /**
 110  * Insert media instance in media list on a position
 111  * The libvlc_media_list_lock should be held upon entering this function.
 112  *
 113  * \param p_ml a media list instance
 114  * \param p_md a media instance
 115  * \param i_pos position in array where to insert
 116  * \return 0 on success, -1 if the media list si read-only
 117  */
 118 VLC_PUBLIC_API int
 119 libvlc_media_list_insert_media( libvlc_media_list_t *p_ml,
 120                                 libvlc_media_t *p_md, int i_pos );
 121
 122 /**
 123  * Remove media instance from media list on a position
 124  * The libvlc_media_list_lock should be held upon entering this function.
 125  *
 126  * \param p_ml a media list instance
 127  * \param i_pos position in array where to insert
 128  * \return 0 on success, -1 if the list is read-only or the item was not found
 129  */
 130 VLC_PUBLIC_API int
 131 libvlc_media_list_remove_index( libvlc_media_list_t *p_ml, int i_pos );
 132
 133 /**
 134  * Get count on media list items
 135  * The libvlc_media_list_lock should be held upon entering this function.
 136  *
 137  * \param p_ml a media list instance
 138  * \return number of items in media list
 139  */
 140 VLC_PUBLIC_API int
 141     libvlc_media_list_count( libvlc_media_list_t *p_ml );
 142
 143 /**
 144  * List media instance in media list at a position
 145  * The libvlc_media_list_lock should be held upon entering this function.
 146  *
 147  * \param p_ml a media list instance
 148  * \param i_pos position in array where to insert
 149  * \return media instance at position i_pos, or NULL if not found.
 150  * In case of success, libvlc_media_retain() is called to increase the refcount
 151  * on the media.
 152  */
 153 VLC_PUBLIC_API libvlc_media_t *
 154     libvlc_media_list_item_at_index( libvlc_media_list_t *p_ml, int i_pos );
 155 /**
 156  * Find index position of List media instance in media list.
 157  * Warning: the function will return the first matched position.
 158  * The libvlc_media_list_lock should be held upon entering this function.
 159  *
 160  * \param p_ml a media list instance
 161  * \param p_md media list instance
 162  * \return position of media instance
 163  */
 164 VLC_PUBLIC_API int
 165     libvlc_media_list_index_of_item( libvlc_media_list_t *p_ml,
 166                                      libvlc_media_t *p_md );
 167
 168 /**
 169  * This indicates if this media list is read-only from a user point of view
 170  *
 171  * \param p_ml media list instance
 172  * \return 0 on readonly, 1 on readwrite
 173  */
 174 VLC_PUBLIC_API int
 175     libvlc_media_list_is_readonly( libvlc_media_list_t * p_ml );
 176
 177 /**
 178  * Get lock on media list items
 179  *
 180  * \param p_ml a media list instance
 181  */
 182 VLC_PUBLIC_API void
 183     libvlc_media_list_lock( libvlc_media_list_t *p_ml );
 184
 185 /**
 186  * Release lock on media list items
 187  * The libvlc_media_list_lock should be held upon entering this function.
 188  *
 189  * \param p_ml a media list instance
 190  */
 191 VLC_PUBLIC_API void
 192     libvlc_media_list_unlock( libvlc_media_list_t *p_ml );
 193
 194 /**
 195  * Get libvlc_event_manager from this media list instance.
 196  * The p_event_manager is immutable, so you don't have to hold the lock
 197  *
 198  * \param p_ml a media list instance
 199  * \return libvlc_event_manager
 200  */
 201 VLC_PUBLIC_API libvlc_event_manager_t *
 202     libvlc_media_list_event_manager( libvlc_media_list_t *p_ml );
 203
 204 /** @} media_list */
 205
 206 # ifdef __cplusplus
 207 }
 208 # endif
 209
 210 #endif /* _LIBVLC_MEDIA_LIST_H */