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