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