46474a9fc08d18c9cd4bdcc4ed78c6ce670eac15
[vlc.git] / 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 */