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

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