include/vlc/libvlc_media_list.h

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