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/libvlc.h>
  47 #include <vlc/mediacontrol_structures.h>
  48
  49 /**
  50  * mediacontrol_Instance is an opaque structure, defined in
  51  * mediacontrol_internal.h. API users do not have to mess with it.
  52  */
  53 typedef struct mediacontrol_Instance mediacontrol_Instance;
  54
  55 /**************************************************************************
  56  *  Helper functions
  57  ***************************************************************************/
  58
  59 /**
  60  * Free a RGBPicture structure.
  61  * \param pic: the RGBPicture structure
  62  */
  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  * Free a StreamInformation structure.
  69  * \param pic: the StreamInformation structure
  70  */
  71 VLC_PUBLIC_API void
  72 mediacontrol_StreamInformation__free( mediacontrol_StreamInformation* p_si );
  73
  74 /**
  75  * Instanciate and initialize an exception structure.
  76  * \return the exception
  77  */
  78 VLC_PUBLIC_API mediacontrol_Exception *
  79   mediacontrol_exception_create( void );
  80
  81 /**
  82  * Initialize an existing exception structure.
  83  * \param p_exception the exception to initialize.
  84  */
  85 VLC_PUBLIC_API void
  86   mediacontrol_exception_init( mediacontrol_Exception *exception );
  87
  88 /**
  89  * Clean up an existing exception structure after use.
  90  * \param p_exception the exception to clean up.
  91  */
  92 VLC_PUBLIC_API void
  93 mediacontrol_exception_cleanup( mediacontrol_Exception *exception );
  94
  95 /**
  96  * Free an exception structure created with mediacontrol_exception_create().
  97  * \return the exception
  98  */
  99 VLC_PUBLIC_API void mediacontrol_exception_free(mediacontrol_Exception *exception);
 100
 101 /*****************************************************************************
 102  * Core functions
 103  *****************************************************************************/
 104
 105 /**
 106  * Create a MediaControl instance with parameters
 107  * \param argc the number of arguments
 108  * \param argv parameters
 109  * \param exception an initialized exception pointer
 110  * \return a mediacontrol_Instance
 111  */
 112 VLC_PUBLIC_API mediacontrol_Instance *
 113 mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
 114
 115 /**
 116  * Create a MediaControl instance from an existing libvlc instance
 117  * \param p_instance the libvlc instance
 118  * \param exception an initialized exception pointer
 119  * \return a mediacontrol_Instance
 120  */
 121 VLC_PUBLIC_API mediacontrol_Instance *
 122 mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
 123                 mediacontrol_Exception *exception );
 124
 125 /**
 126  * Get the associated libvlc instance
 127  * \param self: the mediacontrol instance
 128  * \return a libvlc instance
 129  */
 130 VLC_PUBLIC_API libvlc_instance_t*
 131 mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
 132
 133 /**
 134  * Get the current position
 135  * \param self the mediacontrol instance
 136  * \param an_origin the position origin
 137  * \param a_key the position unit
 138  * \param exception an initialized exception pointer
 139  * \return a mediacontrol_Position
 140  */
 141 VLC_PUBLIC_API mediacontrol_Position * mediacontrol_get_media_position(
 142                          mediacontrol_Instance *self,
 143                          const mediacontrol_PositionOrigin an_origin,
 144                          const mediacontrol_PositionKey a_key,
 145                          mediacontrol_Exception *exception );
 146
 147 /**
 148  * Set the position
 149  * \param self the mediacontrol instance
 150  * \param a_position a mediacontrol_Position
 151  * \param exception an initialized exception pointer
 152  */
 153 VLC_PUBLIC_API void mediacontrol_set_media_position( mediacontrol_Instance *self,
 154                                       const mediacontrol_Position *a_position,
 155                                       mediacontrol_Exception *exception );
 156
 157 /**
 158  * Play the movie at a given position
 159  * \param self the mediacontrol instance
 160  * \param a_position a mediacontrol_Position
 161  * \param exception an initialized exception pointer
 162  */
 163 VLC_PUBLIC_API void mediacontrol_start( mediacontrol_Instance *self,
 164                          const mediacontrol_Position *a_position,
 165                          mediacontrol_Exception *exception );
 166
 167 /**
 168  * Pause the movie at a given position
 169  * \param self the mediacontrol instance
 170  * \param a_position a mediacontrol_Position (ignored for now)
 171  * \param exception an initialized exception pointer
 172  */
 173 VLC_PUBLIC_API void mediacontrol_pause( mediacontrol_Instance *self,
 174                          const mediacontrol_Position *a_position,
 175                          mediacontrol_Exception *exception );
 176
 177 /**
 178  * Resume the movie at a given position
 179  * \param self the mediacontrol instance
 180  * \param a_position a mediacontrol_Position (ignored for now)
 181  * \param exception an initialized exception pointer
 182  */
 183 VLC_PUBLIC_API void mediacontrol_resume( mediacontrol_Instance *self,
 184                           const mediacontrol_Position *a_position,
 185                           mediacontrol_Exception *exception );
 186
 187 /**
 188  * Stop the movie at a given position
 189  * \param self the mediacontrol instance
 190  * \param a_position a mediacontrol_Position (ignored for now)
 191  * \param exception an initialized exception pointer
 192  */
 193 VLC_PUBLIC_API void mediacontrol_stop( mediacontrol_Instance *self,
 194                         const mediacontrol_Position *a_position,
 195                         mediacontrol_Exception *exception );
 196
 197 /**
 198  * Exit the player
 199  * \param self the mediacontrol instance
 200  */
 201 VLC_PUBLIC_API void mediacontrol_exit( mediacontrol_Instance *self );
 202
 203 /**
 204  * Add a new MRL to the playlist
 205  * \param self the mediacontrol instance
 206  * \param psz_file the MRL
 207  * \param exception an initialized exception pointer
 208  */
 209 VLC_PUBLIC_API void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
 210                                      const char* psz_file,
 211                                      mediacontrol_Exception *exception );
 212 /**
 213  * Clear the playlist
 214  * \param self the mediacontrol instance
 215  * \param exception an initialized exception pointer
 216  */
 217 VLC_PUBLIC_API void mediacontrol_playlist_clear( mediacontrol_Instance *self,
 218                                   mediacontrol_Exception *exception );
 219 /**
 220  * Get a flattened view of the playlist
 221  * \param self the mediacontrol instance
 222  * \param exception an initialized exception pointer
 223  * \return a list of strings
 224  */
 225 VLC_PUBLIC_API mediacontrol_PlaylistSeq *
 226   mediacontrol_playlist_get_list( mediacontrol_Instance *self,
 227                                   mediacontrol_Exception *exception );
 228
 229 /**
 230  * Play the next item
 231  * \param self the mediacontrol instance
 232  * \param exception an initialized exception pointer
 233  */
 234 VLC_PUBLIC_API void
 235 mediacontrol_playlist_next_item( mediacontrol_Instance *self,
 236                                  mediacontrol_Exception *exception );
 237
 238 /*****************************************************************************
 239  * A/V functions
 240  *****************************************************************************/
 241 /**
 242  * Get a snapshot
 243  * \param self the mediacontrol instance
 244  * \param a_position the desired position (ignored for now)
 245  * \param exception an initialized exception pointer
 246  * \return a RGBpicture
 247  */
 248 VLC_PUBLIC_API mediacontrol_RGBPicture *
 249   mediacontrol_snapshot( mediacontrol_Instance *self,
 250                          const mediacontrol_Position *a_position,
 251                          mediacontrol_Exception *exception );
 252
 253 /* Return a NULL terminated list */
 254 /**
 255  * Get a list of all cached snapshots (unimplemented)
 256  * \param self the mediacontrol instance
 257  * \param exception an initialized exception pointer
 258  * \return a NULL-terminated list of RGBpicture
 259  */
 260 VLC_PUBLIC_API mediacontrol_RGBPicture **
 261   mediacontrol_all_snapshots( mediacontrol_Instance *self,
 262                               mediacontrol_Exception *exception );
 263
 264 /**
 265  *  Displays the message string, between "begin" and "end" positions.
 266  * \param self the mediacontrol instance
 267  * \param message the message to display
 268  * \param begin the begin position
 269  * \param end the end position
 270  * \param exception an initialized exception pointer
 271  */
 272 VLC_PUBLIC_API void mediacontrol_display_text( mediacontrol_Instance *self,
 273                                 const char *message,
 274                                 const mediacontrol_Position *begin,
 275                                 const mediacontrol_Position *end,
 276                                 mediacontrol_Exception *exception );
 277
 278 /**
 279  *  Get information about a stream
 280  * \param self the mediacontrol instance
 281  * \param a_key the time unit
 282  * \param exception an initialized exception pointer
 283  * \return a mediacontrol_StreamInformation
 284  */
 285 VLC_PUBLIC_API mediacontrol_StreamInformation *
 286   mediacontrol_get_stream_information( mediacontrol_Instance *self,
 287                                        mediacontrol_PositionKey a_key,
 288                                        mediacontrol_Exception *exception );
 289
 290 /**
 291  * Get the current audio level, normalized in [0..100]
 292  * \param self the mediacontrol instance
 293  * \param exception an initialized exception pointer
 294  * \return the volume
 295  */
 296 VLC_PUBLIC_API unsigned short
 297   mediacontrol_sound_get_volume( mediacontrol_Instance *self,
 298                                  mediacontrol_Exception *exception );
 299 /**
 300  * Set the audio level
 301  * \param self the mediacontrol instance
 302  * \param volume the volume (normalized in [0..100])
 303  * \param exception an initialized exception pointer
 304  */
 305 VLC_PUBLIC_API void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
 306                                     const unsigned short volume,
 307                                     mediacontrol_Exception *exception );
 308
 309 /**
 310  * Set the video output window
 311  * \param self the mediacontrol instance
 312  * \param visual_id the Xid or HWND, depending on the platform
 313  * \param exception an initialized exception pointer
 314  */
 315 VLC_PUBLIC_API vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
 316                                     WINDOWHANDLE visual_id,
 317                                     mediacontrol_Exception *exception );
 318
 319 /**
 320  * Get the current playing rate, in percent
 321  * \param self the mediacontrol instance
 322  * \param exception an initialized exception pointer
 323  * \return the rate
 324  */
 325 VLC_PUBLIC_API int mediacontrol_get_rate( mediacontrol_Instance *self,
 326                mediacontrol_Exception *exception );
 327
 328 /**
 329  * Set the playing rate, in percent
 330  * \param self the mediacontrol instance
 331  * \param rate the desired rate
 332  * \param exception an initialized exception pointer
 333  */
 334 VLC_PUBLIC_API void mediacontrol_set_rate( mediacontrol_Instance *self,
 335                 const int rate,
 336                 mediacontrol_Exception *exception );
 337
 338 /**
 339  * Get current fullscreen status
 340  * \param self the mediacontrol instance
 341  * \param exception an initialized exception pointer
 342  * \return the fullscreen status
 343  */
 344 VLC_PUBLIC_API int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
 345                  mediacontrol_Exception *exception );
 346
 347 /**
 348  * Set fullscreen status
 349  * \param self the mediacontrol instance
 350  * \param b_fullscreen the desired status
 351  * \param exception an initialized exception pointer
 352  */
 353 VLC_PUBLIC_API void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
 354                   const int b_fullscreen,
 355                   mediacontrol_Exception *exception );
 356
 357 # ifdef __cplusplus
 358 }
 359 # endif
 360
 361 #endif
 362
 363 /** @} */