mediacontrol.h 13.2 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
26
27
28
29
30
31
/**
 * \defgroup mediacontrol MediaControl 
 * 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
40
41
42
43
44
#ifndef _VLC_CONTROL_H
#define _VLC_CONTROL_H 1

# ifdef __cplusplus
extern "C" {
# endif

#if defined( WIN32 )
#define WINDOWHANDLE HWND
#else
#define WINDOWHANDLE int
#endif

zorglub's avatar
zorglub committed
45
#include <vlc/mediacontrol_structures.h>
46

Olivier Aubert's avatar
Olivier Aubert committed
47
48
49
50
/**
 * RGBPicture structure
 * This generic structure holds a picture in an encoding specified by type.
 */
zorglub's avatar
zorglub committed
51
typedef struct {
52
53
54
55
56
57
    int  width;
    int  height;
    long type;
    vlc_int64_t date;
    int  size;
    char *data;
zorglub's avatar
zorglub committed
58
59
} mediacontrol_RGBPicture;

Olivier Aubert's avatar
Olivier Aubert committed
60
61
62
63
/**
 * Playlist sequence
 * A simple list of strings.
 */
zorglub's avatar
zorglub committed
64
typedef struct {
65
66
    int size;
    char **data;
zorglub's avatar
zorglub committed
67
68
69
} mediacontrol_PlaylistSeq;

typedef struct {
70
71
    int code;
    char *message;
zorglub's avatar
zorglub committed
72
73
} mediacontrol_Exception;

Olivier Aubert's avatar
Olivier Aubert committed
74
75
76
/**
 * Exception codes
 */
zorglub's avatar
zorglub committed
77
78
79
80
81
82
#define mediacontrol_PositionKeyNotSupported    1
#define mediacontrol_PositionOriginNotSupported 2
#define mediacontrol_InvalidPosition            3
#define mediacontrol_PlaylistException          4
#define mediacontrol_InternalException          5

Olivier Aubert's avatar
Olivier Aubert committed
83
84
85
86
/**
 * mediacontrol_Instance is an opaque structure, defined in
 * mediacontrol_internal.h. API users do not have to mess with it. 
 */
87
typedef struct mediacontrol_Instance mediacontrol_Instance;
zorglub's avatar
zorglub committed
88

Olivier Aubert's avatar
Olivier Aubert committed
89
90
91
/**
 * Possible player status
 */
zorglub's avatar
zorglub committed
92
enum mediacontrol_PlayerStatusList
93
{
zorglub's avatar
zorglub committed
94
95
96
97
    mediacontrol_PlayingStatus, mediacontrol_PauseStatus,
    mediacontrol_ForwardStatus, mediacontrol_BackwardStatus,
    mediacontrol_InitStatus,    mediacontrol_EndStatus,
    mediacontrol_UndefinedStatus
98
};
zorglub's avatar
zorglub committed
99
100
typedef enum mediacontrol_PlayerStatusList mediacontrol_PlayerStatus;

Olivier Aubert's avatar
Olivier Aubert committed
101
102
103
104
/**
 * Stream information
 * This structure allows to quickly get various informations about the stream.
 */
zorglub's avatar
zorglub committed
105
106
typedef struct {
    mediacontrol_PlayerStatus streamstatus;
107
108
109
110
    char *url;         /* The URL of the current media stream */
    vlc_int64_t position;     /* actual location in the stream (in ms) */
    vlc_int64_t length;         /* total length of the stream (in ms) */
} mediacontrol_StreamInformation;
zorglub's avatar
zorglub committed
111
112
113
114

/**************************************************************************
 *  Helper functions
 ***************************************************************************/
115

Olivier Aubert's avatar
Olivier Aubert committed
116
117
118
119
/**
 * Allocate a RGBPicture structure.
 * \param datasize: the size of the data
 */
120
121
mediacontrol_RGBPicture *mediacontrol_RGBPicture__alloc( int datasize );

Olivier Aubert's avatar
Olivier Aubert committed
122
123
124
125
/**
 * Free a RGBPicture structure.
 * \param pic: the RGBPicture structure
 */
