libvlc.h: Define and implement libvlc_media_instance_is_pausable().
[vlc.git] / include / vlc / mediacontrol.h
1 /*****************************************************************************
2  * control.h: global header for mediacontrol
3  *****************************************************************************
4  * Copyright (C) 2005 the VideoLAN team
5  * $Id$
6  *
7  * Authors: Olivier Aubert <olivier.aubert@liris.univ-lyon1.fr>
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 /**
25  * \defgroup mediacontrol MediaControl
26  * This is the MediaControl API, * intended to provide a generic API to movie players.
27  *
28  * @{
29  */
30
31
32 #ifndef _VLC_CONTROL_H
33 #define _VLC_CONTROL_H 1
34
35 # ifdef __cplusplus
36 extern "C" {
37 # endif
38
39 #if defined( WIN32 )
40 #include <windows.h>
41 #define WINDOWHANDLE HWND
42 #else
43 #define WINDOWHANDLE int
44 #endif
45
46 #include <vlc/libvlc.h>
47 #include <vlc/mediacontrol_structures.h>
48
49 /**
50  * mediacontrol_Instance is an opaque structure, defined in
51  * mediacontrol_internal.h. API users do not have to mess with it.
52  */
53 typedef struct mediacontrol_Instance mediacontrol_Instance;
54
55 /**************************************************************************
56  *  Helper functions
57  ***************************************************************************/
58
59 /**
60  * Free a RGBPicture structure.
61  * \param pic: the RGBPicture structure
62  */
63 VLC_PUBLIC_API void mediacontrol_RGBPicture__free( mediacontrol_RGBPicture *pic );
64
65 VLC_PUBLIC_API void mediacontrol_PlaylistSeq__free( mediacontrol_PlaylistSeq *ps );
66
67 /**
68  * Free a StreamInformation structure.
69  * \param pic: the StreamInformation structure
70  */
71 VLC_PUBLIC_API void
72 mediacontrol_StreamInformation__free( mediacontrol_StreamInformation* p_si );
73
74 /**
75  * Instanciate and initialize an exception structure.
76  * \return the exception
77  */
78 VLC_PUBLIC_API mediacontrol_Exception *
79   mediacontrol_exception_create( void );
80
81 /**
82  * Initialize an existing exception structure.
83  * \param p_exception the exception to initialize.
84  */
85 VLC_PUBLIC_API void
86   mediacontrol_exception_init( mediacontrol_Exception *exception );
87
88 /**
89  * Clean up an existing exception structure after use.
90  * \param p_exception the exception to clean up.
91  */
92 VLC_PUBLIC_API void
93 mediacontrol_exception_cleanup( mediacontrol_Exception *exception );
94
95 /**
96  * Free an exception structure created with mediacontrol_exception_create().
97  * \return the exception
98  */
99 VLC_PUBLIC_API void mediacontrol_exception_free(mediacontrol_Exception *exception);
100
101 /*****************************************************************************
102  * Core functions
103  *****************************************************************************/
104
105 /**
106  * Create a MediaControl instance with parameters
107  * \param argc the number of arguments
108  * \param argv parameters
109  * \param exception an initialized exception pointer
110  * \return a mediacontrol_Instance
111  */
112 VLC_PUBLIC_API mediacontrol_Instance *
113 mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
114
115 /**
116  * Create a MediaControl instance from an existing libvlc instance
117  * \param p_instance the libvlc instance
118  * \param exception an initialized exception pointer
119  * \return a mediacontrol_Instance
120  */
121 VLC_PUBLIC_API mediacontrol_Instance *
122 mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
123                 mediacontrol_Exception *exception );
124
125 /**
126  * Get the associated libvlc instance
127  * \param self: the mediacontrol instance
128  * \return a libvlc instance
129  */
130 VLC_PUBLIC_API libvlc_instance_t*
131 mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
132
133 /**
134  * Get the current position
135  * \param self the mediacontrol instance
136  * \param an_origin the position origin
137  * \param a_key the position unit
138  * \param exception an initialized exception pointer
139  * \return a mediacontrol_Position
140  */
141 VLC_PUBLIC_API mediacontrol_Position * mediacontrol_get_media_position(
142                          mediacontrol_Instance *self,
143                          const mediacontrol_PositionOrigin an_origin,
144                          const mediacontrol_PositionKey a_key,
145                          mediacontrol_Exception *exception );
146
147 /**
148  * Set the position
149  * \param self the mediacontrol instance
150  * \param a_position a mediacontrol_Position
151  * \param exception an initialized exception pointer
152  */
153 VLC_PUBLIC_API void mediacontrol_set_media_position( mediacontrol_Instance *self,
154                                       const mediacontrol_Position *a_position,
155                                       mediacontrol_Exception *exception );
156
157 /**
158  * Play the movie at a given position
159  * \param self the mediacontrol instance
160  * \param a_position a mediacontrol_Position
161  * \param exception an initialized exception pointer
162  */
163 VLC_PUBLIC_API void mediacontrol_start( mediacontrol_Instance *self,
164                          const mediacontrol_Position *a_position,
165                          mediacontrol_Exception *exception );
166
167 /**
168  * Pause the movie at a given position
169  * \param self the mediacontrol instance
170  * \param a_position a mediacontrol_Position (ignored for now)
171  * \param exception an initialized exception pointer
172  */
173 VLC_PUBLIC_API void mediacontrol_pause( mediacontrol_Instance *self,
174                          const mediacontrol_Position *a_position,
175                          mediacontrol_Exception *exception );
176
177 /**
178  * Resume the movie at a given position
179  * \param self the mediacontrol instance
180  * \param a_position a mediacontrol_Position (ignored for now)
181  * \param exception an initialized exception pointer
182  */
183 VLC_PUBLIC_API void mediacontrol_resume( mediacontrol_Instance *self,
184                           const mediacontrol_Position *a_position,
185                           mediacontrol_Exception *exception );
186
187 /**
188  * Stop the movie at a given position
189  * \param self the mediacontrol instance
190  * \param a_position a mediacontrol_Position (ignored for now)
191  * \param exception an initialized exception pointer
192  */
193 VLC_PUBLIC_API void mediacontrol_stop( mediacontrol_Instance *self,
194                         const mediacontrol_Position *a_position,
195                         mediacontrol_Exception *exception );
196
197 /**
198  * Exit the player
199  * \param self the mediacontrol instance
200  */
201 VLC_PUBLIC_API void mediacontrol_exit( mediacontrol_Instance *self );
202
203 /**
204  * Add a new MRL to the playlist
205  * \param self the mediacontrol instance
206  * \param psz_file the MRL
207  * \param exception an initialized exception pointer
208  */
209 VLC_PUBLIC_API void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
210                                      const char* psz_file,
211                                      mediacontrol_Exception *exception );
212 /**
213  * Clear the playlist
214  * \param self the mediacontrol instance
215  * \param exception an initialized exception pointer
216  */
217 VLC_PUBLIC_API void mediacontrol_playlist_clear( mediacontrol_Instance *self,
218                                   mediacontrol_Exception *exception );
219 /**
220  * Get a flattened view of the playlist
221  * \param self the mediacontrol instance
222  * \param exception an initialized exception pointer
223  * \return a list of strings
224  */
225 VLC_PUBLIC_API mediacontrol_PlaylistSeq *
226   mediacontrol_playlist_get_list( mediacontrol_Instance *self,
227                                   mediacontrol_Exception *exception );
228
229 /**
230  * Play the next item
231  * \param self the mediacontrol instance
232  * \param exception an initialized exception pointer
233  */
234 VLC_PUBLIC_API void
235 mediacontrol_playlist_next_item( mediacontrol_Instance *self,
236                                  mediacontrol_Exception *exception );
237
238 /*****************************************************************************
239  * A/V functions
240  *****************************************************************************/
241 /**
242  * Get a snapshot
243  * \param self the mediacontrol instance
244  * \param a_position the desired position (ignored for now)
245  * \param exception an initialized exception pointer
246  * \return a RGBpicture
247  */
248 VLC_PUBLIC_API mediacontrol_RGBPicture *
249   mediacontrol_snapshot( mediacontrol_Instance *self,
250                          const mediacontrol_Position *a_position,
251                          mediacontrol_Exception *exception );
252
253 /* Return a NULL terminated list */
254 /**
255  * Get a list of all cached snapshots (unimplemented)
256  * \param self the mediacontrol instance
257  * \param exception an initialized exception pointer
258  * \return a NULL-terminated list of RGBpicture
259  */
260 VLC_PUBLIC_API mediacontrol_RGBPicture **
261   mediacontrol_all_snapshots( mediacontrol_Instance *self,
262                               mediacontrol_Exception *exception );
263
264 /**
265  *  Displays the message string, between "begin" and "end" positions.
266  * \param self the mediacontrol instance
267  * \param message the message to display
268  * \param begin the begin position
269  * \param end the end position
270  * \param exception an initialized exception pointer
271  */
272 VLC_PUBLIC_API void mediacontrol_display_text( mediacontrol_Instance *self,
273                                 const char *message,
274                                 const mediacontrol_Position *begin,
275                                 const mediacontrol_Position *end,
276                                 mediacontrol_Exception *exception );
277
278 /**
279  *  Get information about a stream
280  * \param self the mediacontrol instance
281  * \param a_key the time unit
282  * \param exception an initialized exception pointer
283  * \return a mediacontrol_StreamInformation
284  */
285 VLC_PUBLIC_API mediacontrol_StreamInformation *
286   mediacontrol_get_stream_information( mediacontrol_Instance *self,
287                                        mediacontrol_PositionKey a_key,
288                                        mediacontrol_Exception *exception );
289
290 /**
291  * Get the current audio level, normalized in [0..100]
292  * \param self the mediacontrol instance
293  * \param exception an initialized exception pointer
294  * \return the volume
295  */
296 VLC_PUBLIC_API unsigned short
297   mediacontrol_sound_get_volume( mediacontrol_Instance *self,
298                                  mediacontrol_Exception *exception );
299 /**
300  * Set the audio level
301  * \param self the mediacontrol instance
302  * \param volume the volume (normalized in [0..100])
303  * \param exception an initialized exception pointer
304  */
305 VLC_PUBLIC_API void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
306                                     const unsigned short volume,
307                                     mediacontrol_Exception *exception );
308
309 /**
310  * Set the video output window
311  * \param self the mediacontrol instance
312  * \param visual_id the Xid or HWND, depending on the platform
313  * \param exception an initialized exception pointer
314  */
315 VLC_PUBLIC_API vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
316                                     WINDOWHANDLE visual_id,
317                                     mediacontrol_Exception *exception );
318
319 /**
320  * Get the current playing rate, in percent
321  * \param self the mediacontrol instance
322  * \param exception an initialized exception pointer
323  * \return the rate
324  */
325 VLC_PUBLIC_API int mediacontrol_get_rate( mediacontrol_Instance *self,
326                mediacontrol_Exception *exception );
327
328 /**
329  * Set the playing rate, in percent
330  * \param self the mediacontrol instance
331  * \param rate the desired rate
332  * \param exception an initialized exception pointer
333  */
334 VLC_PUBLIC_API void mediacontrol_set_rate( mediacontrol_Instance *self,
335                 const int rate,
336                 mediacontrol_Exception *exception );
337
338 /**
339  * Get current fullscreen status
340  * \param self the mediacontrol instance
341  * \param exception an initialized exception pointer
342  * \return the fullscreen status
343  */
344 VLC_PUBLIC_API int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
345                  mediacontrol_Exception *exception );
346
347 /**
348  * Set fullscreen status
349  * \param self the mediacontrol instance
350  * \param b_fullscreen the desired status
351  * \param exception an initialized exception pointer
352  */
353 VLC_PUBLIC_API void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
354                   const int b_fullscreen,
355                   mediacontrol_Exception *exception );
356
357 # ifdef __cplusplus
358 }
359 # endif
360
361 #endif
362
363 /** @} */