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