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