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 typedef struct libvlc_media_list_view_t libvlc_media_list_view_t;
  47
  48 /**
  49  * Create an empty media list.
  50  *
  51  * \param p_libvlc libvlc instance
  52  * \return empty media list, or NULL on error
  53  */
  54 VLC_PUBLIC_API libvlc_media_list_t *
  55     libvlc_media_list_new( libvlc_instance_t * );
  56
  57 /**
  58  * Release media list created with libvlc_media_list_new().
  59  *
  60  * \param p_ml a media list created with libvlc_media_list_new()
  61  */
  62 VLC_PUBLIC_API void
  63     libvlc_media_list_release( libvlc_media_list_t * );
  64
  65 /**
  66  * Retain reference to a media list
  67  *
  68  * \param p_ml a media list created with libvlc_media_list_new()
  69  */
  70 VLC_PUBLIC_API void
  71     libvlc_media_list_retain( libvlc_media_list_t * );
  72
  73 VLC_DEPRECATED_API void
  74     libvlc_media_list_add_file_content( libvlc_media_list_t * p_mlist,
  75                                         const char * psz_uri,
  76                                         libvlc_exception_t * p_e );
  77
  78 /**
  79  * Associate media instance with this media list instance.
  80  * If another media instance was present it will be released.
  81  * The libvlc_media_list_lock should NOT be held upon entering this function.
  82  *
  83  * \param p_ml a media list instance
  84  * \param p_mi media instance to add
  85  */
  86 VLC_PUBLIC_API void
  87 libvlc_media_list_set_media( libvlc_media_list_t *p_ml, libvlc_media_t *p_md );
  88
  89 /**
  90  * Get media instance from this media list instance. This action will increase
  91  * the refcount on the media instance.
  92  * The libvlc_media_list_lock should NOT be held upon entering this function.
  93  *
  94  * \param p_ml a media list instance
  95  * \return media instance
  96  */
  97 VLC_PUBLIC_API libvlc_media_t *
  98     libvlc_media_list_media( libvlc_media_list_t *p_ml );
  99
 100 /**
 101  * Add media instance to media list
 102  * The libvlc_media_list_lock should be held upon entering this function.
 103  *
 104  * \param p_ml a media list instance
 105  * \param p_mi a media instance
 106  * \return 0 on success, -1 if the media list is read-only
 107  */
 108 VLC_PUBLIC_API int
 109 libvlc_media_list_add_media( libvlc_media_list_t *, libvlc_media_t * );
 110
 111 /**
 112  * Insert media instance in media list on a position
 113  * The libvlc_media_list_lock should be held upon entering this function.
 114  *
 115  * \param p_ml a media list instance
 116  * \param p_mi a media instance
 117  * \param i_pos position in array where to insert
 118  * \return 0 on success, -1 if the media list si read-only
 119  */
 120 VLC_PUBLIC_API int
 121 libvlc_media_list_insert_media( libvlc_media_list_t *,
 122                                 libvlc_media_t *, int );
 123
 124 /**
 125  * Remove media instance from media list on a position
 126  * The libvlc_media_list_lock should be held upon entering this function.
 127  *
 128  * \param p_ml a media list instance
 129  * \param i_pos position in array where to insert
 130  * \return 0 on success, -1 if the list is read-only or the item was not found
 131  */
 132 VLC_PUBLIC_API int
 133 libvlc_media_list_remove_index( libvlc_media_list_t *, int );
 134
 135 /**
 136  * Get count on media list items
 137  * The libvlc_media_list_lock should be held upon entering this function.
 138  *
 139  * \param p_ml a media list instance
 140  * \return number of items in media list
 141  */
 142 VLC_PUBLIC_API int
 143     libvlc_media_list_count( libvlc_media_list_t *p_ml );
 144
 145 /**
 146  * List media instance in media list at a position
 147  * The libvlc_media_list_lock should be held upon entering this function.
 148  *
 149  * \param p_ml a media list instance
 150  * \param i_pos position in array where to insert
 151  * \return media instance at position i_pos, or NULL if not found.
 152  * In case of success, libvlc_media_retain() is called to increase the refcount
 153  * on the media.
 154  */
 155 VLC_PUBLIC_API libvlc_media_t *
 156     libvlc_media_list_item_at_index( libvlc_media_list_t *, int );
 157 /**
 158  * Find index position of List media instance in media list.
 159  * Warning: the function will return the first matched position.
 160  * The libvlc_media_list_lock should be held upon entering this function.
 161  *
 162  * \param p_ml a media list instance
 163  * \param p_mi media list instance
 164  * \return position of media instance
 165  */
 166 VLC_PUBLIC_API int
 167     libvlc_media_list_index_of_item( libvlc_media_list_t *p_ml,
 168                                      libvlc_media_t *p_mi );
 169
 170 /**
 171  * This indicates if this media list is read-only from a user point of view
 172  *
 173  * \param p_ml media list instance
 174  * \return 0 on readonly, 1 on readwrite
 175  */
 176 VLC_PUBLIC_API int
 177     libvlc_media_list_is_readonly( libvlc_media_list_t * p_mlist );
 178
 179 /**
 180  * Get lock on media list items
 181  *
 182  * \param p_ml a media list instance
 183  */
 184 VLC_PUBLIC_API void
 185     libvlc_media_list_lock( libvlc_media_list_t * );
 186
 187 /**
 188  * Release lock on media list items
 189  * The libvlc_media_list_lock should be held upon entering this function.
 190  *
 191  * \param p_ml a media list instance
 192  */
 193 VLC_PUBLIC_API void
 194     libvlc_media_list_unlock( libvlc_media_list_t * );
 195
 196 /**
 197  * Get a flat media list view of media list items
 198  *
 199  * \param p_ml a media list instance
 200  * \param p_ex an excpetion instance
 201  * \return flat media list view instance
 202  */
 203 VLC_PUBLIC_API libvlc_media_list_view_t *
 204     libvlc_media_list_flat_view( libvlc_media_list_t *,
 205                                  libvlc_exception_t * );
 206
 207 /**
 208  * Get a hierarchical media list view of media list items
 209  *
 210  * \param p_ml a media list instance
 211  * \return hierarchical media list view instance
 212  */
 213 VLC_PUBLIC_API libvlc_media_list_view_t *
 214     libvlc_media_list_hierarchical_view( libvlc_media_list_t * );
 215
 216 VLC_PUBLIC_API libvlc_media_list_view_t *
 217     libvlc_media_list_hierarchical_node_view( libvlc_media_list_t * p_ml );
 218
 219 /**
 220  * Get libvlc_event_manager from this media list instance.
 221  * The p_event_manager is immutable, so you don't have to hold the lock
 222  *
 223  * \param p_ml a media list instance
 224  * \return libvlc_event_manager
 225  */
 226 VLC_PUBLIC_API libvlc_event_manager_t *
 227     libvlc_media_list_event_manager( libvlc_media_list_t *p_ml );
 228
 229 /** @} media_list */
 230
 231 # ifdef __cplusplus
 232 }
 233 # endif
 234
 235 #endif /* _LIBVLC_MEDIA_LIST_H */