bindings/mediacontrol/mediacontrol.h

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