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