[vlc-commits] input: document and annotate chain building functions

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Tue Sep 19 19:05:00 2017 +0300| [bbb5df4b324fd6f0e97d23bc65c606c3c62486b9] | committer: Rémi Denis-Courmont

input: document and annotate chain building functions

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=bbb5df4b324fd6f0e97d23bc65c606c3c62486b9
---

 src/input/demux.h          | 17 ++++++++++++++++-
 src/input/input_internal.h |  2 +-
 src/input/stream.h         | 47 +++++++++++++++++++++++++++++++++++++---------
 3 files changed, 55 insertions(+), 11 deletions(-)

diff --git a/src/input/demux.h b/src/input/demux.h
index 5a6d63a6ef..00be2e9ab8 100644
--- a/src/input/demux.h
+++ b/src/input/demux.h
@@ -40,7 +40,22 @@ unsigned demux_TestAndClearFlags( demux_t *, unsigned );
 int demux_GetTitle( demux_t * );
 int demux_GetSeekpoint( demux_t * );
 
-demux_t *demux_FilterChainNew( demux_t *p_demux, const char *psz_name );
+/**
+ * Builds an explicit chain of demux filters.
+ *
+ * This function creates a chain of filters according to a supplied list.
+ *
+ * See also stream_FilterChainNew(). Those two functions have identical
+ * semantics and ownership rules, except for the use of demux vs stream.
+ *
+ * @param source input stream around which to build a filter chain
+ * @param list colon-separated list of stream filters (upstream first)
+ *
+ * @return The last demux (filter) in the chain.
+ * The return value is always a valid (non-NULL) demux pointer.
+ */
+demux_t *demux_FilterChainNew( demux_t *source, const char *list ) VLC_USED;
+
 bool demux_FilterEnable( demux_t *p_demux_chain, const char* psz_demux );
 bool demux_FilterDisable( demux_t *p_demux_chain, const char* psz_demux );
 
diff --git a/src/input/input_internal.h b/src/input/input_internal.h
index 2958dbaa3f..974271f8a0 100644
--- a/src/input/input_internal.h
+++ b/src/input/input_internal.h
@@ -45,7 +45,7 @@ typedef struct
 {
     VLC_COMMON_MEMBERS
 
-    demux_t  *p_demux; /**< Demux plugin instance */
+    demux_t  *p_demux; /**< Demux object (most downstream) */
 
     /* Title infos for that input */
     bool         b_title_demux; /* Titles/Seekpoints provided by demux */
diff --git a/src/input/stream.h b/src/input/stream.h
index a819ab83c2..c481e7fe10 100644
--- a/src/input/stream.h
+++ b/src/input/stream.h
@@ -37,21 +37,50 @@ void stream_CommonDelete( stream_t *s );
 stream_t *stream_AccessNew(vlc_object_t *, input_thread_t *, bool, const char *);
 
 /**
- * Automatically wraps a stream with any applicable stream filter.
- * @return the (outermost/downstream) stream filter; if no filters were added,
- * then the function return the source parameter.
- * @note The function never returns NULL.
+ * Probes stream filters automatically.
+ *
+ * This function automatically and repeatedly probes for applicable stream
+ * filters to append downstream of an existing stream. Any such filter will
+ * convert the stream into another stream, e.g. decompressing it or extracting
+ * the list of contained files (playlist).
+ *
+ * This function transfers ownership of the supplied stream to the following
+ * stream filter, of the first stream filter to the second stream filter, and
+ * so on. Any attempt to access the original stream filter directly is
+ * explicitly undefined.
+ *
+ * If, and only if, no filters were probed succesfully, a pointer to the
+ * unchanged source stream will be returned. Otherwise, this returns a stream
+ * filter. The return value is thus guaranteed to be non-NULL.
+ *
+ * @param source input stream around which to build a filter chain
+ *
+ * @return the last, most downstream stream object.
+ *
+ * @note The return value must be freed with vlc_stream_Delete() after use.
+ * This will automatically free the whole chain and the underlying stream.
  */
 stream_t *stream_FilterAutoNew( stream_t *source ) VLC_USED;
 
 /**
- * This function creates a chain of filters according to the colon-separated
- * list.
+ * Builds an explicit chain of stream filters.
+ *
+ * This function creates a chain of filters according to a supplied list.
+ *
+ * See also stream_FilterAutoNew(). Those two functions have identical
+ * semantics; the only difference lies in how the list of probed filters is
+ * determined (manually versus automatically).
+ *
+ * If the list is empty, or if probing each of the requested filters failed,
+ * this function will return a pointer to the supplied source stream.
+ *
+ * @param source input stream around which to build a filter chain
+ * @param list colon-separated list of stream filters (upstream first)
  *
- * You must release the returned value using vlc_stream_Delete unless it is
- * used as a source to another filter.
+ * @return The last stream (filter) in the chain.
+ * The return value is always a valid (non-NULL) stream pointer.
  */
-stream_t *stream_FilterChainNew( stream_t *p_source, const char *psz_chain );
+stream_t *stream_FilterChainNew( stream_t *source, const char *list ) VLC_USED;
 
 /**
  * Attach \ref stream_extractor%s according to specified data