libvlc: clean up deprecated functions
[vlc.git] / 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 */