Define libvlc_exception_raise() in the proper place
[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´┐Żent 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 typedef struct libvlc_input_t libvlc_input_t;
134
135 ///\todo document me
136 libvlc_input_t *libvlc_playlist_get_input( libvlc_instance_t *,
137                                            libvlc_exception_t * );
138
139
140
141 /** @}*/
142
143 /*****************************************************************************
144  * Input
145  *****************************************************************************/
146 /** defgroup libvlc_input Input
147  * \ingroup libvlc
148  * LibVLC Input handling
149  * @{
150  */
151
152 /** Free an input object
153  * \param p_input the input to free
154  */
155 void libvlc_input_free( libvlc_input_t * );
156
157 /// \bug This might go away ... to be replaced by a broader system
158 vlc_int64_t libvlc_input_get_length( libvlc_input_t *, libvlc_exception_t *);
159 vlc_int64_t libvlc_input_get_time( libvlc_input_t *, libvlc_exception_t *);
160 float libvlc_input_get_position( libvlc_input_t *, libvlc_exception_t *);
161
162 /** @} */
163
164
165
166 # ifdef __cplusplus
167 }
168 # endif
169
170 #endif /* <vlc/vlc_control.h> */