git.sesse.net Git - vlc/blob - include/vlc/vlc.h

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