libvlc: Export libvlc_media_parse() and libvlc_media_parse_async().

[vlc] / include / vlc / libvlc_media.h

diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h
index 075a1c670f32db3c7bcd16080a1f0b7a37eb1cb5..0468940e404af02bfde52d30077b9e4a68340a8a 100644 (file)
--- a/include/vlc/libvlc_media.h
+++ b/include/vlc/libvlc_media.h
@@ -168,6 +168,8 @@ typedef struct libvlc_media_es_t
 /**
  * Create a media with a certain given media resource location.
  *
+ * \see libvlc_media_release
+ *
  * \param p_instance the instance
  * \param psz_mrl the MRL to read
  * \return the newly created media or NULL on error
@@ -179,6 +181,8 @@ VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_location(
 /**
  * Create a media with a certain file path.
  *
+ * \see libvlc_media_release
+ *
  * \param p_instance the instance
  * \param path local filesystem path
  * \return the newly created media or NULL on error
@@ -190,6 +194,8 @@ VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_path(
 /**
  * Create a media as an empty node with a given name.
  *
+ * \see libvlc_media_release
+ *
  * \param p_instance the instance
  * \param psz_name the name of the node
  * \return the new empty media or NULL on error
@@ -272,6 +278,16 @@ VLC_PUBLIC_API libvlc_media_t * libvlc_media_duplicate( libvlc_media_t *p_md );
 /**
  * Read the meta of the media.
  *
+ * If the media has not yet been parsed this will return NULL.
+ *
+ * This methods automatically calls libvlc_media_parse_async(), so after calling
+ * it you may receive a libvlc_MediaMetaChanged event. If you prefer a synchronous
+ * version ensure that you call libvlc_media_parse() before get_meta().
+ *
+ * \see libvlc_media_parse
+ * \see libvlc_media_parse_async
+ * \see libvlc_MediaMetaChanged
+ *
  * \param p_md the media descriptor
  * \param e_meta the meta to read
  * \return the media's meta
@@ -361,6 +377,41 @@ VLC_PUBLIC_API libvlc_event_manager_t *
 VLC_PUBLIC_API libvlc_time_t
    libvlc_media_get_duration( libvlc_media_t * p_md );
 
+/**
+ * Parse a media.
+ *
+ * This fetches (local) meta data and tracks information.
+ * The method is synchronous.
+ *
+ * \see libvlc_media_parse_async
+ * \see libvlc_media_get_meta
+ * \see libvlc_media_get_es
+ *
+ * \param media media descriptor object
+ */
+VLC_PUBLIC_API void
+libvlc_media_parse(libvlc_media_t *media);
+
+/**
+ * Parse a media.
+ *
+ * This fetches (local) meta data and tracks information.
+ * The method is the asynchronous of libvlc_media_parse_async().
+ *
+ * To track when this is over you can listen to libvlc_MediaPreparsedChanged
+ * event. However if the media was already preparsed you will not receive this
+ * event.
+ *
+ * \see libvlc_media_parse
+ * \see libvlc_MediaPreparsedChanged
+ * \see libvlc_media_get_meta
+ * \see libvlc_media_get_es
+ *
+ * \param media media descriptor object
+ */
+VLC_PUBLIC_API void
+libvlc_media_parse_async(libvlc_media_t *media);
+
 /**
  * Get preparsed status for media descriptor object.
  *