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