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/mediacontrol_structures.h>
49 * RGBPicture structure
50 * This generic structure holds a picture in an encoding specified by type.
59 } mediacontrol_RGBPicture;
63 * A simple list of strings.
68 } mediacontrol_PlaylistSeq;
73 } mediacontrol_Exception;
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
85 * mediacontrol_Instance is an opaque structure, defined in
86 * mediacontrol_internal.h. API users do not have to mess with it.
88 typedef struct mediacontrol_Instance mediacontrol_Instance;
91 * Possible player status
93 enum mediacontrol_PlayerStatusList
95 mediacontrol_PlayingStatus, mediacontrol_PauseStatus,
96 mediacontrol_ForwardStatus, mediacontrol_BackwardStatus,
97 mediacontrol_InitStatus, mediacontrol_EndStatus,
98 mediacontrol_UndefinedStatus
100 typedef enum mediacontrol_PlayerStatusList mediacontrol_PlayerStatus;
104 * This structure allows to quickly get various informations about the stream.
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;
113 /**************************************************************************
115 ***************************************************************************/
118 * Allocate a RGBPicture structure.
119 * \param datasize: the size of the data
121 mediacontrol_RGBPicture *mediacontrol_RGBPicture__alloc( int datasize );
124 * Free a RGBPicture structure.
125 * \param pic: the RGBPicture structure
127 VLC_PUBLIC_API void mediacontrol_RGBPicture__free( mediacontrol_RGBPicture *pic );
129 mediacontrol_RGBPicture *
130 _mediacontrol_createRGBPicture( int, int, long, vlc_int64_t l_date,
133 mediacontrol_PlaylistSeq *mediacontrol_PlaylistSeq__alloc( int size );
135 VLC_PUBLIC_API void mediacontrol_PlaylistSeq__free( mediacontrol_PlaylistSeq *ps );
138 * Free a StreamInformation structure.
139 * \param pic: the StreamInformation structure
142 mediacontrol_StreamInformation__free( mediacontrol_StreamInformation* p_si );
145 * Instanciate and initialize an exception structure.
146 * \return the exception
148 VLC_PUBLIC_API mediacontrol_Exception *
149 mediacontrol_exception_create( void );
152 * Initialize an existing exception structure.
153 * \param p_exception the exception to initialize.
156 mediacontrol_exception_init( mediacontrol_Exception *exception );
159 * Free an exception structure.
160 * \return the exception
162 VLC_PUBLIC_API void mediacontrol_exception_free(mediacontrol_Exception *exception);
164 /*****************************************************************************
166 *****************************************************************************/
169 * Create a MediaControl instance with parameters
170 * \param argc the number of arguments
171 * \param argv parameters
172 * \param exception an initialized exception pointer
173 * \return a mediacontrol_Instance
175 VLC_PUBLIC_API mediacontrol_Instance *
176 mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
179 * Create a MediaControl instance from an existing libvlc instance
180 * \param p_instance the libvlc instance
181 * \param exception an initialized exception pointer
182 * \return a mediacontrol_Instance
184 VLC_PUBLIC_API mediacontrol_Instance *
185 mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
186 mediacontrol_Exception *exception );
189 * Get the associated libvlc instance
190 * \param self: the mediacontrol instance
191 * \return a libvlc instance
193 VLC_PUBLIC_API libvlc_instance_t*
194 mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
197 * Get the current position
198 * \param self the mediacontrol instance
199 * \param an_origin the position origin
200 * \param a_key the position unit
201 * \param exception an initialized exception pointer
202 * \return a mediacontrol_Position
204 VLC_PUBLIC_API mediacontrol_Position * mediacontrol_get_media_position(
205 mediacontrol_Instance *self,
206 const mediacontrol_PositionOrigin an_origin,
207 const mediacontrol_PositionKey a_key,
208 mediacontrol_Exception *exception );
212 * \param self the mediacontrol instance
213 * \param a_position a mediacontrol_Position
214 * \param exception an initialized exception pointer
216 VLC_PUBLIC_API void mediacontrol_set_media_position( mediacontrol_Instance *self,
217 const mediacontrol_Position *a_position,
218 mediacontrol_Exception *exception );
221 * Play the movie at a given position
222 * \param self the mediacontrol instance
223 * \param a_position a mediacontrol_Position
224 * \param exception an initialized exception pointer
226 VLC_PUBLIC_API void mediacontrol_start( mediacontrol_Instance *self,
227 const mediacontrol_Position *a_position,
228 mediacontrol_Exception *exception );
231 * Pause the movie at a given position
232 * \param self the mediacontrol instance
233 * \param a_position a mediacontrol_Position (ignored for now)
234 * \param exception an initialized exception pointer
236 VLC_PUBLIC_API void mediacontrol_pause( mediacontrol_Instance *self,
237 const mediacontrol_Position *a_position,
238 mediacontrol_Exception *exception );
241 * Resume the movie at a given position
242 * \param self the mediacontrol instance
243 * \param a_position a mediacontrol_Position (ignored for now)
244 * \param exception an initialized exception pointer
246 VLC_PUBLIC_API void mediacontrol_resume( mediacontrol_Instance *self,
247 const mediacontrol_Position *a_position,
248 mediacontrol_Exception *exception );
251 * Stop the movie at a given position
252 * \param self the mediacontrol instance
253 * \param a_position a mediacontrol_Position (ignored for now)
254 * \param exception an initialized exception pointer
256 VLC_PUBLIC_API void mediacontrol_stop( mediacontrol_Instance *self,
257 const mediacontrol_Position *a_position,
258 mediacontrol_Exception *exception );
262 * \param self the mediacontrol instance
264 VLC_PUBLIC_API void mediacontrol_exit( mediacontrol_Instance *self );
267 * Add a new MRL to the playlist
268 * \param self the mediacontrol instance
269 * \param psz_file the MRL
270 * \param exception an initialized exception pointer
272 VLC_PUBLIC_API void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
273 const char* psz_file,
274 mediacontrol_Exception *exception );
277 * \param self the mediacontrol instance
278 * \param exception an initialized exception pointer
280 VLC_PUBLIC_API void mediacontrol_playlist_clear( mediacontrol_Instance *self,
281 mediacontrol_Exception *exception );
283 * Get a flattened view of the playlist
284 * \param self the mediacontrol instance
285 * \param exception an initialized exception pointer
286 * \return a list of strings
288 VLC_PUBLIC_API mediacontrol_PlaylistSeq *
289 mediacontrol_playlist_get_list( mediacontrol_Instance *self,
290 mediacontrol_Exception *exception );
294 * \param self the mediacontrol instance
295 * \param exception an initialized exception pointer
298 mediacontrol_playlist_next_item( mediacontrol_Instance *self,
299 mediacontrol_Exception *exception );
301 /*****************************************************************************
303 *****************************************************************************/
306 * \param self the mediacontrol instance
307 * \param a_position the desired position (ignored for now)
308 * \param exception an initialized exception pointer
309 * \return a RGBpicture
311 VLC_PUBLIC_API mediacontrol_RGBPicture *
312 mediacontrol_snapshot( mediacontrol_Instance *self,
313 const mediacontrol_Position *a_position,
314 mediacontrol_Exception *exception );
316 /* Return a NULL terminated list */
318 * Get a list of all cached snapshots (unimplemented)
319 * \param self the mediacontrol instance
320 * \param exception an initialized exception pointer
321 * \return a NULL-terminated list of RGBpicture
323 VLC_PUBLIC_API mediacontrol_RGBPicture **
324 mediacontrol_all_snapshots( mediacontrol_Instance *self,
325 mediacontrol_Exception *exception );
328 * Displays the message string, between "begin" and "end" positions.
329 * \param self the mediacontrol instance
330 * \param message the message to display
331 * \param begin the begin position
332 * \param end the end position
333 * \param exception an initialized exception pointer
335 VLC_PUBLIC_API void mediacontrol_display_text( mediacontrol_Instance *self,
337 const mediacontrol_Position *begin,
338 const mediacontrol_Position *end,
339 mediacontrol_Exception *exception );
342 * Get information about a stream
343 * \param self the mediacontrol instance
344 * \param a_key the time unit
345 * \param exception an initialized exception pointer
346 * \return a mediacontrol_StreamInformation
348 VLC_PUBLIC_API mediacontrol_StreamInformation *
349 mediacontrol_get_stream_information( mediacontrol_Instance *self,
350 mediacontrol_PositionKey a_key,
351 mediacontrol_Exception *exception );
354 * Get the current audio level, normalized in [0..100]
355 * \param self the mediacontrol instance
356 * \param exception an initialized exception pointer
359 VLC_PUBLIC_API unsigned short
360 mediacontrol_sound_get_volume( mediacontrol_Instance *self,
361 mediacontrol_Exception *exception );
363 * Set the audio level
364 * \param self the mediacontrol instance
365 * \param volume the volume (normalized in [0..100])
366 * \param exception an initialized exception pointer
368 VLC_PUBLIC_API void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
369 const unsigned short volume,
370 mediacontrol_Exception *exception );
373 * Set the video output window
374 * \param self the mediacontrol instance
375 * \param visual_id the Xid or HWND, depending on the platform
376 * \param exception an initialized exception pointer
378 VLC_PUBLIC_API vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
379 WINDOWHANDLE visual_id,
380 mediacontrol_Exception *exception );
383 * Get the current playing rate, in percent
384 * \param self the mediacontrol instance
385 * \param exception an initialized exception pointer
388 VLC_PUBLIC_API int mediacontrol_get_rate( mediacontrol_Instance *self,
389 mediacontrol_Exception *exception );
392 * Set the playing rate, in percent
393 * \param self the mediacontrol instance
394 * \param rate the desired rate
395 * \param exception an initialized exception pointer
397 VLC_PUBLIC_API void mediacontrol_set_rate( mediacontrol_Instance *self,
399 mediacontrol_Exception *exception );
402 * Get current fullscreen status
403 * \param self the mediacontrol instance
404 * \param exception an initialized exception pointer
405 * \return the fullscreen status
407 VLC_PUBLIC_API int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
408 mediacontrol_Exception *exception );
411 * Set fullscreen status
412 * \param self the mediacontrol instance
413 * \param b_fullscreen the desired status
414 * \param exception an initialized exception pointer
416 VLC_PUBLIC_API void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
417 const int b_fullscreen,
418 mediacontrol_Exception *exception );