mediacontrol.h 12.4 KB
Newer Older
zorglub's avatar
zorglub committed
1
2
3
/*****************************************************************************
 * control.h: global header for mediacontrol
 *****************************************************************************
4
 * Copyright (C) 2005 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
 *****************************************************************************/

Olivier Aubert's avatar
Olivier Aubert committed
24
/**
25
 * \defgroup mediacontrol MediaControl
Olivier Aubert's avatar
Olivier Aubert committed
26
27
28
29
30
31
 * This is the MediaControl API, * intended to provide a generic API to movie players.
 *
 * @{
 */


zorglub's avatar
zorglub committed
32
33
34
35
36
37
38
39
#ifndef _VLC_CONTROL_H
#define _VLC_CONTROL_H 1

# ifdef __cplusplus
extern "C" {
# endif

#if defined( WIN32 )
40
#include <windows.h>
zorglub's avatar
zorglub committed
41
42
43
44
45
#define WINDOWHANDLE HWND
#else
#define WINDOWHANDLE int
#endif

Rafaël Carré's avatar
Rafaël Carré committed
46
#include <vlc/libvlc.h>
zorglub's avatar
zorglub committed
47
#include <vlc/mediacontrol_structures.h>
48

Olivier Aubert's avatar
Olivier Aubert committed
49
50
/**
 * mediacontrol_Instance is an opaque structure, defined in
51
 * mediacontrol_internal.h. API users do not have to mess with it.
Olivier Aubert's avatar
Olivier Aubert committed
52
 */
53
typedef struct mediacontrol_Instance mediacontrol_Instance;
zorglub's avatar
zorglub committed
54
55
56
57

/**************************************************************************
 *  Helper functions
 ***************************************************************************/
58

Olivier Aubert's avatar
Olivier Aubert committed
59
60
61
62
/**
 * Free a RGBPicture structure.
 * \param pic: the RGBPicture structure
 */
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
69
70
71
72
73
/**
 * 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
74
/**
75
 * Instanciate and initialize an exception structure.
Olivier Aubert's avatar
Olivier Aubert committed
76
77
 * \return the exception
 */
78
VLC_PUBLIC_API mediacontrol_Exception *
79
80
81
82
83
84
85
  mediacontrol_exception_create( void );

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

Olivier Aubert's avatar
Olivier Aubert committed
88
/**
89
90
91
92
93
94
95
96
 * 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().
Olivier Aubert's avatar
Olivier Aubert committed
97
98
 * \return the exception
 */
99
VLC_PUBLIC_API void mediacontrol_exception_free(mediacontrol_Exception *exception);
zorglub's avatar
zorglub committed
100
101
102
103

/*****************************************************************************
 * Core functions
 *****************************************************************************/
Olivier Aubert's avatar
Olivier Aubert committed
104
105
106
107
108
109
110
111

/**
 * 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
 */
112
VLC_PUBLIC_API mediacontrol_Instance *
113
mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
114

Olivier Aubert's avatar
Olivier Aubert committed
115
116
117
118
119
120
/**
 * 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
 */
121
VLC_PUBLIC_API mediacontrol_Instance *
122
mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
123
                mediacontrol_Exception *exception );
124

Olivier Aubert's avatar
Olivier Aubert committed
125
126
127
128
129
/**
 * Get the associated libvlc instance
 * \param self: the mediacontrol instance
 * \return a libvlc instance
 */
130
VLC_PUBLIC_API libvlc_instance_t*
131
mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
132

Olivier Aubert's avatar
Olivier Aubert committed
133
134
135
136
137
138
139
140
/**
 * 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
 */
