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

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