mediacontrol API: split old mediacontrol_exception_init behaviour into mediacontrol_e...
[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  * RGBPicture structure
50  * This generic structure holds a picture in an encoding specified by type.
51  */
52 typedef struct {
53     int  width;
54     int  height;
55     long type;
56     vlc_int64_t date;
57     int  size;
58     char *data;
59 } mediacontrol_RGBPicture;
60
61 /**
62  * Playlist sequence
63  * A simple list of strings.
64  */
65 typedef struct {
66     int size;
67     char **data;
68 } mediacontrol_PlaylistSeq;
69
70 typedef struct {
71     int code;
72     char *message;
73 } mediacontrol_Exception;
74
75 /**
76  * Exception codes
77  */
78 #define mediacontrol_PositionKeyNotSupported    1
79 #define mediacontrol_PositionOriginNotSupported 2
80 #define mediacontrol_InvalidPosition            3
81 #define mediacontrol_PlaylistException          4
82 #define mediacontrol_InternalException          5
83
84 /**
85  * mediacontrol_Instance is an opaque structure, defined in
86  * mediacontrol_internal.h. API users do not have to mess with it. 
87  */
88 typedef struct mediacontrol_Instance mediacontrol_Instance;
89
90 /**
91  * Possible player status
92  */
93 enum mediacontrol_PlayerStatusList
94 {
95     mediacontrol_PlayingStatus, mediacontrol_PauseStatus,
96     mediacontrol_ForwardStatus, mediacontrol_BackwardStatus,
97     mediacontrol_InitStatus,    mediacontrol_EndStatus,
98     mediacontrol_UndefinedStatus
99 };
100 typedef enum mediacontrol_PlayerStatusList mediacontrol_PlayerStatus;
101
102 /**
103  * Stream information
104  * This structure allows to quickly get various informations about the stream.
105  */
106 typedef struct {
107     mediacontrol_PlayerStatus streamstatus;
108     char *url;         /* The URL of the current media stream */
109     vlc_int64_t position;     /* actual location in the stream (in ms) */
110     vlc_int64_t length;         /* total length of the stream (in ms) */
111 } mediacontrol_StreamInformation;
112
113 /**************************************************************************
114  *  Helper functions
115  ***************************************************************************/
116
117 /**
118  * Allocate a RGBPicture structure.
119  * \param datasize: the size of the data
120  */
121 mediacontrol_RGBPicture *mediacontrol_RGBPicture__alloc( int datasize );
122
123 /**
124  * Free a RGBPicture structure.
125  * \param pic: the RGBPicture structure
126  */
127 VLC_PUBLIC_API void mediacontrol_RGBPicture__free( mediacontrol_RGBPicture *pic );
128
129 mediacontrol_RGBPicture *
130   _mediacontrol_createRGBPicture( int, int, long, vlc_int64_t l_date,
131                                   char *, int);
132
133 mediacontrol_PlaylistSeq *mediacontrol_PlaylistSeq__alloc( int size );
134
135 VLC_PUBLIC_API void mediacontrol_PlaylistSeq__free( mediacontrol_PlaylistSeq *ps );
136
137 /**
138  * Instanciate and initialize an exception structure.
139  * \return the exception
140  */
141 VLC_PUBLIC_API mediacontrol_Exception *
142   mediacontrol_exception_create( void );
143
144 /**
145  * Initialize an existing exception structure.
146  * \param p_exception the exception to initialize.
147  */
148 VLC_PUBLIC_API void
149   mediacontrol_exception_init( mediacontrol_Exception *exception );
150
151 /**
152  * Free an exception structure.
153  * \return the exception
154  */
155 VLC_PUBLIC_API void mediacontrol_exception_free(mediacontrol_Exception *exception);
156
157 /*****************************************************************************
158  * Core functions
159  *****************************************************************************/
160
161 /**
162  * Create a MediaControl instance with parameters
163  * \param argc the number of arguments
164  * \param argv parameters
165  * \param exception an initialized exception pointer
166  * \return a mediacontrol_Instance
167  */
168 VLC_PUBLIC_API mediacontrol_Instance *
169 mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
170
171 /**
172  * Create a MediaControl instance from an existing libvlc instance
173  * \param p_instance the libvlc instance
174  * \param exception an initialized exception pointer
175  * \return a mediacontrol_Instance
176  */
177 VLC_PUBLIC_API mediacontrol_Instance *
178 mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
179                                 mediacontrol_Exception *exception );
180
181 /**
182  * Get the associated libvlc instance
183  * \param self: the mediacontrol instance
184  * \return a libvlc instance
185  */
186 VLC_PUBLIC_API libvlc_instance_t*
187 mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
188
189 /**
190  * Get the current position
191  * \param self the mediacontrol instance
192  * \param an_origin the position origin
193  * \param a_key the position unit
194  * \param exception an initialized exception pointer
195  * \return a mediacontrol_Position
196  */
197 VLC_PUBLIC_API mediacontrol_Position * mediacontrol_get_media_position(
198                          mediacontrol_Instance *self,
199                          const mediacontrol_PositionOrigin an_origin,
200                          const mediacontrol_PositionKey a_key,
201                          mediacontrol_Exception *exception );
202
203 /**
204  * Set the position
205  * \param self the mediacontrol instance
206  * \param a_position a mediacontrol_Position
207  * \param exception an initialized exception pointer
208  */
209 VLC_PUBLIC_API void mediacontrol_set_media_position( mediacontrol_Instance *self,
210                                       const mediacontrol_Position *a_position,
211                                       mediacontrol_Exception *exception );
212
213 /**
214  * Play the movie at a given position
215  * \param self the mediacontrol instance
216  * \param a_position a mediacontrol_Position
217  * \param exception an initialized exception pointer
218  */
219 VLC_PUBLIC_API void mediacontrol_start( mediacontrol_Instance *self,
220                          const mediacontrol_Position *a_position,
221                          mediacontrol_Exception *exception );
222
223 /**
224  * Pause the movie at a given position
225  * \param self the mediacontrol instance
226  * \param a_position a mediacontrol_Position (ignored for now)
227  * \param exception an initialized exception pointer
228  */
229 VLC_PUBLIC_API void mediacontrol_pause( mediacontrol_Instance *self,
230                          const mediacontrol_Position *a_position,
231                          mediacontrol_Exception *exception );
232
233 /**
234  * Resume the movie at a given position
235  * \param self the mediacontrol instance
236  * \param a_position a mediacontrol_Position (ignored for now)
237  * \param exception an initialized exception pointer
238  */
239 VLC_PUBLIC_API void mediacontrol_resume( mediacontrol_Instance *self,
240                           const mediacontrol_Position *a_position,
241                           mediacontrol_Exception *exception );
242
243 /**
244  * Stop the movie at a given position
245  * \param self the mediacontrol instance
246  * \param a_position a mediacontrol_Position (ignored for now)
247  * \param exception an initialized exception pointer
248  */
249 VLC_PUBLIC_API void mediacontrol_stop( mediacontrol_Instance *self,
250                         const mediacontrol_Position *a_position,
251                         mediacontrol_Exception *exception );
252
253 /**
254  * Exit the player
255  * \param self the mediacontrol instance
256  */
257 VLC_PUBLIC_API void mediacontrol_exit( mediacontrol_Instance *self );
258
259 /**
260  * Add a new MRL to the playlist
261  * \param self the mediacontrol instance
262  * \param psz_file the MRL
263  * \param exception an initialized exception pointer
264  */
265 VLC_PUBLIC_API void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
266                                      const char* psz_file,
267                                      mediacontrol_Exception *exception );
268 /**
269  * Clear the playlist
270  * \param self the mediacontrol instance
271  * \param exception an initialized exception pointer
272  */
273 VLC_PUBLIC_API void mediacontrol_playlist_clear( mediacontrol_Instance *self,
274                                   mediacontrol_Exception *exception );
275 /**
276  * Get a flattened view of the playlist
277  * \param self the mediacontrol instance
278  * \param exception an initialized exception pointer
279  * \return a list of strings
280  */
281 VLC_PUBLIC_API mediacontrol_PlaylistSeq *
282   mediacontrol_playlist_get_list( mediacontrol_Instance *self,
283                                   mediacontrol_Exception *exception );
284
285 /**
286  * Play the next item
287  * \param self the mediacontrol instance
288  * \param exception an initialized exception pointer
289  */
290 VLC_PUBLIC_API void
291 mediacontrol_playlist_next_item( mediacontrol_Instance *self,
292                                  mediacontrol_Exception *exception );
293
294 /*****************************************************************************
295  * A/V functions
296  *****************************************************************************/
297 /**
298  * Get a snapshot
299  * \param self the mediacontrol instance
300  * \param a_position the desired position (ignored for now)
301  * \param exception an initialized exception pointer
302  * \return a RGBpicture
303  */
304 VLC_PUBLIC_API mediacontrol_RGBPicture *
305   mediacontrol_snapshot( mediacontrol_Instance *self,
306                          const mediacontrol_Position *a_position,
307                          mediacontrol_Exception *exception );
308
309 /* Return a NULL terminated list */
310 /**
311  * Get a list of all cached snapshots (unimplemented)
312  * \param self the mediacontrol instance
313  * \param exception an initialized exception pointer
314  * \return a NULL-terminated list of RGBpicture
315  */
316 VLC_PUBLIC_API mediacontrol_RGBPicture **
317   mediacontrol_all_snapshots( mediacontrol_Instance *self,
318                               mediacontrol_Exception *exception );
319
320 /**
321  *  Displays the message string, between "begin" and "end" positions.
322  * \param self the mediacontrol instance
323  * \param message the message to display
324  * \param begin the begin position
325  * \param end the end position
326  * \param exception an initialized exception pointer
327  */
328 VLC_PUBLIC_API void mediacontrol_display_text( mediacontrol_Instance *self,
329                                 const char *message,
330                                 const mediacontrol_Position *begin,
331                                 const mediacontrol_Position *end,
332                                 mediacontrol_Exception *exception );
333
334 /**
335  *  Get information about a stream
336  * \param self the mediacontrol instance
337  * \param a_key the time unit
338  * \param exception an initialized exception pointer
339  * \return a mediacontrol_StreamInformation
340  */
341 VLC_PUBLIC_API mediacontrol_StreamInformation *
342   mediacontrol_get_stream_information( mediacontrol_Instance *self,
343                                        mediacontrol_PositionKey a_key,
344                                        mediacontrol_Exception *exception );
345
346 /**
347  * Get the current audio level, normalized in [0..100]
348  * \param self the mediacontrol instance
349  * \param exception an initialized exception pointer
350  * \return the volume
351  */
352 VLC_PUBLIC_API unsigned short
353   mediacontrol_sound_get_volume( mediacontrol_Instance *self,
354                                  mediacontrol_Exception *exception );
355 /**
356  * Set the audio level
357  * \param self the mediacontrol instance
358  * \param volume the volume (normalized in [0..100])
359  * \param exception an initialized exception pointer
360  */
361 VLC_PUBLIC_API void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
362                                     const unsigned short volume,
363                                     mediacontrol_Exception *exception );
364
365 /**
366  * Set the video output window
367  * \param self the mediacontrol instance
368  * \param visual_id the Xid or HWND, depending on the platform
369  * \param exception an initialized exception pointer
370  */
371 VLC_PUBLIC_API vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
372                                     WINDOWHANDLE visual_id,
373                                     mediacontrol_Exception *exception );
374
375 /**
376  * Get the current playing rate, in percent
377  * \param self the mediacontrol instance
378  * \param exception an initialized exception pointer
379  * \return the rate
380  */
381 VLC_PUBLIC_API int mediacontrol_get_rate( mediacontrol_Instance *self,
382                            mediacontrol_Exception *exception );
383
384 /**
385  * Set the playing rate, in percent
386  * \param self the mediacontrol instance
387  * \param rate the desired rate
388  * \param exception an initialized exception pointer
389  */
390 VLC_PUBLIC_API void mediacontrol_set_rate( mediacontrol_Instance *self,
391                             const int rate,
392                             mediacontrol_Exception *exception );
393
394 /**
395  * Get current fullscreen status
396  * \param self the mediacontrol instance
397  * \param exception an initialized exception pointer
398  * \return the fullscreen status
399  */
400 VLC_PUBLIC_API int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
401                                  mediacontrol_Exception *exception );
402
403 /**
404  * Set fullscreen status
405  * \param self the mediacontrol instance
406  * \param b_fullscreen the desired status
407  * \param exception an initialized exception pointer
408  */
409 VLC_PUBLIC_API void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
410                                   const int b_fullscreen,
411                                   mediacontrol_Exception *exception );
412
413 # ifdef __cplusplus
414 }
415 # endif
416
417 #endif
418
419 /** @} */