git.sesse.net Git - vlc/blob - include/vlc/mediacontrol.h

   1 /*****************************************************************************
   2  * control.h: global header for mediacontrol
   3  *****************************************************************************
   4  * Copyright (C) 2005 the VideoLAN team
   5  * $Id$
   6  *
   7  * Authors: Olivier Aubert <olivier.aubert@liris.univ-lyon1.fr>
   8  *
   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.
  13  *
  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.
  18  *
  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  *****************************************************************************/
  23
  24 /**
  25  * \defgroup mediacontrol MediaControl
  26  * This is the MediaControl API, * intended to provide a generic API to movie players.
  27  *
  28  * @{
  29  */
  30
  31
  32 #ifndef _VLC_CONTROL_H
  33 #define _VLC_CONTROL_H 1
  34
  35 # ifdef __cplusplus
  36 extern "C" {
  37 # endif
  38
  39 #if defined( WIN32 )
  40 #define WINDOWHANDLE HWND
  41 #else
  42 #define WINDOWHANDLE int
  43 #endif
  44
  45 #include <vlc/mediacontrol_structures.h>
  46
  47 /**
  48  * RGBPicture structure
  49  * This generic structure holds a picture in an encoding specified by type.
  50  */
  51 typedef struct {
  52     int  width;
  53     int  height;
  54     long type;
  55     vlc_int64_t date;
  56     int  size;
  57     char *data;
  58 } mediacontrol_RGBPicture;
  59
  60 /**
  61  * Playlist sequence
  62  * A simple list of strings.
  63  */
  64 typedef struct {
  65     int size;
  66     char **data;
  67 } mediacontrol_PlaylistSeq;
  68
  69 typedef struct {
  70     int code;
  71     char *message;
  72 } mediacontrol_Exception;
  73
  74 /**
  75  * Exception codes
  76  */
  77 #define mediacontrol_PositionKeyNotSupported    1
  78 #define mediacontrol_PositionOriginNotSupported 2
  79 #define mediacontrol_InvalidPosition            3
  80 #define mediacontrol_PlaylistException          4
  81 #define mediacontrol_InternalException          5
  82
  83 /**
  84  * mediacontrol_Instance is an opaque structure, defined in
  85  * mediacontrol_internal.h. API users do not have to mess with it.
  86  */
  87 typedef struct mediacontrol_Instance mediacontrol_Instance;
  88
  89 /**
  90  * Possible player status
  91  */
  92 enum mediacontrol_PlayerStatusList
  93 {
  94     mediacontrol_PlayingStatus, mediacontrol_PauseStatus,
  95     mediacontrol_ForwardStatus, mediacontrol_BackwardStatus,
  96     mediacontrol_InitStatus,    mediacontrol_EndStatus,
  97     mediacontrol_UndefinedStatus
  98 };
  99 typedef enum mediacontrol_PlayerStatusList mediacontrol_PlayerStatus;
 100
 101 /**
 102  * Stream information
 103  * This structure allows to quickly get various informations about the stream.
 104  */
 105 typedef struct {
 106     mediacontrol_PlayerStatus streamstatus;
 107     char *url;         /* The URL of the current media stream */
 108     vlc_int64_t position;     /* actual location in the stream (in ms) */
 109     vlc_int64_t length;         /* total length of the stream (in ms) */
 110 } mediacontrol_StreamInformation;
 111
 112 /**************************************************************************
 113  *  Helper functions
 114  ***************************************************************************/
 115
 116 /**
 117  * Allocate a RGBPicture structure.
 118  * \param datasize: the size of the data
 119  */
 120 mediacontrol_RGBPicture *mediacontrol_RGBPicture__alloc( int datasize );
 121
 122 /**
 123  * Free a RGBPicture structure.
 124  * \param pic: the RGBPicture structure
 125  */
 126 void mediacontrol_RGBPicture__free( mediacontrol_RGBPicture *pic );
 127
 128 mediacontrol_RGBPicture *
 129   _mediacontrol_createRGBPicture( int, int, long, vlc_int64_t l_date,
 130                                   char *, int);
 131
 132 mediacontrol_PlaylistSeq *mediacontrol_PlaylistSeq__alloc( int size );
 133
 134 void mediacontrol_PlaylistSeq__free( mediacontrol_PlaylistSeq *ps );
 135
 136 /**
 137  * Initialize an exception structure.
 138  * \param p_exception the exception to initialize. If NULL, a new exception will be created.
 139  * \return the exception
 140  */
 141 mediacontrol_Exception *
 142   mediacontrol_exception_init( mediacontrol_Exception *exception );
 143
 144 /**
 145  * Free an exception structure.
 146  * \return the exception
 147  */
 148 void mediacontrol_exception_free(mediacontrol_Exception *exception);
 149
 150 /*****************************************************************************
 151  * Core functions
 152  *****************************************************************************/
 153
 154 /**
 155  * Create a MediaControl instance with parameters
 156  * \param argc the number of arguments
 157  * \param argv parameters
 158  * \param exception an initialized exception pointer
 159  * \return a mediacontrol_Instance
 160  */
 161 mediacontrol_Instance *
 162 mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
 163
 164 /**
 165  * Create a MediaControl instance from an existing libvlc instance
 166  * \param p_instance the libvlc instance
 167  * \param exception an initialized exception pointer
 168  * \return a mediacontrol_Instance
 169  */
 170 mediacontrol_Instance *
 171 mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
 172                                 mediacontrol_Exception *exception );
 173
 174 /**
 175  * Get the associated libvlc instance
 176  * \param self: the mediacontrol instance
 177  * \return a libvlc instance
 178  */
 179 libvlc_instance_t*
 180 mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
 181
 182 /**
 183  * Get the current position
 184  * \param self the mediacontrol instance
 185  * \param an_origin the position origin
 186  * \param a_key the position unit
 187  * \param exception an initialized exception pointer
 188  * \return a mediacontrol_Position
 189  */
 190 mediacontrol_Position * mediacontrol_get_media_position(
 191                          mediacontrol_Instance *self,
 192                          const mediacontrol_PositionOrigin an_origin,
 193                          const mediacontrol_PositionKey a_key,
 194                          mediacontrol_Exception *exception );
 195
 196 /**
 197  * Set the position
 198  * \param self the mediacontrol instance
 199  * \param a_position a mediacontrol_Position
 200  * \param exception an initialized exception pointer
 201  */
 202 void mediacontrol_set_media_position( mediacontrol_Instance *self,
 203                                       const mediacontrol_Position *a_position,
 204                                       mediacontrol_Exception *exception );
 205
 206 /**
 207  * Play the movie at a given position
 208  * \param self the mediacontrol instance
 209  * \param a_position a mediacontrol_Position
 210  * \param exception an initialized exception pointer
 211  */
 212 void mediacontrol_start( mediacontrol_Instance *self,
 213                          const mediacontrol_Position *a_position,
 214                          mediacontrol_Exception *exception );
 215
 216 /**
 217  * Pause the movie at a given position
 218  * \param self the mediacontrol instance
 219  * \param a_position a mediacontrol_Position (ignored for now)
 220  * \param exception an initialized exception pointer
 221  */
 222 void mediacontrol_pause( mediacontrol_Instance *self,
 223                          const mediacontrol_Position *a_position,
 224                          mediacontrol_Exception *exception );
 225
 226 /**
 227  * Resume the movie at a given position
 228  * \param self the mediacontrol instance
 229  * \param a_position a mediacontrol_Position (ignored for now)
 230  * \param exception an initialized exception pointer
 231  */
 232 void mediacontrol_resume( mediacontrol_Instance *self,
 233                           const mediacontrol_Position *a_position,
 234                           mediacontrol_Exception *exception );
 235
 236 /**
 237  * Stop the movie at a given position
 238  * \param self the mediacontrol instance
 239  * \param a_position a mediacontrol_Position (ignored for now)
 240  * \param exception an initialized exception pointer
 241  */
 242 void mediacontrol_stop( mediacontrol_Instance *self,
 243                         const mediacontrol_Position *a_position,
 244                         mediacontrol_Exception *exception );
 245
 246 /**
 247  * Exit the player
 248  * \param self the mediacontrol instance
 249  */
 250 void mediacontrol_exit( mediacontrol_Instance *self );
 251
 252 /**
 253  * Add a new MRL to the playlist
 254  * \param self the mediacontrol instance
 255  * \param psz_file the MRL
 256  * \param exception an initialized exception pointer
 257  */
 258 void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
 259                                      const char* psz_file,
 260                                      mediacontrol_Exception *exception );
 261 /**
 262  * Clear the playlist
 263  * \param self the mediacontrol instance
 264  * \param exception an initialized exception pointer
 265  */
 266 void mediacontrol_playlist_clear( mediacontrol_Instance *self,
 267                                   mediacontrol_Exception *exception );
 268 /**
 269  * Get a flattened view of the playlist
 270  * \param self the mediacontrol instance
 271  * \param exception an initialized exception pointer
 272  * \return a list of strings
 273  */
 274 mediacontrol_PlaylistSeq *
 275   mediacontrol_playlist_get_list( mediacontrol_Instance *self,
 276                                   mediacontrol_Exception *exception );
 277
 278
 279 /*****************************************************************************
 280  * A/V functions
 281  *****************************************************************************/
 282 /**
 283  * Get a snapshot
 284  * \param self the mediacontrol instance
 285  * \param a_position the desired position (ignored for now)
 286  * \param exception an initialized exception pointer
 287  * \return a RGBpicture
 288  */
 289 mediacontrol_RGBPicture *
 290   mediacontrol_snapshot( mediacontrol_Instance *self,
 291                          const mediacontrol_Position *a_position,
 292                          mediacontrol_Exception *exception );
 293
 294 /* Return a NULL terminated list */
 295 /**
 296  * Get a list of all cached snapshots (unimplemented)
 297  * \param self the mediacontrol instance
 298  * \param exception an initialized exception pointer
 299  * \return a NULL-terminated list of RGBpicture
 300  */
 301 mediacontrol_RGBPicture **
 302   mediacontrol_all_snapshots( mediacontrol_Instance *self,
 303                               mediacontrol_Exception *exception );
 304
 305 /**
 306  *  Displays the message string, between "begin" and "end" positions.
 307  * \param self the mediacontrol instance
 308  * \param message the message to display
 309  * \param begin the begin position
 310  * \param end the end position
 311  * \param exception an initialized exception pointer
 312  */
 313 void mediacontrol_display_text( mediacontrol_Instance *self,
 314                                 const char *message,
 315                                 const mediacontrol_Position *begin,
 316                                 const mediacontrol_Position *end,
 317                                 mediacontrol_Exception *exception );
 318
 319 /**
 320  *  Get information about a stream
 321  * \param self the mediacontrol instance
 322  * \param a_key the time unit
 323  * \param exception an initialized exception pointer
 324  * \return a mediacontrol_StreamInformation
 325  */
 326 mediacontrol_StreamInformation *
 327   mediacontrol_get_stream_information( mediacontrol_Instance *self,
 328                                        mediacontrol_PositionKey a_key,
 329                                        mediacontrol_Exception *exception );
 330
 331 /**
 332  * Get the current audio level, normalized in [0..100]
 333  * \param self the mediacontrol instance
 334  * \param exception an initialized exception pointer
 335  * \return the volume
 336  */
 337 unsigned short
 338   mediacontrol_sound_get_volume( mediacontrol_Instance *self,
 339                                  mediacontrol_Exception *exception );
 340 /**
 341  * Set the audio level
 342  * \param self the mediacontrol instance
 343  * \param volume the volume (normalized in [0..100])
 344  * \param exception an initialized exception pointer
 345  */
 346 void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
 347                                     const unsigned short volume,
 348                                     mediacontrol_Exception *exception );
 349
 350 /**
 351  * Set the video output window
 352  * \param self the mediacontrol instance
 353  * \param visual_id the Xid or HWND, depending on the platform
 354  * \param exception an initialized exception pointer
 355  */
 356 vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
 357                                     WINDOWHANDLE visual_id,
 358                                     mediacontrol_Exception *exception );
 359
 360 /**
 361  * Get the current playing rate, in percent
 362  * \param self the mediacontrol instance
 363  * \param exception an initialized exception pointer
 364  * \return the rate
 365  */
 366 int mediacontrol_get_rate( mediacontrol_Instance *self,
 367                            mediacontrol_Exception *exception );
 368
 369 /**
 370  * Set the playing rate, in percent
 371  * \param self the mediacontrol instance
 372  * \param rate the desired rate
 373  * \param exception an initialized exception pointer
 374  */
 375 void mediacontrol_set_rate( mediacontrol_Instance *self,
 376                             const int rate,
 377                             mediacontrol_Exception *exception );
 378
 379 /**
 380  * Get current fullscreen status
 381  * \param self the mediacontrol instance
 382  * \param exception an initialized exception pointer
 383  * \return the fullscreen status
 384  */
 385 int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
 386                                  mediacontrol_Exception *exception );
 387
 388 /**
 389  * Set fullscreen status
 390  * \param self the mediacontrol instance
 391  * \param b_fullscreen the desired status
 392  * \param exception an initialized exception pointer
 393  */
 394 void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
 395                                   const int b_fullscreen,
 396                                   mediacontrol_Exception *exception );
 397
 398 # ifdef __cplusplus
 399 }
 400 # endif
 401
 402 #endif
 403
 404 /** @} */