d4d522c4b1befe430ce3b20aaf47bcb57e76fba7
[vlc.git] / 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> */