mediacontrol.h 11.4 KB
Newer Older
zorglub's avatar
zorglub committed
1
/*****************************************************************************
2
 * mediacontrol.h: global header for mediacontrol
zorglub's avatar
zorglub committed
3
 *****************************************************************************
4
 * Copyright (C) 2005-2008 the VideoLAN team
5
 * $Id$
zorglub's avatar
zorglub committed
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 *
 * Authors: Olivier Aubert <olivier.aubert@liris.univ-lyon1.fr>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
dionoea's avatar
dionoea committed
21
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
zorglub's avatar
zorglub committed
22
23
 *****************************************************************************/

24
25
26
27
28
/**
 * \file
 * This file defines libvlc mediacontrol_* external API
 */

Olivier Aubert's avatar
Olivier Aubert committed
29
/**
30
 * \defgroup mediacontrol MediaControl
Olivier Aubert's avatar
Olivier Aubert committed
31
32
33
34
35
36
 * This is the MediaControl API, * intended to provide a generic API to movie players.
 *
 * @{
 */


37
38
#ifndef VLC_CONTROL_H
#define VLC_CONTROL_H 1
zorglub's avatar
zorglub committed
39
40
41
42
43
44

# ifdef __cplusplus
extern "C" {
# endif

#if defined( WIN32 )
45
#include <windows.h>
46
typedef HWND WINDOWHANDLE;
zorglub's avatar
zorglub committed
47
#else
48
typedef int WINDOWHANDLE;
zorglub's avatar
zorglub committed
49
50
#endif

Rafaël Carré's avatar
Rafaël Carré committed
51
#include <vlc/libvlc.h>
zorglub's avatar
zorglub committed
52
#include <vlc/mediacontrol_structures.h>
53

Olivier Aubert's avatar
Olivier Aubert committed
54
55
/**
 * mediacontrol_Instance is an opaque structure, defined in
56
 * mediacontrol_internal.h. API users do not have to mess with it.
Olivier Aubert's avatar
Olivier Aubert committed
57
 */
58
typedef struct mediacontrol_Instance mediacontrol_Instance;
zorglub's avatar
zorglub committed
59
60
61
62

/**************************************************************************
 *  Helper functions
 ***************************************************************************/
63

Olivier Aubert's avatar
Olivier Aubert committed
64
65
66
67
/**
 * Free a RGBPicture structure.
 * \param pic: the RGBPicture structure
 */
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
74
75
76
77
78
/**
 * Free a StreamInformation structure.
 * \param pic: the StreamInformation structure
 */
VLC_PUBLIC_API void
mediacontrol_StreamInformation__free( mediacontrol_StreamInformation* p_si );

Olivier Aubert's avatar
Olivier Aubert committed
79
/**
80
 * Instanciate and initialize an exception structure.
Olivier Aubert's avatar
Olivier Aubert committed
81
82
 * \return the exception
 */
83
VLC_PUBLIC_API mediacontrol_Exception *
84
85
86
87
88
89
90
  mediacontrol_exception_create( void );

/**
 * Initialize an existing exception structure.
 * \param p_exception the exception to initialize.
 */
VLC_PUBLIC_API void
91
92
  mediacontrol_exception_init( mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
93
/**
94
95
96
97
98
99
100
101
 * Clean up an existing exception structure after use.
 * \param p_exception the exception to clean up.
 */
VLC_PUBLIC_API void
mediacontrol_exception_cleanup( mediacontrol_Exception *exception );

/**
 * Free an exception structure created with mediacontrol_exception_create().
102
 * \param p_exception the exception to free.
Olivier Aubert's avatar
Olivier Aubert committed
103
 */
104
VLC_PUBLIC_API void mediacontrol_exception_free(mediacontrol_Exception *exception);
zorglub's avatar
zorglub committed
105
106
107
108

/*****************************************************************************
 * Core functions
 *****************************************************************************/
Olivier Aubert's avatar
Olivier Aubert committed
109
110
111
112
113
114
115
116

/**
 * Create a MediaControl instance with parameters
 * \param argc the number of arguments
 * \param argv parameters
 * \param exception an initialized exception pointer
 * \return a mediacontrol_Instance
 */
117
VLC_PUBLIC_API mediacontrol_Instance *
118
mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
119

Olivier Aubert's avatar
Olivier Aubert committed
120
121
122
123
124
125
/**
 * Create a MediaControl instance from an existing libvlc instance
 * \param p_instance the libvlc instance
 * \param exception an initialized exception pointer
 * \return a mediacontrol_Instance
 */
126
VLC_PUBLIC_API mediacontrol_Instance *
127
mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
128
                mediacontrol_Exception *exception );
129

Olivier Aubert's avatar
Olivier Aubert committed
130
131
132
133
134
/**
 * Get the associated libvlc instance
 * \param self: the mediacontrol instance
 * \return a libvlc instance
 */
135
VLC_PUBLIC_API libvlc_instance_t*
136
mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
137

138
139
140
141
142
143
144
145
/**
 * Get the associated libvlc_media_player
 * \param self: the mediacontrol instance
 * \return a libvlc_media_player_t instance
 */
VLC_PUBLIC_API libvlc_media_player_t*
mediacontrol_get_media_player( mediacontrol_Instance* self );

Olivier Aubert's avatar
Olivier Aubert committed
146
147
148
149
150
151
152
153
/**
 * Get the current position
 * \param self the mediacontrol instance
 * \param an_origin the position origin
 * \param a_key the position unit
 * \param exception an initialized exception pointer
 * \return a mediacontrol_Position
 */
154
VLC_PUBLIC_API mediacontrol_Position * mediacontrol_get_media_position(
155
156
157
158
159
                         mediacontrol_Instance *self,
                         const mediacontrol_PositionOrigin an_origin,
                         const mediacontrol_PositionKey a_key,
                         mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
160
161
162
163
164
165
/**
 * Set the position
 * \param self the mediacontrol instance
 * \param a_position a mediacontrol_Position
 * \param exception an initialized exception pointer
 */
166
VLC_PUBLIC_API void mediacontrol_set_media_position( mediacontrol_Instance *self,
167
168
                                      const mediacontrol_Position *a_position,
                                      mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
169

Olivier Aubert's avatar
Olivier Aubert committed
170
171
172
173
174
175
/**
 * Play the movie at a given position
 * \param self the mediacontrol instance
 * \param a_position a mediacontrol_Position
 * \param exception an initialized exception pointer
 */
176
VLC_PUBLIC_API void mediacontrol_start( mediacontrol_Instance *self,
177
178
179
                         const mediacontrol_Position *a_position,
                         mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
180
181
182
183
184
/**
 * Pause the movie at a given position
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 */
185
VLC_PUBLIC_API void mediacontrol_pause( mediacontrol_Instance *self,
186
                         mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
187

Olivier Aubert's avatar
Olivier Aubert committed
188
189
190
191
192
/**
 * Resume the movie at a given position
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 */
193
VLC_PUBLIC_API void mediacontrol_resume( mediacontrol_Instance *self,
194
                          mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
195

Olivier Aubert's avatar
Olivier Aubert committed
196
197
198
199
200
/**
 * Stop the movie at a given position
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 */
201
VLC_PUBLIC_API void mediacontrol_stop( mediacontrol_Instance *self,
202
                        mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
203

Olivier Aubert's avatar
Olivier Aubert committed
204
205
206
207
/**
 * Exit the player
 * \param self the mediacontrol instance
 */
208
VLC_PUBLIC_API void mediacontrol_exit( mediacontrol_Instance *self );
zorglub's avatar
zorglub committed
209

Olivier Aubert's avatar
Olivier Aubert committed
210
/**
211
 * Set the MRL to be played.
Olivier Aubert's avatar
Olivier Aubert committed
212
213
214
215
 * \param self the mediacontrol instance
 * \param psz_file the MRL
 * \param exception an initialized exception pointer
 */
216
VLC_PUBLIC_API void mediacontrol_set_mrl( mediacontrol_Instance *self,
zorglub's avatar
zorglub committed
217
                                     const char* psz_file,
218
                                     mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
219

220
/**
221
 * Get the MRL to be played.
222
223
224
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 */
225
VLC_PUBLIC_API char * mediacontrol_get_mrl( mediacontrol_Instance *self,
226
                                            mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
227
228
229
230

/*****************************************************************************
 * A/V functions
 *****************************************************************************/
Olivier Aubert's avatar
Olivier Aubert committed
231
232
233
234
235
236
237
/**
 * Get a snapshot
 * \param self the mediacontrol instance
 * \param a_position the desired position (ignored for now)
 * \param exception an initialized exception pointer
 * \return a RGBpicture
 */
238
VLC_PUBLIC_API mediacontrol_RGBPicture *
239
240
241
  mediacontrol_snapshot( mediacontrol_Instance *self,
                         const mediacontrol_Position *a_position,
                         mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
242

Olivier Aubert's avatar
Olivier Aubert committed
243
244
245
246
247
248
249
250
/**
 *  Displays the message string, between "begin" and "end" positions.
 * \param self the mediacontrol instance
 * \param message the message to display
 * \param begin the begin position
 * \param end the end position
 * \param exception an initialized exception pointer
 */
251
VLC_PUBLIC_API void mediacontrol_display_text( mediacontrol_Instance *self,
252
253
                                const char *message,
                                const mediacontrol_Position *begin,
254
255
256
                                const mediacontrol_Position *end,
                                mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
257
258
259
260
261
262
263
/**
 *  Get information about a stream
 * \param self the mediacontrol instance
 * \param a_key the time unit
 * \param exception an initialized exception pointer
 * \return a mediacontrol_StreamInformation
 */
264
VLC_PUBLIC_API mediacontrol_StreamInformation *
265
266
267
268
  mediacontrol_get_stream_information( mediacontrol_Instance *self,
                                       mediacontrol_PositionKey a_key,
                                       mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
269
270
271
272
273
274
/**
 * Get the current audio level, normalized in [0..100]
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return the volume
 */
275
VLC_PUBLIC_API unsigned short
276
277
  mediacontrol_sound_get_volume( mediacontrol_Instance *self,
                                 mediacontrol_Exception *exception );
Olivier Aubert's avatar
Olivier Aubert committed
278
279
280
281
282
283
/**
 * Set the audio level
 * \param self the mediacontrol instance
 * \param volume the volume (normalized in [0..100])
 * \param exception an initialized exception pointer
 */
284
VLC_PUBLIC_API void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
285
286
287
                                    const unsigned short volume,
                                    mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
288
289
290
291
292
293
/**
 * Set the video output window
 * \param self the mediacontrol instance
 * \param visual_id the Xid or HWND, depending on the platform
 * \param exception an initialized exception pointer
 */
294
VLC_PUBLIC_API int mediacontrol_set_visual( mediacontrol_Instance *self,
295
296
                                    WINDOWHANDLE visual_id,
                                    mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
297

Olivier Aubert's avatar
Olivier Aubert committed
298
299
300
301
302
303
/**
 * Get the current playing rate, in percent
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return the rate
 */
304
VLC_PUBLIC_API int mediacontrol_get_rate( mediacontrol_Instance *self,
305
               mediacontrol_Exception *exception );
306

Olivier Aubert's avatar
Olivier Aubert committed
307
308
309
310
311
312
/**
 * Set the playing rate, in percent
 * \param self the mediacontrol instance
 * \param rate the desired rate
 * \param exception an initialized exception pointer
 */
313
VLC_PUBLIC_API void mediacontrol_set_rate( mediacontrol_Instance *self,
314
315
                const int rate,
                mediacontrol_Exception *exception );
316

Olivier Aubert's avatar
Olivier Aubert committed
317
318
319
320
321
322
/**
 * Get current fullscreen status
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return the fullscreen status
 */
323
VLC_PUBLIC_API int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
324
                 mediacontrol_Exception *exception );
325

Olivier Aubert's avatar
Olivier Aubert committed
326
327
328
329
330
331
/**
 * Set fullscreen status
 * \param self the mediacontrol instance
 * \param b_fullscreen the desired status
 * \param exception an initialized exception pointer
 */
332
VLC_PUBLIC_API void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
333
334
                  const int b_fullscreen,
                  mediacontrol_Exception *exception );
335

zorglub's avatar
zorglub committed
336
337
338
339
340
# ifdef __cplusplus
}
# endif

#endif
Olivier Aubert's avatar
Olivier Aubert committed
341
342

/** @} */