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