1/*****************************************************************************
2 * libvlc_media_list_player.h: libvlc_media_list API
3 *****************************************************************************
4 * Copyright (C) 1998-2008 VLC authors and VideoLAN
5 * $Id: 04f7d9b9f0d47e1b8304b51ca20fd2b1045a0ff2 $
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_PLAYER_H
25#define LIBVLC_MEDIA_LIST_PLAYER_H 1
26
27# ifdef __cplusplus
28extern "C" {
29# endif
30
31/** \defgroup libvlc_media_list_player LibVLC media list player
32 * \ingroup libvlc
33 * The LibVLC media list player plays a @ref libvlc_media_list_t list of media,
34 * in a certain order.
35 * This is required to especially support playlist files.
36 * The normal @ref libvlc_media_player_t LibVLC media player can only play a
37 * single media, and does not handle playlist files properly.
38 * @{
39 * \file
40 * LibVLC media list player external API
41 */
42
43typedef struct libvlc_media_list_player_t libvlc_media_list_player_t;
44
45/**
46 * Defines playback modes for playlist.
47 */
48typedef enum libvlc_playback_mode_t
49{
50 libvlc_playback_mode_default,
51 libvlc_playback_mode_loop,
52 libvlc_playback_mode_repeat
53} libvlc_playback_mode_t;
54
55/**
56 * Create new media_list_player.
57 *
58 * \param p_instance libvlc instance
59 * \return media list player instance or NULL on error
60 */
61LIBVLC_API libvlc_media_list_player_t *
62 libvlc_media_list_player_new( libvlc_instance_t * p_instance );
63
64/**
65 * Release a media_list_player after use
66 * Decrement the reference count of a media player object. If the
67 * reference count is 0, then libvlc_media_list_player_release() will
68 * release the media player object. If the media player object
69 * has been released, then it should not be used again.
70 *
71 * \param p_mlp media list player instance
72 */
73LIBVLC_API void
74 libvlc_media_list_player_release( libvlc_media_list_player_t * p_mlp );
75
76/**
77 * Retain a reference to a media player list object. Use
78 * libvlc_media_list_player_release() to decrement reference count.
79 *
80 * \param p_mlp media player list object
81 */
82LIBVLC_API void
83 libvlc_media_list_player_retain( libvlc_media_list_player_t *p_mlp );
84
85/**
86 * Return the event manager of this media_list_player.
87 *
88 * \param p_mlp media list player instance
89 * \return the event manager
90 */
91LIBVLC_API libvlc_event_manager_t *
92 libvlc_media_list_player_event_manager(libvlc_media_list_player_t * p_mlp);
93
94/**
95 * Replace media player in media_list_player with this instance.
96 *
97 * \param p_mlp media list player instance
98 * \param p_mi media player instance
99 */
100LIBVLC_API void
101 libvlc_media_list_player_set_media_player(
102 libvlc_media_list_player_t * p_mlp,
103 libvlc_media_player_t * p_mi );
104
105/**
106 * Get media player of the media_list_player instance.
107 *
108 * \param p_mlp media list player instance
109 * \return media player instance
110 * \note the caller is responsible for releasing the returned instance
111 */
112LIBVLC_API libvlc_media_player_t *
113 libvlc_media_list_player_get_media_player(libvlc_media_list_player_t * p_mlp);
114
115/**
116 * Set the media list associated with the player
117 *
118 * \param p_mlp media list player instance
119 * \param p_mlist list of media
120 */
121LIBVLC_API void
122 libvlc_media_list_player_set_media_list(
123 libvlc_media_list_player_t * p_mlp,
124 libvlc_media_list_t * p_mlist );
125
126/**
127 * Play media list
128 *
129 * \param p_mlp media list player instance
130 */
131LIBVLC_API
132void libvlc_media_list_player_play(libvlc_media_list_player_t * p_mlp);
133
134/**
135 * Toggle pause (or resume) media list
136 *
137 * \param p_mlp media list player instance
138 */
139LIBVLC_API
140void libvlc_media_list_player_pause(libvlc_media_list_player_t * p_mlp);
141
142/**
143 * Pause or resume media list
144 *
145 * \param p_mlp media list player instance
146 * \param do_pause play/resume if zero, pause if non-zero
147 * \version LibVLC 3.0.0 or later
148 */
149LIBVLC_API
150void libvlc_media_list_player_set_pause(libvlc_media_list_player_t * p_mlp,
151 int do_pause);
152
153/**
154 * Is media list playing?
155 *
156 * \param p_mlp media list player instance
157 * \return true for playing and false for not playing
158 *
159 * \libvlc_return_bool
160 */
161LIBVLC_API int
162 libvlc_media_list_player_is_playing( libvlc_media_list_player_t * p_mlp );
163
164/**
165 * Get current libvlc_state of media list player
166 *
167 * \param p_mlp media list player instance
168 * \return libvlc_state_t for media list player
169 */
170LIBVLC_API libvlc_state_t
171 libvlc_media_list_player_get_state( libvlc_media_list_player_t * p_mlp );
172
173/**
174 * Play media list item at position index
175 *
176 * \param p_mlp media list player instance
177 * \param i_index index in media list to play
178 * \return 0 upon success -1 if the item wasn't found
179 */
180LIBVLC_API
181int libvlc_media_list_player_play_item_at_index(libvlc_media_list_player_t * p_mlp,
182 int i_index);
183
184/**
185 * Play the given media item
186 *
187 * \param p_mlp media list player instance
188 * \param p_md the media instance
189 * \return 0 upon success, -1 if the media is not part of the media list
190 */
191LIBVLC_API
192int libvlc_media_list_player_play_item(libvlc_media_list_player_t * p_mlp,
193 libvlc_media_t * p_md);
194
195/**
196 * Stop playing media list
197 *
198 * \param p_mlp media list player instance
199 */
200LIBVLC_API void
201 libvlc_media_list_player_stop( libvlc_media_list_player_t * p_mlp);
202
203/**
204 * Play next item from media list
205 *
206 * \param p_mlp media list player instance
207 * \return 0 upon success -1 if there is no next item
208 */
209LIBVLC_API
210int libvlc_media_list_player_next(libvlc_media_list_player_t * p_mlp);
211
212/**
213 * Play previous item from media list
214 *
215 * \param p_mlp media list player instance
216 * \return 0 upon success -1 if there is no previous item
217 */
218LIBVLC_API
219int libvlc_media_list_player_previous(libvlc_media_list_player_t * p_mlp);
220
221
222
223/**
224 * Sets the playback mode for the playlist
225 *
226 * \param p_mlp media list player instance
227 * \param e_mode playback mode specification
228 */
229LIBVLC_API
230void libvlc_media_list_player_set_playback_mode(libvlc_media_list_player_t * p_mlp,
231 libvlc_playback_mode_t e_mode );
232
233/** @} media_list_player */
234
235# ifdef __cplusplus
236}
237# endif
238
239#endif /* LIBVLC_MEDIA_LIST_PLAYER_H */
240

source code of include/vlc/libvlc_media_list_player.h