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