include/vlc/deprecated.h

   1 /*****************************************************************************
   2  * deprecated.h:  libvlc deprecated API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2008 VLC authors and VideoLAN
   5  *
   6  * Authors: Clément Stenac <zorglub@videolan.org>
   7  *          Jean-Paul Saman <jpsaman@videolan.org>
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation; either version 2.1 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 Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifndef LIBVLC_DEPRECATED_H
  25 #define LIBVLC_DEPRECATED_H 1
  26
  27 # ifdef __cplusplus
  28 extern "C" {
  29 # endif
  30
  31 /**
  32  * \ingroup libvlc libvlc_media
  33  * @{
  34  */
  35
  36 /**
  37  * Parse a media.
  38  *
  39  * This fetches (local) art, meta data and tracks information.
  40  * The method is synchronous.
  41  *
  42  * \deprecated This function could block indefinitely.
  43  *             Use libvlc_media_parse_with_options() instead
  44  *
  45  * \see libvlc_media_parse_with_options
  46  * \see libvlc_media_get_meta
  47  *
  48  * \param p_md media descriptor object
  49  */
  50 LIBVLC_DEPRECATED LIBVLC_API void
  51 libvlc_media_parse( libvlc_media_t *p_md );
  52
  53 /**
  54  * Parse a media.
  55  *
  56  * This fetches (local) art, meta data and tracks information.
  57  * The method is the asynchronous of libvlc_media_parse().
  58  *
  59  * To track when this is over you can listen to libvlc_MediaParsedChanged
  60  * event. However if the media was already parsed you will not receive this
  61  * event.
  62  *
  63  * \deprecated You can't be sure to receive the libvlc_MediaParsedChanged
  64  *             event (you can wait indefinitely for this event).
  65  *             Use libvlc_media_parse_with_options() instead
  66  *
  67  * \see libvlc_media_parse
  68  * \see libvlc_MediaParsedChanged
  69  * \see libvlc_media_get_meta
  70  *
  71  * \param p_md media descriptor object
  72  */
  73 LIBVLC_DEPRECATED LIBVLC_API void
  74 libvlc_media_parse_async( libvlc_media_t *p_md );
  75
  76 /**
  77  * Return true is the media descriptor object is parsed
  78  *
  79  * \deprecated This can return true in case of failure.
  80  *             Use libvlc_media_get_parsed_status() instead
  81  *
  82  * \see libvlc_MediaParsedChanged
  83  *
  84  * \param p_md media descriptor object
  85  * \retval true media object has been parsed
  86  * \retval false otherwise
  87  */
  88 LIBVLC_DEPRECATED LIBVLC_API bool
  89    libvlc_media_is_parsed( libvlc_media_t *p_md );
  90
  91 /**
  92  * Get media descriptor's elementary streams description
  93  *
  94  * Note, you need to call libvlc_media_parse_with_options() or play the media
  95  * at least once before calling this function.
  96  * Not doing this will result in an empty array.
  97  *
  98  * \version LibVLC 2.1.0 and later.
  99  * \see libvlc_media_parse_with_options
 100  *
 101  * \param p_md media descriptor object
 102  * \param tracks address to store an allocated array of Elementary Streams
 103  *        descriptions (must be freed with libvlc_media_tracks_release
 104           by the caller) [OUT]
 105  *
 106  * \return the number of Elementary Streams (zero on error)
 107  */
 108 LIBVLC_DEPRECATED LIBVLC_API
 109 unsigned libvlc_media_tracks_get( libvlc_media_t *p_md,
 110                                   libvlc_media_track_t ***tracks );
 111
 112 /**
 113  * Release media descriptor's elementary streams description array
 114  *
 115  * \version LibVLC 2.1.0 and later.
 116  *
 117  * \param p_tracks tracks info array to release
 118  * \param i_count number of elements in the array
 119  */
 120 LIBVLC_DEPRECATED LIBVLC_API
 121 void libvlc_media_tracks_release( libvlc_media_track_t **p_tracks,
 122                                   unsigned i_count );
 123
 124 /** @}*/
 125
 126 /**
 127  * \ingroup libvlc libvlc_media_player
 128  * @{
 129  */
 130
 131 /**
 132  * Description for video, audio tracks and subtitles. It contains
 133  * id, name (description string) and pointer to next record.
 134  */
 135 typedef struct libvlc_track_description_t
 136 {
 137     int   i_id;
 138     char *psz_name;
 139     struct libvlc_track_description_t *p_next;
 140
 141 } libvlc_track_description_t;
 142
 143 /**
 144  * Release (free) libvlc_track_description_t
 145  *
 146  * \param p_track_description the structure to release
 147  */
 148 LIBVLC_DEPRECATED LIBVLC_API void libvlc_track_description_list_release( libvlc_track_description_t *p_track_description );
 149
 150
 151 /** @}*/
 152
 153 /**
 154  * \ingroup libvlc libvlc_video
 155  * @{
 156  */
 157
 158 /**
 159  * Get number of available video tracks.
 160  *
 161  * \param p_mi media player
 162  * \return the number of available video tracks (int)
 163  */
 164 LIBVLC_DEPRECATED LIBVLC_API int libvlc_video_get_track_count( libvlc_media_player_t *p_mi );
 165
 166 /**
 167  * Get the description of available video tracks.
 168  *
 169  * \param p_mi media player
 170  * \return list with description of available video tracks, or NULL on error.
 171  * It must be freed with libvlc_track_description_list_release()
 172  */
 173 LIBVLC_DEPRECATED LIBVLC_API libvlc_track_description_t *
 174         libvlc_video_get_track_description( libvlc_media_player_t *p_mi );
 175
 176 /**
 177  * Get current video track.
 178  *
 179  * \param p_mi media player
 180  * \return the video track ID (int) or -1 if no active input
 181  */
 182 LIBVLC_DEPRECATED LIBVLC_API int libvlc_video_get_track( libvlc_media_player_t *p_mi );
 183
 184 /**
 185  * Set video track.
 186  *
 187  * \param p_mi media player
 188  * \param i_track the track ID (i_id field from track description)
 189  * \return 0 on success, -1 if out of range
 190  */
 191 LIBVLC_DEPRECATED LIBVLC_API
 192 int libvlc_video_set_track( libvlc_media_player_t *p_mi, int i_track );
 193
 194 /**
 195  * Get current video subtitle.
 196  *
 197  * \param p_mi the media player
 198  * \return the video subtitle selected, or -1 if none
 199  */
 200 LIBVLC_DEPRECATED LIBVLC_API int libvlc_video_get_spu( libvlc_media_player_t *p_mi );
 201
 202 /**
 203  * Get the number of available video subtitles.
 204  *
 205  * \param p_mi the media player
 206  * \return the number of available video subtitles
 207  */
 208 LIBVLC_DEPRECATED LIBVLC_API int libvlc_video_get_spu_count( libvlc_media_player_t *p_mi );
 209
 210 /**
 211  * Get the description of available video subtitles.
 212  *
 213  * \param p_mi the media player
 214  * \return list containing description of available video subtitles.
 215  * It must be freed with libvlc_track_description_list_release()
 216  */
 217 LIBVLC_DEPRECATED LIBVLC_API libvlc_track_description_t *
 218         libvlc_video_get_spu_description( libvlc_media_player_t *p_mi );
 219
 220 /**
 221  * Set new video subtitle.
 222  *
 223  * \param p_mi the media player
 224  * \param i_spu video subtitle track to select (i_id from track description)
 225  * \return 0 on success, -1 if out of range
 226  */
 227 LIBVLC_DEPRECATED LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, int i_spu );
 228
 229 /** @}*/
 230
 231 /**
 232  * \ingroup libvlc libvlc_audio
 233  * @{
 234  */
 235
 236 /**
 237  * Get number of available audio tracks.
 238  *
 239  * \param p_mi media player
 240  * \return the number of available audio tracks (int), or -1 if unavailable
 241  */
 242 LIBVLC_DEPRECATED LIBVLC_API int libvlc_audio_get_track_count( libvlc_media_player_t *p_mi );
 243
 244 /**
 245  * Get the description of available audio tracks.
 246  *
 247  * \param p_mi media player
 248  * \return list with description of available audio tracks, or NULL.
 249  * It must be freed with libvlc_track_description_list_release()
 250  */
 251 LIBVLC_DEPRECATED LIBVLC_API libvlc_track_description_t *
 252         libvlc_audio_get_track_description( libvlc_media_player_t *p_mi );
 253
 254 /**
 255  * Get current audio track.
 256  *
 257  * \param p_mi media player
 258  * \return the audio track ID or -1 if no active input.
 259  */
 260 LIBVLC_DEPRECATED LIBVLC_API int libvlc_audio_get_track( libvlc_media_player_t *p_mi );
 261
 262 /**
 263  * Set current audio track.
 264  *
 265  * \param p_mi media player
 266  * \param i_track the track ID (i_id field from track description)
 267  * \return 0 on success, -1 on error
 268  */
 269 LIBVLC_DEPRECATED LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track );
 270
 271 /** @}*/
 272
 273 /**
 274  * \ingroup libvlc
 275  * \defgroup libvlc_playlist LibVLC playlist (legacy)
 276  * @deprecated Use @ref libvlc_media_list instead.
 277  * @{
 278  * \file
 279  * LibVLC deprecated playlist API
 280  */
 281
 282 /**
 283  * Start playing (if there is any item in the playlist).
 284  *
 285  * Additionnal playlist item options can be specified for addition to the
 286  * item before it is played.
 287  *
 288  * \param p_instance the playlist instance
 289  */
 290 LIBVLC_DEPRECATED LIBVLC_API
 291 void libvlc_playlist_play( libvlc_instance_t *p_instance );
 292
 293 /** @}*/
 294
 295 # ifdef __cplusplus
 296 }
 297 # endif
 298
 299 #endif /* _LIBVLC_DEPRECATED_H */