include/vlc/vlc.h

   1 /*****************************************************************************
   2  * vlc.h: global header for vlc
   3  *****************************************************************************
   4  * Copyright (C) 1998-2004 VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Vincent Seguin <seguin@via.ecp.fr>
   8  *          Samuel Hocevar <sam@zoy.org>
   9  *          Gildas Bazin <gbazin@netcourrier.com>
  10  *          Derk-Jan Hartman <hartman at videolan dot org>
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  25  *****************************************************************************/
  26
  27 /**
  28  * \defgroup libvlc Libvlc
  29  * This is libvlc, the base library of the VLC program.
  30  *
  31  * @{
  32  */
  33
  34
  35 #ifndef _VLC_VLC_H
  36 #define _VLC_VLC_H 1
  37
  38 # ifdef __cplusplus
  39 extern "C" {
  40 # endif
  41
  42 /*****************************************************************************
  43  * Our custom types
  44  *****************************************************************************/
  45 typedef int vlc_bool_t;
  46 typedef struct vlc_list_t vlc_list_t;
  47 typedef struct vlc_object_t vlc_object_t;
  48
  49 /**
  50  * VLC value structure
  51  */
  52 typedef union
  53 {
  54     int             i_int;
  55     vlc_bool_t      b_bool;
  56     float           f_float;
  57     char *          psz_string;
  58     void *          p_address;
  59     vlc_object_t *  p_object;
  60     vlc_list_t *    p_list;
  61
  62 #if (defined( WIN32 ) && !defined( __MINGW32__ )) || defined( UNDER_CE )
  63     signed __int64   i_time;
  64 # else
  65     signed long long i_time;
  66 #endif
  67
  68     struct { char *psz_name; int i_object_id; } var;
  69
  70    /* Make sure the structure is at least 64bits */
  71     struct { char a, b, c, d, e, f, g, h; } padding;
  72
  73 } vlc_value_t;
  74
  75 /**
  76  * VLC list structure
  77  */
  78 struct vlc_list_t
  79 {
  80     int             i_count;
  81     vlc_value_t *   p_values;
  82     int *           pi_types;
  83
  84 };
  85
  86 /*****************************************************************************
  87  * Error values
  88  *****************************************************************************/
  89 #define VLC_SUCCESS         -0                                   /* No error */
  90 #define VLC_ENOMEM          -1                          /* Not enough memory */
  91 #define VLC_ETHREAD         -2                               /* Thread error */
  92 #define VLC_ETIMEOUT        -3                                    /* Timeout */
  93
  94 #define VLC_ENOMOD         -10                           /* Module not found */
  95
  96 #define VLC_ENOOBJ         -20                           /* Object not found */
  97 #define VLC_EBADOBJ        -21                            /* Bad object type */
  98
  99 #define VLC_ENOVAR         -30                         /* Variable not found */
 100 #define VLC_EBADVAR        -31                         /* Bad variable value */
 101
 102 #define VLC_EEXIT         -255                             /* Program exited */
 103 #define VLC_EGENERIC      -666                              /* Generic error */
 104
 105 /*****************************************************************************
 106  * Booleans
 107  *****************************************************************************/
 108 #define VLC_FALSE 0
 109 #define VLC_TRUE  1
 110
 111 /*****************************************************************************
 112  * Playlist
 113  *****************************************************************************/
 114
 115 /* Used by VLC_AddTarget() */
 116 #define PLAYLIST_INSERT          0x0001
 117 #define PLAYLIST_REPLACE         0x0002
 118 #define PLAYLIST_APPEND          0x0004
 119 #define PLAYLIST_GO              0x0008
 120 #define PLAYLIST_CHECK_INSERT    0x0010
 121
 122 #define PLAYLIST_END           -666
 123
 124 /*****************************************************************************
 125  * Required internal headers
 126  *****************************************************************************/
 127 #if defined( __VLC__ )
 128 #   include "vlc_common.h"
 129 #endif
 130
 131 /*****************************************************************************
 132  * Exported libvlc API
 133  *****************************************************************************/
 134
 135 /**
 136  * Retrieve libvlc version
 137  *
 138  * \return a string containing the libvlc version
 139  */
 140 char const * VLC_Version ( void );
 141
 142 /**
 143  * Return an error string
 144  *
 145  * \param i_err an error code
 146  * \return an error string
 147  */
 148 char const * VLC_Error ( int i_err );
 149
 150 /**
 151  * Initialize libvlc
 152  *
 153  * This function allocates a vlc_t structure and returns a negative value
 154  * in case of failure. Also, the thread system is initialized
 155  *
 156  * \return vlc object id or an error code
 157  */
 158 int     VLC_Create( void );
 159
 160 /**
 161  * Initialize a vlc_t structure
 162  *
 163  * This function initializes a previously allocated vlc_t structure:
 164  *  - CPU detection
 165  *  - gettext initialization
 166  *  - message queue, module bank and playlist initialization
 167  *  - configuration and commandline parsing
 168  *
 169  *  \param i_object a vlc object id
 170  *  \param i_argc the number of arguments
 171  *  \param ppsz_argv an array of arguments
 172  *  \return VLC_SUCCESS on success
 173  */
 174 int     VLC_Init( int, int, char *[] );
 175
 176 /**
 177  * Add an interface
 178  *
 179  * This function opens an interface plugin and runs it. If b_block is set
 180  * to 0, VLC_AddIntf will return immediately and let the interface run in a
 181  * separate thread. If b_block is set to 1, VLC_AddIntf will continue until
 182  * user requests to quit.
 183  *
 184  * \param i_object a vlc object id
 185  * \param psz_module a vlc module name of an interface
 186  * \param b_block make this interface blocking
 187  * \param b_play start playing when the interface is done loading
 188  * \return VLC_SUCCESS on success
 189  */
 190 int     VLC_AddIntf( int, char const *, vlc_bool_t, vlc_bool_t );
 191
 192 /**
 193  * Ask vlc to die
 194  *
 195  * This function sets p_vlc->b_die to VLC_TRUE, but does not do any other
 196  * task. It is your duty to call VLC_CleanUp and VLC_Destroy afterwards.
 197  *
 198  * \param i_object a vlc object id
 199  * \return VLC_SUCCESS on success
 200  */
 201 int     VLC_Die( int );
 202
 203 /**
 204  * Clean up all the intf, playlist, vout and aout
 205  *
 206  * This function requests all intf, playlist, vout and aout objects to finish
 207  * and CleanUp. Only a blank VLC object should remain after this.
 208  *
 209  * \note This function was previously called VLC_Stop
 210  *
 211  * \param i_object a vlc object id
 212  * \return VLC_SUCCESS on success
 213  */
 214 int     VLC_CleanUp( int );
 215
 216 /**
 217  * Destroy all threads and the VLC object
 218  *
 219  * This function requests the running threads to finish, waits for their
 220  * termination, and destroys their structure.
 221  * Then it will de-init all VLC object initializations.
 222  *
 223  * \param i_object a vlc object id
 224  * \return VLC_SUCCESS on success
 225  */
 226 int     VLC_Destroy( int );
 227
 228 /**
 229  * Set a VLC variable
 230  *
 231  * This function sets a variable of VLC
 232  *
 233  * \note Was previously called VLC_Set
 234  *
 235  * \param i_object a vlc object id
 236  * \param psz_var a vlc variable name
 237  * \param value a vlc_value_t structure
 238  * \return VLC_SUCCESS on success
 239  */
 240 int     VLC_VariableSet( int, char const *, vlc_value_t );
 241
 242 /**
 243  * Get a VLC variable
 244  *
 245  * This function gets the value of a variable of VLC
 246  * It stores it in the p_value argument
 247  *
 248  * \note Was previously called VLC_Get
 249  *
 250  * \param i_object a vlc object id
 251  * \param psz_var a vlc variable name
 252  * \param p_value a pointer to a vlc_value_t structure
 253  * \return VLC_SUCCESS on success
 254  */
 255 int     VLC_VariableGet( int, char const *, vlc_value_t * );
 256
 257 /**
 258  * Add a target to the current playlist
 259  *
 260  * This funtion will add a target to the current playlist. If a playlist does
 261  * not exist, it will be created.
 262  *
 263  * \param i_object a vlc object id
 264  * \param psz_target the URI of the target to play
 265  * \param ppsz_options an array of strings with input options (ie. :input-repeat)
 266  * \param i_options the amount of options in the ppsz_options array
 267  * \param i_mode the insert mode to insert the target into the playlist (PLAYLIST_* defines)
 268  * \param i_pos the position at which to add the new target (PLAYLIST_END for end)
 269  * \return VLC_SUCCESS on success
 270  */
 271 int     VLC_AddTarget( int, char const *, const char **, int, int, int );
 272
 273 /**
 274  * Start the playlist and play the currently selected playlist item
 275  *
 276  * If there is something in the playlist, and the playlist is not running,
 277  * then start the playlist and play the currently selected playlist item.
 278  * If an item is currently paused, then resume it.
 279  *
 280  * \param i_object a vlc object id
 281  * \return VLC_SUCCESS on success
 282  */
 283 int     VLC_Play( int );
 284
 285 /**
 286  * Pause the currently playing item. Resume it if already paused
 287  *
 288  * If an item is currently playing then pause it.
 289  * If the item is already paused, then resume playback.
 290  *
 291  * \param i_object a vlc object id
 292  * \return VLC_SUCCESS on success
 293  */
 294 int     VLC_Pause( int );
 295
 296 /**
 297  * Stop the playlist
 298  *
 299  * If an item is currently playing then stop it.
 300  * Set the playlist to a stopped state.
 301  *
 302  * \note This function is new. The old VLC_Stop is now called VLC_CleanUp
 303  *
 304  * \param i_object a vlc object id
 305  * \return VLC_SUCCESS on success
 306  */
 307 int             VLC_Stop( int );
 308
 309 /**
 310  * Tell if VLC is playing
 311  *
 312  * If an item is currently playing, it returns
 313  * VLC_TRUE, else VLC_FALSE
 314  *
 315  * \param i_object a vlc object id
 316  * \return VLC_TRUE or VLC_FALSE
 317  */
 318 vlc_bool_t      VLC_IsPlaying( int );
 319
 320 /**
 321  * Get the current position in a input
 322  *
 323  * Return the current position as a float
 324  * This method should be used for time sliders etc
 325  * \note For some inputs, this will be unknown.
 326  *
 327  * \param i_object a vlc object id
 328  * \return a float in the range of 0.0 - 1.0
 329  */
 330 float           VLC_PositionGet( int );
 331
 332 /**
 333  * Set the current position in a input
 334  *
 335  * Set the current position as a float
 336  * This method should be used for time sliders etc
 337  * \note For some inputs, this will be unknown.
 338  *
 339  * \param i_object a vlc object id
 340  * \param i_position a float in the range of 0.0 - 1.0
 341  * \return a float in the range of 0.0 - 1.0
 342  */
 343 float           VLC_PositionSet( int, float );
 344
 345 /**
 346  * Get the current position in a input
 347  *
 348  * Return the current position in seconds from the start.
 349  * \note For some inputs, this will be unknown.
 350  *
 351  * \param i_object a vlc object id
 352  * \return the offset from 0:00 in seconds
 353  */
 354 int             VLC_TimeGet( int );
 355
 356 /**
 357  * Seek to a position in the current input
 358  *
 359  * Seek i_seconds in the current input. If b_relative is set,
 360  * then the seek will be relative to the current position, otherwise
 361  * it will seek to i_seconds from the beginning of the input.
 362  * \note For some inputs, this will be unknown.
 363  *
 364  * \param i_object a vlc object id
 365  * \param i_seconds seconds from current position or from beginning of input
 366  * \param b_relative seek relative from current position
 367  * \return VLC_SUCCESS on success
 368  */
 369 int             VLC_TimeSet( int, int, vlc_bool_t );
 370
 371 /**
 372  * Get the total length of a input
 373  *
 374  * Return the total length in seconds from the current input.
 375  * \note For some inputs, this will be unknown.
 376  *
 377  * \param i_object a vlc object id
 378  * \return the length in seconds
 379  */
 380 int             VLC_LengthGet( int );
 381
 382 /**
 383  * Play the input faster than realtime
 384  *
 385  * 2x, 4x, 8x faster than realtime
 386  * \note For some inputs, this will be impossible.
 387  *
 388  * \param i_object a vlc object id
 389  * \return the current speedrate
 390  */
 391 float           VLC_SpeedFaster( int );
 392
 393 /**
 394  * Play the input slower than realtime
 395  *
 396  * 1/2x, 1/4x, 1/8x slower than realtime
 397  * \note For some inputs, this will be impossible.
 398  *
 399  * \param i_object a vlc object id
 400  * \return the current speedrate
 401  */
 402 float           VLC_SpeedSlower( int );
 403
 404 /**
 405  * Return the current playlist item
 406  *
 407  * \param i_object a vlc object id
 408  * \return the index of the playlistitem that is currently selected for play
 409  */
 410 int             VLC_PlaylistIndex( int );
 411
 412 /**
 413  * Total amount of items in the playlist
 414  *
 415  * \param i_object a vlc object id
 416  * \return amount of playlist items
 417  */
 418 int             VLC_PlaylistNumberOfItems( int );
 419
 420 /**
 421  * Next playlist item
 422  *
 423  * Skip to the next playlistitem and play it.
 424  *
 425  * \param i_object a vlc object id
 426  * \return VLC_SUCCESS on success
 427  */
 428 int             VLC_PlaylistNext( int );
 429
 430 /**
 431  * Previous playlist item
 432  *
 433  * Skip to the previous playlistitem and play it.
 434  *
 435  * \param i_object a vlc object id
 436  * \return VLC_SUCCESS on success
 437  */
 438 int             VLC_PlaylistPrev( int );
 439
 440 /**
 441  * Clear the contents of the playlist
 442  *
 443  * Completly empty the entire playlist.
 444  *
 445  * \note Was previously called VLC_ClearPlaylist
 446  *
 447  * \param i_object a vlc object id
 448  * \return VLC_SUCCESS on success
 449  */
 450 int             VLC_PlaylistClear( int );
 451
 452 /**
 453  * Change the volume
 454  *
 455  * \param i_object a vlc object id
 456  * \param i_volume something in a range from 0-200
 457  * \return the new volume (range 0-200 %)
 458  */
 459 int             VLC_VolumeSet( int, int );
 460
 461 /**
 462  * Get the current volume
 463  *
 464  * Retrieve the current volume.
 465  *
 466  * \param i_object a vlc object id
 467  * \return the current volume (range 0-200 %)
 468  */
 469 int             VLC_VolumeGet( int );
 470
 471 /**
 472  * Mute/Unmute the volume
 473  *
 474  * \param i_object a vlc object id
 475  * \return VLC_SUCCESS on success
 476  */
 477 int            VLC_VolumeMute( int );
 478
 479 /**
 480  * Toggle Fullscreen mode
 481  *
 482  * Switch between normal and fullscreen video
 483  *
 484  * \param i_object a vlc object id
 485  * \return VLC_SUCCESS on success
 486  */
 487 int             VLC_FullScreen( int );
 488
 489
 490 # ifdef __cplusplus
 491 }
 492 # endif
 493
 494 #endif /* <vlc/vlc.h> */