libvlc: clean up deprecated functions
[vlc.git] / include / vlc / deprecated.h
1 /*****************************************************************************
2  * deprecated.h:  libvlc deprecated API
3  *****************************************************************************
4  * Copyright (C) 1998-2008 VLC authors and VideoLAN
5  * $Id$
6  *
7  * Authors: ClĂ©ment Stenac <zorglub@videolan.org>
8  *          Jean-Paul Saman <jpsaman@videolan.org>
9  *
10  * This program is free software; you can redistribute it and/or modify it
11  * under the terms of the GNU Lesser General Public License as published by
12  * the Free Software Foundation; either version 2.1 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU Lesser General Public License for more details.
19  *
20  * You should have received a copy of the GNU Lesser General Public License
21  * along with this program; if not, write to the Free Software Foundation,
22  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
23  *****************************************************************************/
24
25 #ifndef LIBVLC_DEPRECATED_H
26 #define LIBVLC_DEPRECATED_H 1
27
28 # ifdef __cplusplus
29 extern "C" {
30 # endif
31
32 /**
33  * \ingroup libvlc libvlc_media_player
34  * @{
35  */
36
37 /**
38  * Get movie fps rate
39  *
40  * This function is provided for backward compatibility. It cannot deal with
41  * multiple video tracks. In LibVLC versions prior to 3.0, it would also fail
42  * if the file format did not convey the frame rate explicitly.
43  *
44  * \deprecated Consider using libvlc_media_tracks_get() instead.
45  *
46  * \param p_mi the Media Player
47  * \return frames per second (fps) for this playing movie, or 0 if unspecified
48  */
49 LIBVLC_DEPRECATED
50 LIBVLC_API float libvlc_media_player_get_fps( libvlc_media_player_t *p_mi );
51
52 /** end bug */
53
54 /**
55  * \deprecated Use libvlc_media_player_set_nsobject() instead
56  */
57 LIBVLC_DEPRECATED
58 LIBVLC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable );
59
60 /**
61  * \deprecated Use libvlc_media_player_get_nsobject() instead
62  */
63 LIBVLC_DEPRECATED
64 LIBVLC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_mi );
65
66 /**
67  * \deprecated Use libvlc_track_description_list_release() instead
68  */
69 LIBVLC_DEPRECATED LIBVLC_API
70 void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
71
72 /** @}*/
73
74 /**
75  * \ingroup libvlc libvlc_video
76  * @{
77  */
78
79 /**
80  * Get current video height.
81  * \deprecated Use libvlc_video_get_size() instead.
82  *
83  * \param p_mi the media player
84  * \return the video pixel height or 0 if not applicable
85  */
86 LIBVLC_DEPRECATED LIBVLC_API
87 int libvlc_video_get_height( libvlc_media_player_t *p_mi );
88
89 /**
90  * Get current video width.
91  * \deprecated Use libvlc_video_get_size() instead.
92  *
93  * \param p_mi the media player
94  * \return the video pixel width or 0 if not applicable
95  */
96 LIBVLC_DEPRECATED LIBVLC_API
97 int libvlc_video_get_width( libvlc_media_player_t *p_mi );
98
99 /**
100  * Get the description of available titles.
101  *
102  * \param p_mi the media player
103  * \return list containing description of available titles.
104  * It must be freed with libvlc_track_description_list_release()
105  */
106 LIBVLC_DEPRECATED LIBVLC_API libvlc_track_description_t *
107         libvlc_video_get_title_description( libvlc_media_player_t *p_mi );
108
109 /**
110  * Get the description of available chapters for specific title.
111  *
112  * \param p_mi the media player
113  * \param i_title selected title
114  * \return list containing description of available chapter for title i_title.
115  * It must be freed with libvlc_track_description_list_release()
116  */
117 LIBVLC_DEPRECATED LIBVLC_API libvlc_track_description_t *
118         libvlc_video_get_chapter_description( libvlc_media_player_t *p_mi, int i_title );
119
120 /** @}*/
121
122 /**
123  * \ingroup libvlc libvlc_audio
124  * @{
125  */
126
127 /**
128  * Backward compatibility stub. Do not use in new code.
129  * \deprecated Use libvlc_audio_output_device_list_get() instead.
130  * \return always 0.
131  */
132 LIBVLC_DEPRECATED LIBVLC_API
133 int libvlc_audio_output_device_count( libvlc_instance_t *, const char * );
134
135 /**
136  * Backward compatibility stub. Do not use in new code.
137  * \deprecated Use libvlc_audio_output_device_list_get() instead.
138  * \return always NULL.
139  */
140 LIBVLC_DEPRECATED LIBVLC_API
141 char *libvlc_audio_output_device_longname( libvlc_instance_t *, const char *,
142                                            int );
143
144 /**
145  * Backward compatibility stub. Do not use in new code.
146  * \deprecated Use libvlc_audio_output_device_list_get() instead.
147  * \return always NULL.
148  */
149 LIBVLC_DEPRECATED LIBVLC_API
150 char *libvlc_audio_output_device_id( libvlc_instance_t *, const char *, int );
151
152 /**
153  * Stub for backward compatibility.
154  * \return always -1.
155  */
156 LIBVLC_DEPRECATED
157 LIBVLC_API int libvlc_audio_output_get_device_type( libvlc_media_player_t *p_mi );
158
159 /**
160  * Stub for backward compatibility.
161  */
162 LIBVLC_DEPRECATED
163 LIBVLC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *,
164                                                      int );
165
166 /** @}*/
167
168 /**
169  * \ingroup libvlc libvlc_media
170  * @{
171  */
172
173 /**
174  * Parse a media.
175  *
176  * This fetches (local) art, meta data and tracks information.
177  * The method is the asynchronous of libvlc_media_parse().
178  *
179  * To track when this is over you can listen to libvlc_MediaParsedChanged
180  * event. However if the media was already parsed you will not receive this
181  * event.
182  *
183  * \deprecated You can't be sure to receive the libvlc_MediaParsedChanged
184  *             event (you can wait indefinitely for this event).
185  *             Use libvlc_media_parse_with_options() instead
186  *
187  * \see libvlc_media_parse
188  * \see libvlc_MediaParsedChanged
189  * \see libvlc_media_get_meta
190  * \see libvlc_media_get_tracks_info
191  *
192  * \param p_md media descriptor object
193  */
194 LIBVLC_DEPRECATED LIBVLC_API void
195 libvlc_media_parse_async( libvlc_media_t *p_md );
196
197 /**
198  * Return true is the media descriptor object is parsed
199  *
200  * \deprecated This can return true in case of failure.
201  *             Use libvlc_media_get_parsed_status() instead
202  *
203  * \see libvlc_MediaParsedChanged
204  *
205  * \param p_md media descriptor object
206  * \return true if media object has been parsed otherwise it returns false
207  *
208  * \libvlc_return_bool
209  */
210 LIBVLC_DEPRECATED LIBVLC_API int
211    libvlc_media_is_parsed( libvlc_media_t *p_md );
212
213 /**
214  * Get media descriptor's elementary streams description
215  *
216  * Note, you need to call libvlc_media_parse() or play the media at least once
217  * before calling this function.
218  * Not doing this will result in an empty array.
219  *
220  * \deprecated Use libvlc_media_tracks_get() instead
221  *
222  * \param p_md media descriptor object
223  * \param tracks address to store an allocated array of Elementary Streams
224  *        descriptions (must be freed by the caller) [OUT]
225  *
226  * \return the number of Elementary Streams
227  */
228 LIBVLC_DEPRECATED LIBVLC_API
229 int libvlc_media_get_tracks_info( libvlc_media_t *p_md,
230                                   libvlc_media_track_info_t **tracks );
231
232 /** @}*/
233
234 /**
235  * \ingroup libvlc libvlc_media_list
236  * @{
237  */
238
239 LIBVLC_DEPRECATED int
240     libvlc_media_list_add_file_content( libvlc_media_list_t * p_ml,
241                                         const char * psz_uri );
242
243 /** @}*/
244
245 /**
246  * \ingroup libvlc libvlc_media_discoverer
247  * @{
248  */
249
250 /**
251  * \deprecated Use libvlc_media_discoverer_new() and libvlc_media_discoverer_start().
252  */
253 LIBVLC_DEPRECATED LIBVLC_API libvlc_media_discoverer_t *
254 libvlc_media_discoverer_new_from_name( libvlc_instance_t * p_inst,
255                                        const char * psz_name );
256
257 /** @}*/
258
259 /**
260  * \ingroup libvlc libvlc_core
261  * @{
262  */
263
264 /**
265  * Waits until an interface causes the instance to exit.
266  * You should start at least one interface first, using libvlc_add_intf().
267  *
268  * \param p_instance the instance
269  * \warning This function wastes one thread doing basically nothing.
270  * libvlc_set_exit_handler() should be used instead.
271  */
272 LIBVLC_DEPRECATED LIBVLC_API
273 void libvlc_wait( libvlc_instance_t *p_instance );
274
275
276 /** @}*/
277
278 /**
279  * \ingroup libvlc_core
280  * \defgroup libvlc_log_deprecated LibVLC logging (legacy)
281  * @{
282  */
283
284 /** This structure is opaque. It represents a libvlc log iterator */
285 typedef struct libvlc_log_iterator_t libvlc_log_iterator_t;
286
287 typedef struct libvlc_log_message_t
288 {
289     int         i_severity;   /* 0=INFO, 1=ERR, 2=WARN, 3=DBG */
290     const char *psz_type;     /* module type */
291     const char *psz_name;     /* module name */
292     const char *psz_header;   /* optional header */
293     const char *psz_message;  /* message */
294 } libvlc_log_message_t;
295
296 /**
297  * Always returns minus one.
298  * This function is only provided for backward compatibility.
299  *
300  * \param p_instance ignored
301  * \return always -1
302  */
303 LIBVLC_DEPRECATED LIBVLC_API
304 unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );
305
306 /**
307  * This function does nothing.
308  * It is only provided for backward compatibility.
309  *
310  * \param p_instance ignored
311  * \param level ignored
312  */
313 LIBVLC_DEPRECATED LIBVLC_API
314 void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, unsigned level );
315
316 /**
317  * This function does nothing useful.
318  * It is only provided for backward compatibility.
319  *
320  * \param p_instance libvlc instance
321  * \return an unique pointer or NULL on error
322  */
323 LIBVLC_DEPRECATED LIBVLC_API
324 libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );
325
326 /**
327  * Frees memory allocated by libvlc_log_open().
328  *
329  * \param p_log libvlc log instance or NULL
330  */
331 LIBVLC_DEPRECATED LIBVLC_API
332 void libvlc_log_close( libvlc_log_t *p_log );
333
334 /**
335  * Always returns zero.
336  * This function is only provided for backward compatibility.
337  *
338  * \param p_log ignored
339  * \return always zero
340  */
341 LIBVLC_DEPRECATED LIBVLC_API
342 unsigned libvlc_log_count( const libvlc_log_t *p_log );
343
344 /**
345  * This function does nothing.
346  * It is only provided for backward compatibility.
347  *
348  * \param p_log ignored
349  */
350 LIBVLC_DEPRECATED LIBVLC_API
351 void libvlc_log_clear( libvlc_log_t *p_log );
352
353 /**
354  * This function does nothing useful.
355  * It is only provided for backward compatibility.
356  *
357  * \param p_log ignored
358  * \return an unique pointer or NULL on error or if the parameter was NULL
359  */
360 LIBVLC_DEPRECATED LIBVLC_API
361 libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );
362
363 /**
364  * Frees memory allocated by libvlc_log_get_iterator().
365  *
366  * \param p_iter libvlc log iterator or NULL
367  */
368 LIBVLC_DEPRECATED LIBVLC_API
369 void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );
370
371 /**
372  * Always returns zero.
373  * This function is only provided for backward compatibility.
374  *
375  * \param p_iter ignored
376  * \return always zero
377  */
378 LIBVLC_DEPRECATED LIBVLC_API
379 int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );
380
381 /**
382  * Always returns NULL.
383  * This function is only provided for backward compatibility.
384  *
385  * \param p_iter libvlc log iterator or NULL
386  * \param p_buf ignored
387  * \return always NULL
388  */
389 LIBVLC_DEPRECATED LIBVLC_API
390 libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
391                                                 libvlc_log_message_t *p_buf );
392
393 /** @}*/
394
395 /**
396  * \ingroup libvlc
397  * \defgroup libvlc_playlist LibVLC playlist (legacy)
398  * @deprecated Use @ref libvlc_media_list instead.
399  * @{
400  * \file
401  * LibVLC deprecated playlist API
402  */
403
404 /**
405  * Start playing (if there is any item in the playlist).
406  *
407  * Additionnal playlist item options can be specified for addition to the
408  * item before it is played.
409  *
410  * \param p_instance the playlist instance
411  * \param i_id the item to play. If this is a negative number, the next
412  *        item will be selected. Otherwise, the item with the given ID will be
413  *        played
414  * \param i_options the number of options to add to the item
415  * \param ppsz_options the options to add to the item
416  */
417 LIBVLC_DEPRECATED LIBVLC_API
418 void libvlc_playlist_play( libvlc_instance_t *p_instance, int i_id,
419                            int i_options, char **ppsz_options );
420
421 /** @}*/
422
423 # ifdef __cplusplus
424 }
425 # endif
426
427 #endif /* _LIBVLC_DEPRECATED_H */