git.sesse.net Git - vlc/blob - include/vlc/deprecated.h

   1 /*****************************************************************************
   2  * deprecated.h:  libvlc deprecated API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2008 the VideoLAN team
   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
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 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 General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, 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 /**
  29  * \file
  30  * This file defines libvlc depreceated API
  31  */
  32
  33 /**
  34  * This is the legacy representation of a platform-specific drawable. Because
  35  * it cannot accomodate a pointer on most 64-bits platforms, it should not be
  36  * used anymore.
  37  */
  38 typedef int libvlc_drawable_t;
  39
  40 # ifdef __cplusplus
  41 extern "C" {
  42 # endif
  43
  44 /**
  45  * Set the drawable where the media player should render its video output.
  46  *
  47  * On Windows 32-bits, a window handle (HWND) is expected.
  48  * On Windows 64-bits, this function will always fail.
  49  *
  50  * On OSX 32-bits, a CGrafPort is expected.
  51  * On OSX 64-bits, this function will always fail.
  52  *
  53  * On other platforms, an existing X11 window ID is expected. See
  54  * libvlc_media_player_set_xid() for details.
  55  *
  56  * \param p_mi the Media Player
  57  * \param drawable the libvlc_drawable_t where the media player
  58  *        should render its video
  59  * \param p_e an initialized exception pointer
  60  */
  61 VLC_DEPRECATED_API void libvlc_media_player_set_drawable ( libvlc_media_player_t *, libvlc_drawable_t, libvlc_exception_t * );
  62
  63 /**
  64  * Get the drawable where the media player should render its video output
  65  *
  66  * \param p_mi the Media Player
  67  * \param p_e an initialized exception pointer
  68  * \return the libvlc_drawable_t where the media player
  69  *         should render its video
  70  */
  71 VLC_DEPRECATED_API libvlc_drawable_t
  72                     libvlc_media_player_get_drawable ( libvlc_media_player_t *, libvlc_exception_t * );
  73
  74 /**
  75  * Set the default video output's parent.
  76  *
  77  * This setting will be used as default for any video output.
  78  *
  79  * \param p_instance libvlc instance
  80  * \param drawable the new parent window
  81  *                 (see libvlc_media_player_set_drawable() for details)
  82  * \param p_e an initialized exception pointer
  83  * @deprecated Use libvlc_media_player_set_drawable
  84  */
  85 VLC_DEPRECATED_API void libvlc_video_set_parent( libvlc_instance_t *, libvlc_drawable_t, libvlc_exception_t * );
  86
  87 /**
  88  * Set the default video output parent.
  89  *
  90  * This setting will be used as default for all video outputs.
  91  *
  92  * \param p_instance libvlc instance
  93  * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
  94  * \param p_e an initialized exception pointer
  95  * @deprecated Use libvlc_media_player_get_drawable
  96  */
  97 VLC_DEPRECATED_API libvlc_drawable_t libvlc_video_get_parent( libvlc_instance_t *, libvlc_exception_t * );
  98
  99 /**
 100  * Does nothing. Do not use this function.
 101  */
 102 VLC_DEPRECATED_API int libvlc_video_reparent( libvlc_media_player_t *, libvlc_drawable_t, libvlc_exception_t * );
 103
 104 /**
 105  * Resize the current video output window.
 106  * This might crash. Please use libvlc_video_set_scale() instead.
 107  *
 108  * \param p_mi media player instance
 109  * \param width new width for video output window
 110  * \param height new height for video output window
 111  * \param p_e an initialized exception pointer
 112  * \return the success status (boolean)
 113  */
 114 VLC_DEPRECATED_API void libvlc_video_resize( libvlc_media_player_t *, int, int, libvlc_exception_t *);
 115
 116 /**
 117  * Tell windowless video output to redraw rectangular area (MacOS X only).
 118  * This might crash. Do not use this function.
 119  *
 120  * \param p_mi media player instance
 121  * \param area coordinates within video drawable
 122  * \param p_e an initialized exception pointer
 123  */
 124 VLC_DEPRECATED_API void libvlc_video_redraw_rectangle( libvlc_media_player_t *, const libvlc_rectangle_t *, libvlc_exception_t * );
 125
 126 /**
 127  * Set the default video output size.
 128  * This setting will be used as default for all video outputs.
 129  *
 130  * \param p_instance libvlc instance
 131  * \param width new width for video drawable
 132  * \param height new height for video drawable
 133  * \param p_e an initialized exception pointer
 134  */
 135 VLC_DEPRECATED_API void libvlc_video_set_size( libvlc_instance_t *, int, int, libvlc_exception_t * );
 136
 137 /**
 138  * Set the default video output viewport for a windowless video output
 139  * (MacOS X only). This might crash. Do not use this function.
 140  *
 141  * This setting will be used as default for all video outputs.
 142  *
 143  * \param p_instance libvlc instance
 144  * \param p_mi media player instance
 145  * \param view coordinates within video drawable
 146  * \param clip coordinates within video drawable
 147  * \param p_e an initialized exception pointer
 148  */
 149 VLC_DEPRECATED_API void libvlc_video_set_viewport( libvlc_instance_t *, libvlc_media_player_t *, const libvlc_rectangle_t *, const libvlc_rectangle_t *, libvlc_exception_t * );
 150
 151 /*
 152  * This function shall not be used at all. It may lead to crash and race condition.
 153  */
 154 VLC_DEPRECATED_API int libvlc_video_destroy( libvlc_media_player_t *, libvlc_exception_t *);
 155
 156 /*****************************************************************************
 157  * Playlist (Deprecated)
 158  *****************************************************************************/
 159 /** \defgroup libvlc_playlist libvlc_playlist (Deprecated)
 160  * \ingroup libvlc
 161  * LibVLC Playlist handling (Deprecated)
 162  * @deprecated Use media_list
 163  * @{
 164  */
 165
 166 /**
 167  * Set the playlist's loop attribute. If set, the playlist runs continuously
 168  * and wraps around when it reaches the end.
 169  *
 170  * \param p_instance the playlist instance
 171  * \param loop the loop attribute. 1 sets looping, 0 disables it
 172  * \param p_e an initialized exception pointer
 173  */
 174 VLC_DEPRECATED_API void libvlc_playlist_loop( libvlc_instance_t* , int,
 175                                           libvlc_exception_t * );
 176
 177 /**
 178  * Start playing.
 179  *
 180  * Additionnal playlist item options can be specified for addition to the
 181  * item before it is played.
 182  *
 183  * \param p_instance the playlist instance
 184  * \param i_id the item to play. If this is a negative number, the next
 185  *        item will be selected. Otherwise, the item with the given ID will be
 186  *        played
 187  * \param i_options the number of options to add to the item
 188  * \param ppsz_options the options to add to the item
 189  * \param p_e an initialized exception pointer
 190  */
 191 VLC_DEPRECATED_API void libvlc_playlist_play( libvlc_instance_t*, int, int,
 192                                           char **, libvlc_exception_t * );
 193
 194 /**
 195  * Toggle the playlist's pause status.
 196  *
 197  * If the playlist was running, it is paused. If it was paused, it is resumed.
 198  *
 199  * \param p_instance the playlist instance to pause
 200  * \param p_e an initialized exception pointer
 201  */
 202 VLC_DEPRECATED_API void libvlc_playlist_pause( libvlc_instance_t *,
 203                                            libvlc_exception_t * );
 204
 205 /**
 206  * Checks whether the playlist is running
 207  *
 208  * \param p_instance the playlist instance
 209  * \param p_e an initialized exception pointer
 210  * \return 0 if the playlist is stopped or paused, 1 if it is running
 211  */
 212 VLC_DEPRECATED_API int libvlc_playlist_isplaying( libvlc_instance_t *,
 213                                               libvlc_exception_t * );
 214
 215 /**
 216  * Get the number of items in the playlist
 217  *
 218  * Expects the playlist instance to be locked already.
 219  *
 220  * \param p_instance the playlist instance
 221  * \param p_e an initialized exception pointer
 222  * \return the number of items
 223  */
 224 VLC_DEPRECATED_API int libvlc_playlist_items_count( libvlc_instance_t *,
 225                                                 libvlc_exception_t * );
 226
 227 VLC_DEPRECATED_API int libvlc_playlist_get_current_index( libvlc_instance_t *,
 228                                                  libvlc_exception_t *);
 229 /**
 230  * Lock the playlist.
 231  *
 232  * \param p_instance the playlist instance
 233  */
 234 VLC_DEPRECATED_API void libvlc_playlist_lock( libvlc_instance_t * );
 235
 236 /**
 237  * Unlock the playlist.
 238  *
 239  * \param p_instance the playlist instance
 240  */
 241 VLC_DEPRECATED_API void libvlc_playlist_unlock( libvlc_instance_t * );
 242
 243 /**
 244  * Stop playing.
 245  *
 246  * \param p_instance the playlist instance to stop
 247  * \param p_e an initialized exception pointer
 248  */
 249 VLC_DEPRECATED_API void libvlc_playlist_stop( libvlc_instance_t *,
 250                                           libvlc_exception_t * );
 251
 252 /**
 253  * Go to the next playlist item. If the playlist was stopped, playback
 254  * is started.
 255  *
 256  * \param p_instance the playlist instance
 257  * \param p_e an initialized exception pointer
 258  */
 259 VLC_DEPRECATED_API void libvlc_playlist_next( libvlc_instance_t *,
 260                                           libvlc_exception_t * );
 261
 262 /**
 263  * Go to the previous playlist item. If the playlist was stopped, playback
 264  * is started.
 265  *
 266  * \param p_instance the playlist instance
 267  * \param p_e an initialized exception pointer
 268  */
 269 VLC_DEPRECATED_API void libvlc_playlist_prev( libvlc_instance_t *,
 270                                           libvlc_exception_t * );
 271
 272 /**
 273  * Empty a playlist. All items in the playlist are removed.
 274  *
 275  * \param p_instance the playlist instance
 276  * \param p_e an initialized exception pointer
 277  */
 278 VLC_DEPRECATED_API void libvlc_playlist_clear( libvlc_instance_t *,
 279                                            libvlc_exception_t * );
 280
 281 /**
 282  * Append an item to the playlist. The item is added at the end. If more
 283  * advanced options are required, \see libvlc_playlist_add_extended instead.
 284  *
 285  * \param p_instance the playlist instance
 286  * \param psz_uri the URI to open, using VLC format
 287  * \param psz_name a name that you might want to give or NULL
 288  * \param p_e an initialized exception pointer
 289  * \return the identifier of the new item
 290  */
 291 VLC_DEPRECATED_API int libvlc_playlist_add( libvlc_instance_t *, const char *,
 292                                         const char *, libvlc_exception_t * );
 293
 294 /**
 295  * Append an item to the playlist. The item is added at the end, with
 296  * additional input options.
 297  *
 298  * \param p_instance the playlist instance
 299  * \param psz_uri the URI to open, using VLC format
 300  * \param psz_name a name that you might want to give or NULL
 301  * \param i_options the number of options to add
 302  * \param ppsz_options strings representing the options to add
 303  * \param p_e an initialized exception pointer
 304  * \return the identifier of the new item
 305  */
 306 VLC_DEPRECATED_API int libvlc_playlist_add_extended( libvlc_instance_t *, const char *,
 307                                                  const char *, int, const char **,
 308                                                  libvlc_exception_t * );
 309
 310 /**
 311  * Append an item to the playlist. The item is added at the end, with
 312  * additional input options from an untrusted source.
 313  *
 314  * \param p_instance the playlist instance
 315  * \param psz_uri the URI to open, using VLC format
 316  * \param psz_name a name that you might want to give or NULL
 317  * \param i_options the number of options to add
 318  * \param ppsz_options strings representing the options to add
 319  * \param p_e an initialized exception pointer
 320  * \return the identifier of the new item
 321  */
 322 VLC_DEPRECATED_API int libvlc_playlist_add_extended_untrusted( libvlc_instance_t *, const char *,
 323                                                  const char *, int, const char **,
 324                                                  libvlc_exception_t * );
 325
 326 /**
 327  * Delete the playlist item with the given ID.
 328  *
 329  * \param p_instance the playlist instance
 330  * \param i_id the id to remove
 331  * \param p_e an initialized exception pointer
 332  * \return 0 in case of success, a non-zero value otherwise
 333  */
 334 VLC_DEPRECATED_API int libvlc_playlist_delete_item( libvlc_instance_t *, int,
 335                                                 libvlc_exception_t * );
 336
 337 /** Get the input that is currently being played by the playlist.
 338  *
 339  * \param p_instance the playlist instance to use
 340  * \param p_e an initialized exception pointern
 341  * \return a media instance object
 342  */
 343 VLC_DEPRECATED_API libvlc_media_player_t * libvlc_playlist_get_media_player(
 344                                 libvlc_instance_t *, libvlc_exception_t * );
 345
 346 /** @}*/
 347
 348 # ifdef __cplusplus
 349 }
 350 # endif
 351
 352 #endif /* _LIBVLC_DEPRECATED_H */