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  * Play the next item
 280  * \param self the mediacontrol instance
 281  * \param exception an initialized exception pointer
 282  */
 283 void
 284 mediacontrol_playlist_next_item( mediacontrol_Instance *self,
 285                                  mediacontrol_Exception *exception );
 286
 287 /*****************************************************************************
 288  * A/V functions
 289  *****************************************************************************/
 290 /**
 291  * Get a snapshot
 292  * \param self the mediacontrol instance
 293  * \param a_position the desired position (ignored for now)
 294  * \param exception an initialized exception pointer
 295  * \return a RGBpicture
 296  */
 297 mediacontrol_RGBPicture *
 298   mediacontrol_snapshot( mediacontrol_Instance *self,
 299                          const mediacontrol_Position *a_position,
 300                          mediacontrol_Exception *exception );
 301
 302 /* Return a NULL terminated list */
 303 /**
 304  * Get a list of all cached snapshots (unimplemented)
 305  * \param self the mediacontrol instance
 306  * \param exception an initialized exception pointer
 307  * \return a NULL-terminated list of RGBpicture
 308  */
 309 mediacontrol_RGBPicture **
 310   mediacontrol_all_snapshots( mediacontrol_Instance *self,
 311                               mediacontrol_Exception *exception );
 312
 313 /**
 314  *  Displays the message string, between "begin" and "end" positions.
 315  * \param self the mediacontrol instance
 316  * \param message the message to display
 317  * \param begin the begin position
 318  * \param end the end position
 319  * \param exception an initialized exception pointer
 320  */
 321 void mediacontrol_display_text( mediacontrol_Instance *self,
 322                                 const char *message,
 323                                 const mediacontrol_Position *begin,
 324                                 const mediacontrol_Position *end,
 325                                 mediacontrol_Exception *exception );
 326
 327 /**
 328  *  Get information about a stream
 329  * \param self the mediacontrol instance
 330  * \param a_key the time unit
 331  * \param exception an initialized exception pointer
 332  * \return a mediacontrol_StreamInformation
 333  */
 334 mediacontrol_StreamInformation *
 335   mediacontrol_get_stream_information( mediacontrol_Instance *self,
 336                                        mediacontrol_PositionKey a_key,
 337                                        mediacontrol_Exception *exception );
 338
 339 /**
 340  * Get the current audio level, normalized in [0..100]
 341  * \param self the mediacontrol instance
 342  * \param exception an initialized exception pointer
 343  * \return the volume
 344  */
 345 unsigned short
 346   mediacontrol_sound_get_volume( mediacontrol_Instance *self,
 347                                  mediacontrol_Exception *exception );
 348 /**
 349  * Set the audio level
 350  * \param self the mediacontrol instance
 351  * \param volume the volume (normalized in [0..100])
 352  * \param exception an initialized exception pointer
 353  */
 354 void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
 355                                     const unsigned short volume,
 356                                     mediacontrol_Exception *exception );
 357
 358 /**
 359  * Set the video output window
 360  * \param self the mediacontrol instance
 361  * \param visual_id the Xid or HWND, depending on the platform
 362  * \param exception an initialized exception pointer
 363  */
 364 vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
 365                                     WINDOWHANDLE visual_id,
 366                                     mediacontrol_Exception *exception );
 367
 368 /**
 369  * Get the current playing rate, in percent
 370  * \param self the mediacontrol instance
 371  * \param exception an initialized exception pointer
 372  * \return the rate
 373  */
 374 int mediacontrol_get_rate( mediacontrol_Instance *self,
 375                            mediacontrol_Exception *exception );
 376
 377 /**
 378  * Set the playing rate, in percent
 379  * \param self the mediacontrol instance
 380  * \param rate the desired rate
 381  * \param exception an initialized exception pointer
 382  */
 383 void mediacontrol_set_rate( mediacontrol_Instance *self,
 384                             const int rate,
 385                             mediacontrol_Exception *exception );
 386
 387 /**
 388  * Get current fullscreen status
 389  * \param self the mediacontrol instance
 390  * \param exception an initialized exception pointer
 391  * \return the fullscreen status
 392  */
 393 int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
 394                                  mediacontrol_Exception *exception );
 395
 396 /**
 397  * Set fullscreen status
 398  * \param self the mediacontrol instance
 399  * \param b_fullscreen the desired status
 400  * \param exception an initialized exception pointer
 401  */
 402 void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
 403                                   const int b_fullscreen,
 404                                   mediacontrol_Exception *exception );
 405
 406 # ifdef __cplusplus
 407 }
 408 # endif
 409
 410 #endif
 411
 412 /** @} */