126
127
128
129
130
131
132
133
134
135
void mediacontrol_RGBPicture__free( mediacontrol_RGBPicture *pic );

mediacontrol_RGBPicture *
  _mediacontrol_createRGBPicture( int, int, long, vlc_int64_t l_date,
                                  char *, int);

mediacontrol_PlaylistSeq *mediacontrol_PlaylistSeq__alloc( int size );

void mediacontrol_PlaylistSeq__free( mediacontrol_PlaylistSeq *ps );

Olivier Aubert's avatar
Olivier Aubert committed
136
137
138
139
140
/**
 * Initialize an exception structure.
 * \param p_exception the exception to initialize. If NULL, a new exception will be created.
 * \return the exception
 */
141
142
143
mediacontrol_Exception *
  mediacontrol_exception_init( mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
144
145
146
147
/**
 * Free an exception structure.
 * \return the exception
 */
zorglub's avatar
zorglub committed
148
149
150
151
152
void mediacontrol_exception_free(mediacontrol_Exception *exception);

/*****************************************************************************
 * Core functions
 *****************************************************************************/
Olivier Aubert's avatar
Olivier Aubert committed
153
154
155
156
157
158
159
160

/**
 * 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
 */
161
mediacontrol_Instance *
162
mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
163

Olivier Aubert's avatar
Olivier Aubert committed
164
165
166
167
168
169
/**
 * 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
 */
170
mediacontrol_Instance *
171
172
173
mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
				mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
174
175
176
177
178
/**
 * Get the associated libvlc instance
 * \param self: the mediacontrol instance
 * \return a libvlc instance
 */
179
180
libvlc_instance_t*
mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
181

Olivier Aubert's avatar
Olivier Aubert committed
182
183
184
185
186
187
188
189
/**
 * 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
 */
190
mediacontrol_Position * mediacontrol_get_media_position(
191
192
193
194
195
                         mediacontrol_Instance *self,
                         const mediacontrol_PositionOrigin an_origin,
                         const mediacontrol_PositionKey a_key,
                         mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
196
197
198
199
200
201
/**
 * Set the position
 * \param self the mediacontrol instance
 * \param a_position a mediacontrol_Position
 * \param exception an initialized exception pointer
 */
202
203
204
void mediacontrol_set_media_position( mediacontrol_Instance *self,
                                      const mediacontrol_Position *a_position,
                                      mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
205

Olivier Aubert's avatar
Olivier Aubert committed
206
207
208
209
210
211
/**
 * Play the movie at a given position
 * \param self the mediacontrol instance
 * \param a_position a mediacontrol_Position
 * \param exception an initialized exception pointer
 */
zorglub's avatar
zorglub committed
212
void mediacontrol_start( mediacontrol_Instance *self,
213
214
215
                         const mediacontrol_Position *a_position,
                         mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
216
217
218
219
220
221
/**
 * 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
 */
222
void mediacontrol_pause( mediacontrol_Instance *self,
223
                         const mediacontrol_Position *a_position,
224
                         mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
225

Olivier Aubert's avatar
Olivier Aubert committed
226
227
228
229
230
231
/**
 * 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
 */
232
233
234
void mediacontrol_resume( mediacontrol_Instance *self,
                          const mediacontrol_Position *a_position,
                          mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
235

Olivier Aubert's avatar
Olivier Aubert committed
236
237
238
239
240
241
/**
 * 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
 */
242
243
244
void mediacontrol_stop( mediacontrol_Instance *self,
                        const mediacontrol_Position *a_position,
                        mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
245

Olivier Aubert's avatar
Olivier Aubert committed
246
247
248
249
/**
 * Exit the player
 * \param self the mediacontrol instance
 */
250
void mediacontrol_exit( mediacontrol_Instance *self );
zorglub's avatar
zorglub committed
251

Olivier Aubert's avatar
Olivier Aubert committed
252
253
254
255
256
257
/**
 * Add a new MRL to the playlist
 * \param self the mediacontrol instance
 * \param psz_file the MRL
 * \param exception an initialized exception pointer
 */
258
void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
zorglub's avatar
zorglub committed
259
                                     const char* psz_file,
260
                                     mediacontrol_Exception *exception );
Olivier Aubert's avatar
Olivier Aubert committed
261
262
263
264
265
/**
 * Clear the playlist
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 */
266
267
void mediacontrol_playlist_clear( mediacontrol_Instance *self,
                                  mediacontrol_Exception *exception );
Olivier Aubert's avatar
Olivier Aubert committed
268
269
270
271
272
273
/**
 * Get a flattened view of the playlist
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return a list of strings
 */
274
275
276
mediacontrol_PlaylistSeq *
  mediacontrol_playlist_get_list( mediacontrol_Instance *self,
                                  mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
277

278
279
280
281
282
283
284
285
/**
 * Play the next item
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 */
void
mediacontrol_playlist_next_item( mediacontrol_Instance *self,
                                 mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
286
287
288
289

/*****************************************************************************
 * A/V functions
 *****************************************************************************/
Olivier Aubert's avatar
Olivier Aubert committed
290
291
292
293
294
295
296
/**
 * 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
 */
297
298
299
300
mediacontrol_RGBPicture *
  mediacontrol_snapshot( mediacontrol_Instance *self,
                         const mediacontrol_Position *a_position,
                         mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
301
302

/* Return a NULL terminated list */
Olivier Aubert's avatar
Olivier Aubert committed
303
304
305
306
307
308
/**
 * 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
 */
309
310
311
312
mediacontrol_RGBPicture **
  mediacontrol_all_snapshots( mediacontrol_Instance *self,
                              mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
313
314
315
316
317
318
319
320
/**
 *  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
 */
321
void mediacontrol_display_text( mediacontrol_Instance *self,
322
323
                                const char *message,
                                const mediacontrol_Position *begin,
324
325
326
                                const mediacontrol_Position *end,
                                mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
327
328
329
330
331
332
333
/**
 *  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
 */
334
335
336
337
338
mediacontrol_StreamInformation *
  mediacontrol_get_stream_information( mediacontrol_Instance *self,
                                       mediacontrol_PositionKey a_key,
                                       mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
339
340
341
342
343
344
/**
 * Get the current audio level, normalized in [0..100]
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return the volume
 */
345
346
347
unsigned short
  mediacontrol_sound_get_volume( mediacontrol_Instance *self,
                                 mediacontrol_Exception *exception );
Olivier Aubert's avatar
Olivier Aubert committed
348
349
350
351
352
353
/**
 * Set the audio level
 * \param self the mediacontrol instance
 * \param volume the volume (normalized in [0..100])
 * \param exception an initialized exception pointer
 */
354
355
356
357
void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
                                    const unsigned short volume,
                                    mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
358
359
360
361
362
363
/**
 * 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
 */
364
365
366
vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
                                    WINDOWHANDLE visual_id,
                                    mediacontrol_Exception *exception );
zorglub's avatar
zorglub committed
367

Olivier Aubert's avatar
Olivier Aubert committed
368
369
370
371
372
373
/**
 * Get the current playing rate, in percent
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return the rate
 */
374
375
376
int mediacontrol_get_rate( mediacontrol_Instance *self,
			   mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
377
378
379
380
381
382
/**
 * Set the playing rate, in percent
 * \param self the mediacontrol instance
 * \param rate the desired rate
 * \param exception an initialized exception pointer
 */
383
384
385
386
void mediacontrol_set_rate( mediacontrol_Instance *self,
			    const int rate,
			    mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
387
388
389
390
391
392
/**
 * Get current fullscreen status
 * \param self the mediacontrol instance
 * \param exception an initialized exception pointer
 * \return the fullscreen status
 */
393
394
395
int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
				 mediacontrol_Exception *exception );

Olivier Aubert's avatar
Olivier Aubert committed
396
397
398
399
400
401
/**
 * Set fullscreen status
 * \param self the mediacontrol instance
 * \param b_fullscreen the desired status
 * \param exception an initialized exception pointer
 */
402
403
404
405
void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
				  const int b_fullscreen,
				  mediacontrol_Exception *exception );

zorglub's avatar
zorglub committed
406
407
408
409
410
# ifdef __cplusplus
}
# endif

#endif
Olivier Aubert's avatar
Olivier Aubert committed
411
412

/** @} */