use VLC_DEPRECATED_API as needed

[vlc] / include / vlc / deprecated.h

diff --git a/include/vlc/deprecated.h b/include/vlc/deprecated.h
index 0238e5d95d7d690f94fab84605db8371f70f861a..886dfdbded7f45890e855f5bc4f14c412c425068 100644 (file)
--- a/include/vlc/deprecated.h
+++ b/include/vlc/deprecated.h
@@ -1,11 +1,11 @@
 /*****************************************************************************
  * deprecated.h:  libvlc deprecated API
  *****************************************************************************
- * Copyright (C) 1998-2005 the VideoLAN team
+ * Copyright (C) 1998-2008 the VideoLAN team
  * $Id$
  *
  * Authors: Clément Stenac <zorglub@videolan.org>
- *          Jean-Paul Saman <jpsaman _at_ m2x _dot_ nl>
+ *          Jean-Paul Saman <jpsaman@videolan.org>
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -22,24 +22,67 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
-#ifndef _LIBVLC_DEPRECATED_H
-#define _LIBVLC_DEPRECATED_H 1
+#ifndef LIBVLC_DEPRECATED_H
+#define LIBVLC_DEPRECATED_H 1
+
+/**
+ * \file
+ * This file defines libvlc depreceated API
+ */
+
+/**
+ * This is the legacy representation of a platform-specific drawable. Because
+ * it cannot accomodate a pointer on most 64-bits platforms, it should not be
+ * used anymore.
+ */
+typedef int libvlc_drawable_t;
 
 # ifdef __cplusplus
 extern "C" {
 # endif
 
+/**
+ * Set the drawable where the media player should render its video output.
+ *
+ * On Windows 32-bits, a window handle (HWND) is expected.
+ * On Windows 64-bits, this function will always fail.
+ *
+ * On OSX 32-bits, a CGrafPort is expected.
+ * On OSX 64-bits, this function will always fail.
+ *
+ * On other platforms, an existing X11 window ID is expected. See
+ * libvlc_media_player_set_xid() for details.
+ *
+ * \param p_mi the Media Player
+ * \param drawable the libvlc_drawable_t where the media player
+ *        should render its video
+ * \param p_e an initialized exception pointer
+ */
+VLC_DEPRECATED_API void libvlc_media_player_set_drawable ( libvlc_media_player_t *, libvlc_drawable_t, libvlc_exception_t * );
+
+/**
+ * Get the drawable where the media player should render its video output
+ *
+ * \param p_mi the Media Player
+ * \param p_e an initialized exception pointer
+ * \return the libvlc_drawable_t where the media player
+ *         should render its video
+ */
+VLC_DEPRECATED_API libvlc_drawable_t
+                    libvlc_media_player_get_drawable ( libvlc_media_player_t *, libvlc_exception_t * );
+
 /**
  * Set the default video output's parent.
  *
- * This setting will be used as default for all video outputs.
+ * This setting will be used as default for any video output.
  *
  * \param p_instance libvlc instance
- * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
+ * \param drawable the new parent window
+ *                 (see libvlc_media_player_set_drawable() for details)
  * \param p_e an initialized exception pointer
  * @deprecated Use libvlc_media_player_set_drawable
  */
-VLC_PUBLIC_API void libvlc_video_set_parent( libvlc_instance_t *, libvlc_drawable_t, libvlc_exception_t * );
+VLC_DEPRECATED_API void libvlc_video_set_parent( libvlc_instance_t *, libvlc_drawable_t, libvlc_exception_t * );
 
 /**
  * Set the default video output parent.
@@ -51,7 +94,17 @@ VLC_PUBLIC_API void libvlc_video_set_parent( libvlc_instance_t *, libvlc_drawabl
  * \param p_e an initialized exception pointer
  * @deprecated Use libvlc_media_player_get_drawable
  */
-VLC_PUBLIC_API libvlc_drawable_t libvlc_video_get_parent( libvlc_instance_t *, libvlc_exception_t * );
+VLC_DEPRECATED_API libvlc_drawable_t libvlc_video_get_parent( libvlc_instance_t *, libvlc_exception_t * );
+
+/**
+ * Change the parent for the current the video output.
+ *
+ * \param p_instance libvlc instance
+ * \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
+ * \param p_e an initialized exception pointer
+ * \return the success status (boolean)
+ */
+VLC_PUBLIC_API int libvlc_video_reparent( libvlc_media_player_t *, libvlc_drawable_t, libvlc_exception_t * );
 
 /*
  * This function shall not be used at all. It may lead to crash and race condition.
@@ -120,6 +173,8 @@ VLC_DEPRECATED_API int libvlc_playlist_isplaying( libvlc_instance_t *,
 /**
  * Get the number of items in the playlist
  *
+ * Expects the playlist instance to be locked already.
+ *
  * \param p_instance the playlist instance
  * \param p_e an initialized exception pointer
  * \return the number of items
@@ -210,6 +265,22 @@ VLC_DEPRECATED_API int libvlc_playlist_add_extended( libvlc_instance_t *, const
                                                  const char *, int, const char **,
                                                  libvlc_exception_t * );
 
+/**
+ * Append an item to the playlist. The item is added at the end, with
+ * additional input options from an untrusted source.
+ *
+ * \param p_instance the playlist instance
+ * \param psz_uri the URI to open, using VLC format
+ * \param psz_name a name that you might want to give or NULL
+ * \param i_options the number of options to add
+ * \param ppsz_options strings representing the options to add
+ * \param p_e an initialized exception pointer
+ * \return the identifier of the new item
+ */
+VLC_DEPRECATED_API int libvlc_playlist_add_extended_untrusted( libvlc_instance_t *, const char *,
+                                                 const char *, int, const char **,
+                                                 libvlc_exception_t * );
+
 /**
  * Delete the playlist item with the given ID.
  *