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 # ifdef __LIBVLC__
 173 /* Avoid unuseful warnings from libvlc with our deprecated APIs */
 174 #    define VLC_DEPRECATED_API VLC_PUBLIC_API
 175 # else /* __LIBVLC__ */
 176 #  if defined(__GNUC__) && (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ > 0)
 177 #    define VLC_DEPRECATED_API VLC_PUBLIC_API __attribute__((deprecated))
 178 #  else
 179 #    define VLC_DEPRECATED_API VLC_PUBLIC_API
 180 #  endif
 181 # endif /* __LIBVLC__ */
 182 #endif
 183
 184 /*****************************************************************************
 185  * Exported libvlc API
 186  *****************************************************************************/
 187 #if !defined( __LIBVLC__ )
 188 /* Otherwise they are declared and exported in vlc_common.h */
 189 /**
 190  * Retrieve libvlc version
 191  *
 192  * \return a string containing the libvlc version
 193  */
 194 VLC_DEPRECATED_API char const * VLC_Version ( void );
 195
 196 /**
 197  * Retrieve libvlc compile time
 198  *
 199  * \return a string containing the libvlc compile time
 200  */
 201 VLC_DEPRECATED_API char const * VLC_CompileTime ( void );
 202
 203 /**
 204  * Retrieve the username of the libvlc builder
 205  *
 206  * \return a string containing the username of the libvlc builder
 207  */
 208 VLC_DEPRECATED_API char const * VLC_CompileBy ( void );
 209
 210 /**
 211  * Retrieve the host of the libvlc builder
 212  *
 213  * \return a string containing the host of the libvlc builder
 214  */
 215 VLC_DEPRECATED_API char const * VLC_CompileHost ( void );
 216
 217 /**
 218  * Retrieve the domain name of the host of the libvlc builder
 219  *
 220  * \return a string containing the domain name of the host of the libvlc builder
 221  */
 222 VLC_DEPRECATED_API char const * VLC_CompileDomain ( void );
 223
 224 /**
 225  * Retrieve libvlc compiler version
 226  *
 227  * \return a string containing the libvlc compiler version
 228  */
 229 VLC_DEPRECATED_API char const * VLC_Compiler ( void );
 230
 231 /**
 232  * Retrieve libvlc changeset
 233  *
 234  * \return a string containing the libvlc subversion changeset
 235  */
 236 VLC_DEPRECATED_API char const * VLC_Changeset ( void );
 237
 238 /**
 239  * Return an error string
 240  *
 241  * \param i_err an error code
 242  * \return an error string
 243  */
 244 VLC_DEPRECATED_API char const * VLC_Error ( int i_err );
 245
 246 #endif /* __LIBVLC__ */
 247
 248 /**
 249  * Initialize libvlc
 250  *
 251  * This function allocates a vlc_t structure and returns a negative value
 252  * in case of failure. Also, the thread system is initialized
 253  *
 254  * \return vlc object id or an error code
 255  */
 256 VLC_PUBLIC_API int     VLC_Create( void );
 257
 258 /**
 259  * Initialize a vlc_t structure
 260  *
 261  * This function initializes a previously allocated vlc_t structure:
 262  *  - CPU detection
 263  *  - gettext initialization
 264  *  - message queue, module bank and playlist initialization
 265  *  - configuration and commandline parsing
 266  *
 267  *  \param i_object a vlc object id
 268  *  \param i_argc the number of arguments
 269  *  \param ppsz_argv an array of arguments
 270  *  \return VLC_SUCCESS on success
 271  */
 272 VLC_PUBLIC_API int     VLC_Init( int, int, const char *[] );
 273
 274 /**
 275  * Add an interface
 276  *
 277  * This function opens an interface plugin and runs it. If b_block is set
 278  * to 0, VLC_AddIntf will return immediately and let the interface run in a
 279  * separate thread. If b_block is set to 1, VLC_AddIntf will continue until
 280  * user requests to quit.
 281  *
 282  * \param i_object a vlc object id
 283  * \param psz_module a vlc module name of an interface
 284  * \param b_block make this interface blocking
 285  * \param b_play start playing when the interface is done loading
 286  * \return VLC_SUCCESS on success
 287  */
 288 VLC_PUBLIC_API int     VLC_AddIntf( int, char const *, vlc_bool_t, vlc_bool_t );
 289
 290 /**
 291  * Ask vlc to die
 292  *
 293  * This function sets p_libvlc->b_die to VLC_TRUE, but does not do any other
 294  * task. It is your duty to call VLC_CleanUp and VLC_Destroy afterwards.
 295  *
 296  * \param i_object a vlc object id
 297  * \return VLC_SUCCESS on success
 298  */
 299 VLC_PUBLIC_API int     VLC_Die( int );
 300
 301 /**
 302  * Clean up all the intf, playlist, vout and aout
 303  *
 304  * This function requests all intf, playlist, vout and aout objects to finish
 305  * and CleanUp. Only a blank VLC object should remain after this.
 306  *
 307  * \note This function was previously called VLC_Stop
 308  *
 309  * \param i_object a vlc object id
 310  * \return VLC_SUCCESS on success
 311  */
 312 VLC_PUBLIC_API int     VLC_CleanUp( int );
 313
 314 /**
 315  * Destroy all threads and the VLC object
 316  *
 317  * This function requests the running threads to finish, waits for their
 318  * termination, and destroys their structure.
 319  * Then it will de-init all VLC object initializations.
 320  *
 321  * \param i_object a vlc object id
 322  * \return VLC_SUCCESS on success
 323  */
 324 VLC_PUBLIC_API int     VLC_Destroy( int );
 325
 326 /**
 327  * Set a VLC variable
 328  *
 329  * This function sets a variable of VLC
 330  *
 331  * \note Was previously called VLC_Set
 332  *
 333  * \param i_object a vlc object id
 334  * \param psz_var a vlc variable name
 335  * \param value a vlc_value_t structure
 336  * \return VLC_SUCCESS on success
 337  */
 338 VLC_DEPRECATED_API int     VLC_VariableSet( int, char const *, vlc_value_t );
 339
 340 /**
 341  * Get a VLC variable
 342  *
 343  * This function gets the value of a variable of VLC
 344  * It stores it in the p_value argument
 345  *
 346  * \note Was previously called VLC_Get
 347  *
 348  * \param i_object a vlc object id
 349  * \param psz_var a vlc variable name
 350  * \param p_value a pointer to a vlc_value_t structure
 351  * \return VLC_SUCCESS on success
 352  */
 353 VLC_DEPRECATED_API int     VLC_VariableGet( int, char const *, vlc_value_t * );
 354
 355 /**
 356  * Get a VLC variable type
 357  *
 358  * This function gets the type of a variable of VLC
 359  * It stores it in the p_type argument
 360  *
 361  * \param i_object a vlc object id
 362  * \param psz_var a vlc variable name
 363  * \param pi_type a pointer to an integer
 364  * \return VLC_SUCCESS on success
 365  */
 366 VLC_DEPRECATED_API int     VLC_VariableType( int, char const *, int * );
 367
 368 /**
 369  * Add a target to the current playlist
 370  *
 371  * This funtion will add a target to the current playlist. If a playlist does
 372  * not exist, it will be created.
 373  *
 374  * \param i_object a vlc object id
 375  * \param psz_target the URI of the target to play
 376  * \param ppsz_options an array of strings with input options (ie. :input-repeat)
 377  * \param i_options the amount of options in the ppsz_options array
 378  * \param i_mode the insert mode to insert the target into the playlist (PLAYLIST_* defines)
 379  * \param i_pos the position at which to add the new target (PLAYLIST_END for end)
 380  * \return the item id on success and -1 on error
 381  */
 382 VLC_PUBLIC_API int     VLC_AddTarget( int, char const *, const char **, int, int, int );
 383
 384 /**
 385  * Start the playlist and play the currently selected playlist item
 386  *
 387  * If there is something in the playlist, and the playlist is not running,
 388  * then start the playlist and play the currently selected playlist item.
 389  * If an item is currently paused, then resume it.
 390  *
 391  * \param i_object a vlc object id
 392  * \return VLC_SUCCESS on success
 393  */
 394 VLC_DEPRECATED_API int     VLC_Play( int );
 395
 396 /**
 397  * Pause the currently playing item. Resume it if already paused
 398  *
 399  * If an item is currently playing then pause it.
 400  * If the item is already paused, then resume playback.
 401  *
 402  * \param i_object a vlc object id
 403  * \return VLC_SUCCESS on success
 404  */
 405 VLC_DEPRECATED_API int     VLC_Pause( int );
 406
 407 /**
 408  * Stop the playlist
 409  *
 410  * If an item is currently playing then stop it.
 411  * Set the playlist to a stopped state.
 412  *
 413  * \note This function is new. The old VLC_Stop is now called VLC_CleanUp
 414  *
 415  * \param i_object a vlc object id
 416  * \return VLC_SUCCESS on success
 417  */
 418 VLC_DEPRECATED_API int             VLC_Stop( int );
 419
 420 /**
 421  * Tell if VLC is playing
 422  *
 423  * If an item is currently playing, it returns
 424  * VLC_TRUE, else VLC_FALSE
 425  *
 426  * \param i_object a vlc object id
 427  * \return VLC_TRUE or VLC_FALSE
 428  */
 429 VLC_DEPRECATED_API vlc_bool_t      VLC_IsPlaying( int );
 430
 431 /**
 432  * Get the current position in a input
 433  *
 434  * Return the current position as a float
 435  * This method should be used for time sliders etc
 436  * \note For some inputs, this will be unknown.
 437  *
 438  * \param i_object a vlc object id
 439  * \return a float in the range of 0.0 - 1.0
 440  */
 441 VLC_DEPRECATED_API float           VLC_PositionGet( int );
 442
 443 /**
 444  * Set the current position in a input
 445  *
 446  * Set the current position as a float
 447  * This method should be used for time sliders etc
 448  * \note For some inputs, this will be unknown.
 449  *
 450  * \param i_object a vlc object id
 451  * \param i_position a float in the range of 0.0 - 1.0
 452  * \return a float in the range of 0.0 - 1.0
 453  */
 454 VLC_DEPRECATED_API float           VLC_PositionSet( int, float );
 455
 456 /**
 457  * Get the current position in a input
 458  *
 459  * Return the current position in seconds from the start.
 460  * \note For some inputs, this will be unknown.
 461  *
 462  * \param i_object a vlc object id
 463  * \return the offset from 0:00 in seconds
 464  */
 465 VLC_DEPRECATED_API int             VLC_TimeGet( int );
 466
 467 /**
 468  * Seek to a position in the current input
 469  *
 470  * Seek i_seconds in the current input. If b_relative is set,
 471  * then the seek will be relative to the current position, otherwise
 472  * it will seek to i_seconds from the beginning of the input.
 473  * \note For some inputs, this will be unknown.
 474  *
 475  * \param i_object a vlc object id
 476  * \param i_seconds seconds from current position or from beginning of input
 477  * \param b_relative seek relative from current position
 478  * \return VLC_SUCCESS on success
 479  */
 480 VLC_DEPRECATED_API int             VLC_TimeSet( int, int, vlc_bool_t );
 481
 482 /**
 483  * Get the total length of a input
 484  *
 485  * Return the total length in seconds from the current input.
 486  * \note For some inputs, this will be unknown.
 487  *
 488  * \param i_object a vlc object id
 489  * \return the length in seconds
 490  */
 491 VLC_DEPRECATED_API int             VLC_LengthGet( int );
 492
 493 /**
 494  * Play the input faster than realtime
 495  *
 496  * 2x, 4x, 8x faster than realtime
 497  * \note For some inputs, this will be impossible.
 498  *
 499  * \param i_object a vlc object id
 500  * \return the current speedrate
 501  */
 502 VLC_DEPRECATED_API float           VLC_SpeedFaster( int );
 503
 504 /**
 505  * Play the input slower than realtime
 506  *
 507  * 1/2x, 1/4x, 1/8x slower than realtime
 508  * \note For some inputs, this will be impossible.
 509  *
 510  * \param i_object a vlc object id
 511  * \return the current speedrate
 512  */
 513 VLC_DEPRECATED_API float           VLC_SpeedSlower( int );
 514
 515 /**
 516  * Return the current playlist item
 517  *
 518  * \param i_object a vlc object id
 519  * \return the index of the playlistitem that is currently selected for play
 520  */
 521 VLC_DEPRECATED_API int             VLC_PlaylistIndex( int );
 522
 523 /**
 524  * Total amount of items in the playlist
 525  *
 526  * \param i_object a vlc object id
 527  * \return amount of playlist items
 528  */
 529 VLC_DEPRECATED_API int             VLC_PlaylistNumberOfItems( int );
 530
 531 /**
 532  * Next playlist item
 533  *
 534  * Skip to the next playlistitem and play it.
 535  *
 536  * \param i_object a vlc object id
 537  * \return VLC_SUCCESS on success
 538  */
 539 VLC_DEPRECATED_API int             VLC_PlaylistNext( int );
 540
 541 /**
 542  * Previous playlist item
 543  *
 544  * Skip to the previous playlistitem and play it.
 545  *
 546  * \param i_object a vlc object id
 547  * \return VLC_SUCCESS on success
 548  */
 549 VLC_DEPRECATED_API int             VLC_PlaylistPrev( int );
 550
 551 /**
 552  * Clear the contents of the playlist
 553  *
 554  * Completly empty the entire playlist.
 555  *
 556  * \note Was previously called VLC_ClearPlaylist
 557  *
 558  * \param i_object a vlc object id
 559  * \return VLC_SUCCESS on success
 560  */
 561 VLC_DEPRECATED_API int             VLC_PlaylistClear( int );
 562
 563 /**
 564  * Change the volume
 565  *
 566  * \param i_object a vlc object id
 567  * \param i_volume something in a range from 0-200
 568  * \return the new volume (range 0-200 %)
 569  */
 570 VLC_DEPRECATED_API int             VLC_VolumeSet( int, int );
 571
 572 /**
 573  * Get the current volume
 574  *
 575  * Retrieve the current volume.
 576  *
 577  * \param i_object a vlc object id
 578  * \return the current volume (range 0-200 %)
 579  */
 580 VLC_DEPRECATED_API int             VLC_VolumeGet( int );
 581
 582 /**
 583  * Mute/Unmute the volume
 584  *
 585  * \param i_object a vlc object id
 586  * \return VLC_SUCCESS on success
 587  */
 588 VLC_DEPRECATED_API int            VLC_VolumeMute( int );
 589
 590 /**
 591  * Toggle Fullscreen mode
 592  *
 593  * Switch between normal and fullscreen video
 594  *
 595  * \param i_object a vlc object id
 596  * \return VLC_SUCCESS on success
 597  */
 598 VLC_DEPRECATED_API int             VLC_FullScreen( int );
 599
 600
 601 # ifdef __cplusplus
 602 }
 603 # endif
 604
 605 #define LICENSE_MSG \
 606   _("This program comes with NO WARRANTY, to the extent permitted by " \
 607     "law.\nYou may redistribute it under the terms of the GNU General " \
 608     "Public License;\nsee the file named COPYING for details.\n" \
 609     "Written by the VideoLAN team; see the AUTHORS file.\n")
 610
 611 #endif /* <vlc/vlc.h> */