More UTF8ication
[vlc.git] / include / vlc / libvlc.h
1 /*****************************************************************************
2  * libvlc.h:  libvlc_* new external API
3  *****************************************************************************
4  * Copyright (C) 1998-2005 the VideoLAN team
5  * $Id: vlc.h 13701 2005-12-12 17:58:56Z zorglub $
6  *
7  * Authors: ClĂ©ment Stenac <zorglub@videolan.org>
8  *
9  * This program is free software; you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation; either version 2 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22  *****************************************************************************/
23
24 /**
25  * \defgroup libvlc Libvlc
26  * This is libvlc, the base library of the VLC program.
27  *
28  * @{
29  */
30
31
32 #ifndef _LIBVLC_H
33 #define _LIBVLC_H 1
34
35 #include <vlc/vlc.h>
36
37 # ifdef __cplusplus
38 extern "C" {
39 # endif
40
41 /*****************************************************************************
42  * Exception handling
43  *****************************************************************************/
44 /** defgroup libvlc_exception Exceptions
45  * \ingroup libvlc
46  * LibVLC Exceptions handling
47  * @{
48  */
49
50 struct libvlc_exception_t
51 {
52     int b_raised;
53     char *psz_message;
54 };
55 typedef struct libvlc_exception_t libvlc_exception_t;
56
57 /**
58  * Initialize an exception structure. This can be called several times to reuse
59  * an exception structure.
60  * \param p_exception the exception to initialize
61  */
62 void libvlc_exception_init( libvlc_exception_t *p_exception );
63
64 /**
65  * Has an exception been raised ?
66  * \param p_exception the exception to query
67  * \return 0 if no exception raised, 1 else
68  */
69 int libvlc_exception_raised( libvlc_exception_t *p_exception );
70 void libvlc_exception_raise( libvlc_exception_t *p_exception, char *psz_message );
71
72 /**
73  * Get exception message
74  * \param p_exception the exception to query
75  * \return the exception message or NULL if not applicable (exception not raised
76  * for example)
77  */
78 char* libvlc_exception_get_message( libvlc_exception_t *p_exception );
79
80
81
82 /** @} */
83
84 /*****************************************************************************
85  * Core handling
86  *****************************************************************************/
87
88 /** defgroup libvlc_core Core
89  * \ingroup libvlc
90  * LibVLC Core
91  * @{
92  */
93
94 /** This structure is opaque. It represents a libvlc instance */
95 typedef struct libvlc_instance_t libvlc_instance_t;
96
97 /**
98  * Create an initialized libvlc instance
99  * \param argc the number of arguments
100  * \param argv command-line-type arguments
101  * \param exception an initialized exception pointer
102  */
103 libvlc_instance_t * libvlc_new( int , char **, libvlc_exception_t *);
104
105 /**
106  * Destroy a libvlc instance
107  * \param p_instance the instance to destroy
108  */
109 void libvlc_destroy( libvlc_instance_t *);
110
111 /** @}*/
112
113 /*****************************************************************************
114  * Playlist
115  *****************************************************************************/
116 /** defgroup libvlc_playlist Playlist
117  * \ingroup libvlc
118  * LibVLC Playlist handling
119  * @{
120  */
121
122 /**
123  * Start playing. You can give some additionnal playlist item options
124  * that will be added to the item before playing it.
125  * \param p_instance the instance
126  * \param i_options the number of options to add to the item
127  * \param ppsz_options the options to add to the item
128  * \param p_exception an initialized exception
129  */
130 void libvlc_playlist_play( libvlc_instance_t*, int, char **,
131                            libvlc_exception_t * );
132
133 /**
134  * Stop playing
135  * \param p_instance the instance to stop
136  * \param p_exception an initialized exception
137  */
138 void libvlc_playlist_stop( libvlc_instance_t *, libvlc_exception_t * );
139
140 /**
141  * Remove all playlist ites
142  * \param p_instance the instance
143  * \param p_exception an initialized exception
144  */
145 void libvlc_playlist_clear( libvlc_instance_t *, libvlc_exception_t * );
146
147 /**
148  * Go to next playlist item
149  * \param p_instance the instance
150  * \param p_exception an initialized exception
151  */
152 void libvlc_playlist_next( libvlc_instance_t *, libvlc_exception_t * );
153
154 /**
155  * Go to Previous playlist item
156  * \param p_instance the instance
157  * \param p_exception an initialized exception
158  */
159 void libvlc_playlist_prev( libvlc_instance_t *, libvlc_exception_t * );
160
161
162
163
164
165 typedef struct libvlc_input_t libvlc_input_t;
166
167 ///\todo document me
168 libvlc_input_t *libvlc_playlist_get_input( libvlc_instance_t *,
169                                            libvlc_exception_t * );
170
171
172
173 /** @}*/
174
175 /*****************************************************************************
176  * Input
177  *****************************************************************************/
178 /** defgroup libvlc_input Input
179  * \ingroup libvlc
180  * LibVLC Input handling
181  * @{
182  */
183
184 /** Free an input object
185  * \param p_input the input to free
186  */
187 void libvlc_input_free( libvlc_input_t * );
188
189 /// \bug This might go away ... to be replaced by a broader system
190 vlc_int64_t libvlc_input_get_length( libvlc_input_t *, libvlc_exception_t *);
191 vlc_int64_t libvlc_input_get_time( libvlc_input_t *, libvlc_exception_t *);
192 float libvlc_input_get_position( libvlc_input_t *, libvlc_exception_t *);
193
194 /** @} */
195
196
197
198 # ifdef __cplusplus
199 }
200 # endif
201
202 #endif /* <vlc/vlc_control.h> */