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