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