[vlc-devel] [PATCH 02/21] input/stream: stream-fragments: add initial documentation

[Filip Roséen]

This commit does not introduce any new functionality, but it describes
the semantics associated with a new addition to the vlc-core called
named "Stream Fragments".
---
 include/vlc_stream.h | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/include/vlc_stream.h b/include/vlc_stream.h
index 2095729..e81005b 100644
--- a/include/vlc_stream.h
+++ b/include/vlc_stream.h
@@ -434,6 +434,106 @@ do { \
 } while (0)
 
 /**
+ * \defgroup stream_fragments Stream Fragments
+ * @{
+ * \section stream_fragments_introduction Introduction to Fragments
+ *
+ * If a stream is a directory, \em stream-fragments is the mechanism used to
+ * specify a sub-item directly in the MRL referring to its parent. In short,
+ * they are used to specify that one would like to access a certain entity
+ * within something else; like a file within a compressed archive, or a certain
+ * track on an audio cd.
+ *
+ * \subsection fragments_introduction What are fragments?
+ *
+ * \em stream-fragments are very much like the fragment described in \link
+ * https://tools.ietf.org/html/rfc3986#section-3.5 RFC3986/3.5
+ * Fragment\endlink, though (has hinted by the plural form of "fragment") VLC
+ * can handle a fragment within a fragment; meaning that one can refer to a
+ * secondary resource (nested entity), within another secondary resource.
+ *
+ * <b>Examples</b>
+ *
+ * If one would like to refer to a paragraph named `documentation` within an
+ * html-document named `index.html`, the URL will look something like the below.
+ *
+ * \verbatim scheme://host/index.html#documentation\endverbatim
+ *
+ * If we were to refer to a resource named `cats.avi` within a zip-archive named
+ * `media.zip`, it would (following the same semantics as the previous example)
+ * look like the following.
+ *
+ *  \verbatim proto://host/media.zip#cats.avi\endverbatim
+ *
+ * If `media.zip` includes another archive, let's say `music.rar`, which in
+ * turn contains `the-perfect-song.mp3`, we need a way to refer to an entity
+ * within an entity, within an entity.
+ *
+ * In order to do this, \em stream-fragments specifies that we append an
+ * extra url-encoded hash (`#`) followed by the nested, url-encoded, name that
+ * refers to the entity we would like to access.
+ *
+ * \verbatim proto://host/media.zip#music.rar%23the-perfect-song.mp3\endverbatim
+ *
+ * \subsection technical Technical Info
+ *
+ * <b>Creating an MRL with \em stream-fragments</b>
+ *
+ * To generate an MRL with \em stream-fragments, the following described
+ * algorithm shall be used.
+ *
+ * 1. Store the URI for the \em primary-resource as `mrl`
+ * 2. For each \em stream-fragment with offset `N` (initially `0`):
+ *      1. Append a `#` url-encoded `N` times.
+ *      2. Replace any occurrence of `#` within the \em stream-fragment data
+ *         with `##`.
+ *      3. URL-encode the escaped data `N+1` times.
+ *      4. Append the URL-encoded data to the `mrl`.
+ *
+ * > As described, any use of `#` within the original \em stream-fragment data
+ * > needs to be replaced by `##` in order for it not to be interpreted as the
+ * > fragment-end during parsing.
+ *
+ * <b>Parsing an MRL with \em stream-fragments</b>
+ *
+ * 1. The MRL is split on the first occurrence of `#` (if any)
+ * 2. The data prior to `#` (if any) is the \em primary-resource
+ * 3. The data following the `#` is parsed as follows (`N` is initially `0`):
+ *
+ *      1. URL-decode the data.
+ *      2. Split the decoded data on the first occurrence of `#` not followed by
+ *         another `#` (if any).
+ *      3. Collapse the data prior to the split by replacing any occurrence of
+ *         `##` with `#`.
+ *      4. Store the collapsed data as fragment `N`.
+ *      5. Increase `N` by one.
+ *      6. Treat the data following the split by applying the same semantics.
+ *
+ * <b>Examples</b>
+ *
+ *\verbatim scheme://host/hiphop.mp3" => [ ] \endverbatim
+ *\verbatim cdda://#track-1 => [ "track-1" ] \endverbatim
+ *\verbatim
+  scheme://host/media.zip#music.rar%23rock.tgz%2523track%2525231.mp3 => [
+      "music.rar",
+      "rock.tgz",
+      "track#1.mp3" ]
+  \endverbatim
+
+  \subsection additional_resources Additional Resources
+ *
+ * See the following functions for further information regarding how to interact
+ * with any \em stream-fragments present when implementing an \em accessor or
+ * \em stream_filter.
+ *
+ * - ::vlc_stream_PeekFragment
+ * - ::vlc_stream_PopFragment
+ * - ::vlc_stream_CreateFragmentedMRL
+ *
+ * @}
+ **/
+
+/**
  * @}
  */
 
-- 
2.9.2