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