libvlc: add libvlc_media_parse_with_options

Extended version of libvlc_media_parse_async. It uses a flag to specify parse
options and returns an int for error handling.
Signed-off-by: Jean-Baptiste Kempf <jb@videolan.org>

include/vlc/libvlc_media.h

@@ -223,6 +223,30 @@ typedef struct libvlc_media_track_t
 
 } libvlc_media_track_t;
 
+/**
+ * Parse flags used by libvlc_media_parse_with_options()
+ *
+ * \see libvlc_media_parse_with_options
+ */
+typedef enum libvlc_media_parse_flag_t
+{
+    /**
+     * Parse media if it's a local file
+     */
+    libvlc_media_parse_local    = 0x00,
+    /**
+     * Parse media even if it's a network file
+     */
+    libvlc_media_parse_network  = 0x01,
+    /**
+     * Fetch meta and covert art using local resources
+     */
+    libvlc_media_fetch_local    = 0x02,
+    /**
+     * Fetch meta and covert art using network resources
+     */
+    libvlc_media_fetch_network  = 0x04,
+} libvlc_media_parse_flag_t;
 
 /**
  * Create a media with a certain given media resource location,
@@ -485,7 +509,7 @@ LIBVLC_API libvlc_time_t
 /**
  * Parse a media.
  *
- * This fetches (local) meta data and tracks information.
+ * This fetches (local) art, meta data and tracks information.
  * The method is synchronous.
  *
  * \see libvlc_media_parse_async
@@ -500,7 +524,7 @@ libvlc_media_parse( libvlc_media_t *p_md );
 /**
  * Parse a media.
  *
- * This fetches (local) meta data and tracks information.
+ * This fetches (local) art, meta data and tracks information.
  * The method is the asynchronous of libvlc_media_parse().
  *
  * To track when this is over you can listen to libvlc_MediaParsedChanged
@@ -517,6 +541,34 @@ libvlc_media_parse( libvlc_media_t *p_md );
 LIBVLC_API void
 libvlc_media_parse_async( libvlc_media_t *p_md );
 
+/**
+ * Parse the media asynchronously with options.
+ *
+ * This fetches (local or network) art, meta data and/or tracks information.
+ * This method is the extended version of libvlc_media_parse_async().
+ *
+ * To track when this is over you can listen to libvlc_MediaParsedChanged
+ * event. However if this functions returns an error, you will not receive this
+ * event.
+ *
+ * It uses a flag to specify parse options (see libvlc_media_parse_flag_t). All
+ * these flags can be combined. By default, media is parsed if it's a local
+ * file.
+ *
+ * \see libvlc_MediaParsedChanged
+ * \see libvlc_media_get_meta
+ * \see libvlc_media_tracks_get
+ * \see libvlc_media_parse_flag_t
+ *
+ * \param p_md media descriptor object
+ * \param parse_flag parse options:
+ * \return -1 in case of error, 0 otherwise
+ * \version LibVLC 3.0.0 or later
+ */
+LIBVLC_API int
+libvlc_media_parse_with_options( libvlc_media_t *p_md,
+                                 libvlc_media_parse_flag_t parse_flag );
+
 /**
  * Get Parsed status for media descriptor object.
  *

lib/libvlc.sym

@@ -136,6 +136,7 @@ libvlc_media_new_as_node
 libvlc_media_new_from_input_item
 libvlc_media_parse
 libvlc_media_parse_async
+libvlc_media_parse_with_options
 libvlc_media_player_can_pause
 libvlc_media_player_program_scrambled
 libvlc_media_player_next_frame

lib/media.c

@@ -678,14 +678,51 @@ libvlc_media_get_duration( libvlc_media_t * p_md )
     return from_mtime(input_item_GetDuration( p_md->p_input_item ));
 }
 
-static int media_parse(libvlc_media_t *media)
+static int media_parse(libvlc_media_t *media, bool b_async,
+                       libvlc_media_parse_flag_t parse_flag)
 {
-    libvlc_int_t *libvlc = media->p_libvlc_instance->p_libvlc_int;
-    input_item_t *item = media->p_input_item;
+    bool needed;
+
+    vlc_mutex_lock(&media->parsed_lock);
+    needed = !media->has_asked_preparse;
+    media->has_asked_preparse = true;
+    vlc_mutex_unlock(&media->parsed_lock);
+
+    if (needed)
+    {
+        libvlc_int_t *libvlc = media->p_libvlc_instance->p_libvlc_int;
+        input_item_t *item = media->p_input_item;
+        input_item_meta_request_option_t art_scope = META_REQUEST_OPTION_NONE;
+        input_item_meta_request_option_t parse_scope = META_REQUEST_OPTION_SCOPE_LOCAL;
+        int ret;
+
+        if (parse_flag & libvlc_media_fetch_local)
+            art_scope |= META_REQUEST_OPTION_SCOPE_LOCAL;
+        if (parse_flag & libvlc_media_fetch_network)
+            art_scope |= META_REQUEST_OPTION_SCOPE_NETWORK;
+        if (art_scope != META_REQUEST_OPTION_NONE) {
+            ret = libvlc_ArtRequest(libvlc, item, art_scope);
+            if (ret != VLC_SUCCESS)
+                return ret;
+        }
 
-    /* TODO: Fetch art on need basis. But how not to break compatibility? */
-    libvlc_ArtRequest(libvlc, item, META_REQUEST_OPTION_NONE);
-    return libvlc_MetaRequest(libvlc, item, META_REQUEST_OPTION_NONE);
+        if (parse_flag & libvlc_media_parse_network)
+            parse_scope |= META_REQUEST_OPTION_SCOPE_NETWORK;
+        ret = libvlc_MetaRequest(libvlc, item, parse_scope);
+        if (ret != VLC_SUCCESS)
+            return ret;
+    }
+    else
+        return VLC_EGENERIC;
+
+    if (!b_async)
+    {
+        vlc_mutex_lock(&media->parsed_lock);
+        while (!media->is_parsed)
+            vlc_cond_wait(&media->parsed_cond, &media->parsed_lock);
+        vlc_mutex_unlock(&media->parsed_lock);
+    }
+    return VLC_SUCCESS;
 }
 
 /**************************************************************************
@@ -694,21 +731,7 @@ static int media_parse(libvlc_media_t *media)
 void
 libvlc_media_parse(libvlc_media_t *media)
 {
-    vlc_mutex_lock(&media->parsed_lock);
-    if (!media->has_asked_preparse)
-    {
-        media->has_asked_preparse = true;
-        vlc_mutex_unlock(&media->parsed_lock);
-
-        if (media_parse(media))
-            /* Parse failed: do not wait! */
-            return;
-        vlc_mutex_lock(&media->parsed_lock);
-    }
-
-    while (!media->is_parsed)
-        vlc_cond_wait(&media->parsed_cond, &media->parsed_lock);
-    vlc_mutex_unlock(&media->parsed_lock);
+    media_parse( media, false, libvlc_media_fetch_local );
 }
 
 /**************************************************************************
@@ -717,15 +740,17 @@ libvlc_media_parse(libvlc_media_t *media)
 void
 libvlc_media_parse_async(libvlc_media_t *media)
 {
-    bool needed;
-
-    vlc_mutex_lock(&media->parsed_lock);
-    needed = !media->has_asked_preparse;
-    media->has_asked_preparse = true;
-    vlc_mutex_unlock(&media->parsed_lock);
+    media_parse( media, true, libvlc_media_fetch_local );
+}
 
-    if (needed)
-        media_parse(media);
+/**************************************************************************
+ * Parse the media asynchronously with options.
+ **************************************************************************/
+int
+libvlc_media_parse_with_options( libvlc_media_t *media,
+                                 libvlc_media_parse_flag_t parse_flag )
+{
+    return media_parse( media, true, parse_flag ) == VLC_SUCCESS ? 0 : -1;
 }
 
 /**************************************************************************