141
VLC_PUBLIC_API mediacontrol_Position * mediacontrol_get_media_position(
142
143
144
145
146
                         mediacontrol_Instance *self,
                         const mediacontrol_PositionOrigin an_origin,
                         const mediacontrol_PositionKey a_key,
                         mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
147
148
149
150
151
152
/**
 * Set the position
 * \param self the mediacontrol instance
 * \param a_position a mediacontrol_Position
 * \param exception an initialized exception pointer
 */
153
VLC_PUBLIC_API void mediacontrol_set_media_position( mediacontrol_Instance *self,
154
155
                                      const mediacontrol_Position *a_position,
                                      mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
156

Olivier Aubert's avatar
Olivier Aubert committed
157
158
159
160
161
162
/**
 * Play the movie at a given position
 * \param self the mediacontrol instance
 * \param a_position a mediacontrol_Position
 * \param exception an initialized exception pointer
 */
163
VLC_PUBLIC_API void mediacontrol_start( mediacontrol_Instance *self,
164
165
166
                         const mediacontrol_Position *a_position,
                         mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
167
168
169
170
171
172
/**
 * Pause the movie at a given position
 * \param self the mediacontrol instance
 * \param a_position a mediacontrol_Position (ignored for now)
 * \param exception an initialized exception pointer
 */
173
VLC_PUBLIC_API void mediacontrol_pause( mediacontrol_Instance *self,
174
                         const mediacontrol_Position *a_position,
175
                         mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
176

Olivier Aubert's avatar
Olivier Aubert committed
177
178
179
180
181
182
/**
 * Resume the movie at a given position
 * \param self the mediacontrol instance
 * \param a_position a mediacontrol_Position (ignored for now)
 * \param exception an initialized exception pointer
 */
183
VLC_PUBLIC_API void mediacontrol_resume( mediacontrol_Instance *self,
184
185
                          const mediacontrol_Position *a_position,
                          mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
186

Olivier Aubert's avatar
Olivier Aubert committed
187
188
189
190
191
192
/**
 * Stop the movie at a given position
 * \param self the mediacontrol instance
 * \param a_position a mediacontrol_Position (ignored for now)
 * \param exception an initialized exception pointer
 */
193
VLC_PUBLIC_API void mediacontrol_stop( mediacontrol_Instance *self,
194
195
                        const mediacontrol_Position *a_position,
                        mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
196

Olivier Aubert's avatar
Olivier Aubert committed
197
198
199
200
/**
 * Exit the player
 * \param self the mediacontrol instance
 */
201
VLC_PUBLIC_API void mediacontrol_exit( mediacontrol_Instance *self );
zorglub's avatar
zorglub committed
202

Olivier Aubert's avatar
Olivier Aubert committed
203
204
205
206
207
208
/**
 * Add a new MRL to the playlist
 * \param self the mediacontrol instance
 * \param psz_file the MRL
 * \param exception an initialized exception pointer
 */
209
VLC_PUBLIC_API void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
zorglub's avatar
zorglub committed
210
                                     const char* psz_file,
211
                                     mediacontrol_Exception *exception );
Olivier Aubert's avatar
Olivier Aubert committed
212
213
214
215
216
/**
 * Clear the playlist
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 */
217
VLC_PUBLIC_API void mediacontrol_playlist_clear( mediacontrol_Instance *self,
218
                                  mediacontrol_Exception *exception );
Olivier Aubert's avatar
Olivier Aubert committed
219
220
221
222
223
224
/**
 * Get a flattened view of the playlist
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return a list of strings
 */
225
VLC_PUBLIC_API mediacontrol_PlaylistSeq *
226
227
  mediacontrol_playlist_get_list( mediacontrol_Instance *self,
                                  mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
228

229
230
231
232
233
/**
 * Play the next item
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 */
234
VLC_PUBLIC_API void
235
236
mediacontrol_playlist_next_item( mediacontrol_Instance *self,
                                 mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
237
238
239
240

/*****************************************************************************
 * A/V functions
 *****************************************************************************/
Olivier Aubert's avatar
Olivier Aubert committed
241
242
243
244
245
246
247
/**
 * 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
 */
248
VLC_PUBLIC_API mediacontrol_RGBPicture *
249
250
251
  mediacontrol_snapshot( mediacontrol_Instance *self,
                         const mediacontrol_Position *a_position,
                         mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
252
253

/* Return a NULL terminated list */
Olivier Aubert's avatar
Olivier Aubert committed
254
255
256
257
258
259
/**
 * Get a list of all cached snapshots (unimplemented)
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return a NULL-terminated list of RGBpicture
 */
260
VLC_PUBLIC_API mediacontrol_RGBPicture **
261
262
263
  mediacontrol_all_snapshots( mediacontrol_Instance *self,
                              mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
264
265
266
267
268
269
270
271
/**
 *  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
 */
272
VLC_PUBLIC_API void mediacontrol_display_text( mediacontrol_Instance *self,
273
274
                                const char *message,
                                const mediacontrol_Position *begin,
275
276
277
                                const mediacontrol_Position *end,
                                mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
278
279
280
281
282
283
284
/**
 *  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
 */
285
VLC_PUBLIC_API mediacontrol_StreamInformation *
286
287
288
289
  mediacontrol_get_stream_information( mediacontrol_Instance *self,
                                       mediacontrol_PositionKey a_key,
                                       mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
290
291
292
293
294
295
/**
 * Get the current audio level, normalized in [0..100]
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return the volume
 */
296
VLC_PUBLIC_API unsigned short
297
298
  mediacontrol_sound_get_volume( mediacontrol_Instance *self,
                                 mediacontrol_Exception *exception );
Olivier Aubert's avatar
Olivier Aubert committed
299
300
301
302
303
304
/**
 * Set the audio level
 * \param self the mediacontrol instance
 * \param volume the volume (normalized in [0..100])
 * \param exception an initialized exception pointer
 */
305
VLC_PUBLIC_API void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
306
307
308
                                    const unsigned short volume,
                                    mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
309
310
311
312
313
314
/**
 * 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
 */
315
VLC_PUBLIC_API vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
316
317
                                    WINDOWHANDLE visual_id,
                                    mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
318

Olivier Aubert's avatar
Olivier Aubert committed
319
320
321
322
323
324
/**
 * Get the current playing rate, in percent
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return the rate
 */
325
VLC_PUBLIC_API int mediacontrol_get_rate( mediacontrol_Instance *self,
326
               mediacontrol_Exception *exception );
327

Olivier Aubert's avatar
Olivier Aubert committed
328
329
330
331
332
333
/**
 * Set the playing rate, in percent
 * \param self the mediacontrol instance
 * \param rate the desired rate
 * \param exception an initialized exception pointer
 */
334
VLC_PUBLIC_API void mediacontrol_set_rate( mediacontrol_Instance *self,
335
336
                const int rate,
                mediacontrol_Exception *exception );
337

Olivier Aubert's avatar
Olivier Aubert committed
338
339
340
341
342
343
/**
 * Get current fullscreen status
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return the fullscreen status
 */
344
VLC_PUBLIC_API int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
345
                 mediacontrol_Exception *exception );
346

Olivier Aubert's avatar
Olivier Aubert committed
347
348
349
350
351
352
/**
 * Set fullscreen status
 * \param self the mediacontrol instance
 * \param b_fullscreen the desired status
 * \param exception an initialized exception pointer
 */
353
VLC_PUBLIC_API void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
354
355
                  const int b_fullscreen,
                  mediacontrol_Exception *exception );
356

zorglub's avatar
zorglub committed
357
358
359
360
361
# ifdef __cplusplus
}
# endif

#endif
Olivier Aubert's avatar
Olivier Aubert committed
362
363

/** @} */