Add libvlc_media_new_fd

[vlc] / include / vlc / libvlc_media.h

diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h
index 1185bf464fb443e8e48158960974a31568fdf345..ccdaeaedab70cb76e67be25004d4af9113157716 100644 (file)
--- a/include/vlc/libvlc_media.h
+++ b/include/vlc/libvlc_media.h
@@ -67,7 +67,7 @@ typedef enum libvlc_meta_t {
     libvlc_meta_Publisher,
     libvlc_meta_EncodedBy,
     libvlc_meta_ArtworkURL,
-    libvlc_meta_TrackID,
+    libvlc_meta_TrackID
     /* Add new meta types HERE */
 } libvlc_meta_t;
 
@@ -105,7 +105,7 @@ typedef enum libvlc_track_type_t
     libvlc_track_unknown   = -1,
     libvlc_track_audio     = 0,
     libvlc_track_video     = 1,
-    libvlc_track_text      = 2,
+    libvlc_track_text      = 2
 } libvlc_track_type_t;
 
 /** defgroup libvlc_media_stats_t LibVLC media statistics
@@ -171,12 +171,18 @@ typedef struct libvlc_media_track_info_t
 
 
 /**
- * Create a media with a certain given media resource location.
+ * Create a media with a certain given media resource location,
+ * for instance a valid URL.
+ *
+ * \note To refer to a local file with this function,
+ * the file://... URI syntax <b>must</b> be used (see IETF RFC3986).
+ * We recommend using libvlc_media_new_path() instead when dealing with
+ * local files.
  *
  * \see libvlc_media_release
  *
  * \param p_instance the instance
- * \param psz_mrl the MRL to read
+ * \param psz_mrl the media location
  * \return the newly created media or NULL on error
  */
 VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_location(
@@ -184,7 +190,7 @@ VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_location(
                                    const char * psz_mrl );
 
 /**
- * Create a media with a certain file path.
+ * Create a media for a certain file path.
  *
  * \see libvlc_media_release
  *
@@ -196,6 +202,35 @@ VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_path(
                                    libvlc_instance_t *p_instance,
                                    const char *path );
 
+/**
+ * Create a media for an already open file descriptor.
+ * The file descriptor shall be open for reading (or reading and writing).
+ *
+ * Regular file descriptors, pipe read descriptors and character device
+ * descriptors (including TTYs) are supported on all platforms.
+ * Block device descriptors are supported where available.
+ * Directory descriptors are supported on systems that provide fdopendir().
+ * Sockets are supported on all platforms where they are file descriptors,
+ * i.e. all except Windows.
+ *
+ * \note This library will <b>not</b> automatically close the file descriptor
+ * under any circumstance. Nevertheless, a file descriptor can usually only be
+ * rendered once in a media player. To render it a second time, the file
+ * descriptor should probably be rewound to the beginning with lseek().
+ *
+ * \see libvlc_media_release
+ *
+ * \version LibVLC 1.1.5 and later.
+ *
+ * \param p_instance the instance
+ * \param fd open file descriptor
+ * \return the newly created media or NULL on error
+ */
+VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_fd(
+                                   libvlc_instance_t *p_instance,
+                                   int fd );
+
+
 /**
  * Create a media as an empty node with a given name.
  *
@@ -457,7 +492,7 @@ VLC_PUBLIC_API void *libvlc_media_get_user_data( libvlc_media_t *p_md );
  *
  * @begincode
  * libvlc_media_player_t *player = libvlc_media_player_new_from_media(media);
- * libvlc_media_add_option_flag(media, "sout=\"#description\"");
+ * libvlc_media_add_option_flag(media, "sout=#description");
  * libvlc_media_player_play(player);
  * // ... wait until playing
  * libvlc_media_player_release(player);