1/*****************************************************************************
2 * libvlc_media_list.h: libvlc_media_list API
3 *****************************************************************************
4 * Copyright (C) 1998-2008 VLC authors and VideoLAN
5 * $Id: fa3b90932be8c3a9cce27925d4867aeddde748d7 $
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
28extern "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
39typedef 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 */
47LIBVLC_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 */
55LIBVLC_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 */
63LIBVLC_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 */
74LIBVLC_API void
75libvlc_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 */
85LIBVLC_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 */
96LIBVLC_API int
97libvlc_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 */
108LIBVLC_API int
109libvlc_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 */
120LIBVLC_API int
121libvlc_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 */
130LIBVLC_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 */
143LIBVLC_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 */
154LIBVLC_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 */
166LIBVLC_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 */
174LIBVLC_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 */
183LIBVLC_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 */
193LIBVLC_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 */
203

source code of include/vlc/libvlc_media_list.h