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