1 /*****************************************************************************
2 * control.h: global header for mediacontrol
3 *****************************************************************************
4 * Copyright (C) 2005 the VideoLAN team
7 * Authors: Olivier Aubert <olivier.aubert@liris.univ-lyon1.fr>
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.
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.
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 *****************************************************************************/
25 * \defgroup mediacontrol MediaControl
26 * This is the MediaControl API, * intended to provide a generic API to movie players.
32 #ifndef _VLC_CONTROL_H
33 #define _VLC_CONTROL_H 1
41 #define WINDOWHANDLE HWND
43 #define WINDOWHANDLE int
46 #include <vlc/libvlc.h>
47 #include <vlc/mediacontrol_structures.h>
50 * mediacontrol_Instance is an opaque structure, defined in
51 * mediacontrol_internal.h. API users do not have to mess with it.
53 typedef struct mediacontrol_Instance mediacontrol_Instance;
55 /**************************************************************************
57 ***************************************************************************/
60 * Free a RGBPicture structure.
61 * \param pic: the RGBPicture structure
63 VLC_PUBLIC_API void mediacontrol_RGBPicture__free( mediacontrol_RGBPicture *pic );
65 VLC_PUBLIC_API void mediacontrol_PlaylistSeq__free( mediacontrol_PlaylistSeq *ps );
68 * Free a StreamInformation structure.
69 * \param pic: the StreamInformation structure
72 mediacontrol_StreamInformation__free( mediacontrol_StreamInformation* p_si );
75 * Instanciate and initialize an exception structure.
76 * \return the exception
78 VLC_PUBLIC_API mediacontrol_Exception *
79 mediacontrol_exception_create( void );
82 * Initialize an existing exception structure.
83 * \param p_exception the exception to initialize.
86 mediacontrol_exception_init( mediacontrol_Exception *exception );
89 * Free an exception structure.
90 * \return the exception
92 VLC_PUBLIC_API void mediacontrol_exception_free(mediacontrol_Exception *exception);
94 /*****************************************************************************
96 *****************************************************************************/
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
105 VLC_PUBLIC_API mediacontrol_Instance *
106 mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
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
114 VLC_PUBLIC_API mediacontrol_Instance *
115 mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
116 mediacontrol_Exception *exception );
119 * Get the associated libvlc instance
120 * \param self: the mediacontrol instance
121 * \return a libvlc instance
123 VLC_PUBLIC_API libvlc_instance_t*
124 mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
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
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 );
142 * \param self the mediacontrol instance
143 * \param a_position a mediacontrol_Position
144 * \param exception an initialized exception pointer
146 VLC_PUBLIC_API void mediacontrol_set_media_position( mediacontrol_Instance *self,
147 const mediacontrol_Position *a_position,
148 mediacontrol_Exception *exception );
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
156 VLC_PUBLIC_API void mediacontrol_start( mediacontrol_Instance *self,
157 const mediacontrol_Position *a_position,
158 mediacontrol_Exception *exception );
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
166 VLC_PUBLIC_API void mediacontrol_pause( mediacontrol_Instance *self,
167 const mediacontrol_Position *a_position,
168 mediacontrol_Exception *exception );
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
176 VLC_PUBLIC_API void mediacontrol_resume( mediacontrol_Instance *self,
177 const mediacontrol_Position *a_position,
178 mediacontrol_Exception *exception );
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
186 VLC_PUBLIC_API void mediacontrol_stop( mediacontrol_Instance *self,
187 const mediacontrol_Position *a_position,
188 mediacontrol_Exception *exception );
192 * \param self the mediacontrol instance
194 VLC_PUBLIC_API void mediacontrol_exit( mediacontrol_Instance *self );
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
202 VLC_PUBLIC_API void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
203 const char* psz_file,
204 mediacontrol_Exception *exception );
207 * \param self the mediacontrol instance
208 * \param exception an initialized exception pointer
210 VLC_PUBLIC_API void mediacontrol_playlist_clear( mediacontrol_Instance *self,
211 mediacontrol_Exception *exception );
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
218 VLC_PUBLIC_API mediacontrol_PlaylistSeq *
219 mediacontrol_playlist_get_list( mediacontrol_Instance *self,
220 mediacontrol_Exception *exception );
224 * \param self the mediacontrol instance
225 * \param exception an initialized exception pointer
228 mediacontrol_playlist_next_item( mediacontrol_Instance *self,
229 mediacontrol_Exception *exception );
231 /*****************************************************************************
233 *****************************************************************************/
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
241 VLC_PUBLIC_API mediacontrol_RGBPicture *
242 mediacontrol_snapshot( mediacontrol_Instance *self,
243 const mediacontrol_Position *a_position,
244 mediacontrol_Exception *exception );
246 /* Return a NULL terminated list */
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
253 VLC_PUBLIC_API mediacontrol_RGBPicture **
254 mediacontrol_all_snapshots( mediacontrol_Instance *self,
255 mediacontrol_Exception *exception );
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
265 VLC_PUBLIC_API void mediacontrol_display_text( mediacontrol_Instance *self,
267 const mediacontrol_Position *begin,
268 const mediacontrol_Position *end,
269 mediacontrol_Exception *exception );
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
278 VLC_PUBLIC_API mediacontrol_StreamInformation *
279 mediacontrol_get_stream_information( mediacontrol_Instance *self,
280 mediacontrol_PositionKey a_key,
281 mediacontrol_Exception *exception );
284 * Get the current audio level, normalized in [0..100]
285 * \param self the mediacontrol instance
286 * \param exception an initialized exception pointer
289 VLC_PUBLIC_API unsigned short
290 mediacontrol_sound_get_volume( mediacontrol_Instance *self,
291 mediacontrol_Exception *exception );
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
298 VLC_PUBLIC_API void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
299 const unsigned short volume,
300 mediacontrol_Exception *exception );
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
308 VLC_PUBLIC_API vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
309 WINDOWHANDLE visual_id,
310 mediacontrol_Exception *exception );
313 * Get the current playing rate, in percent
314 * \param self the mediacontrol instance
315 * \param exception an initialized exception pointer
318 VLC_PUBLIC_API int mediacontrol_get_rate( mediacontrol_Instance *self,
319 mediacontrol_Exception *exception );
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
327 VLC_PUBLIC_API void mediacontrol_set_rate( mediacontrol_Instance *self,
329 mediacontrol_Exception *exception );
332 * Get current fullscreen status
333 * \param self the mediacontrol instance
334 * \param exception an initialized exception pointer
335 * \return the fullscreen status
337 VLC_PUBLIC_API int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
338 mediacontrol_Exception *exception );
341 * Set fullscreen status
342 * \param self the mediacontrol instance
343 * \param b_fullscreen the desired status
344 * \param exception an initialized exception pointer
346 VLC_PUBLIC_API void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
347 const int b_fullscreen,
348 mediacontrol_Exception *exception );