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