| blob | 59365a26d21b10f51b41fe973d9a96bd15f7a846 |
1 /**
2 * \defgroup mrl Media Resource Locator (MRL)
3 *
4 * The \em MRL-specification is a VLC intrinsic extension to <a
5 * href="https://tools.ietf.org/html/rfc3986">RFC3986</a>, providing means to
6 * associate extra media-related information within the \em resource-identifier.
7 *
8 * \note \em MRLs are only used when an item is to be played by \em VLC,
9 * through a direct (or indirect) call to \ref input_Create and \ref
10 * input_CreatePreparser, which means that they are not handled by
11 * functions such as \ref vlc_UrlParse and \ref vlc_stream_NewURL (as
12 * implied by their names).
13 *
14 * \section mrl_introduction Introduction
15 *
16 * As an example, with the use of an \em MRL one can specify that a certain \ref
17 * demux is to be unconditionally used for a specific resource, such as in the
18 * below (forcing usage of \em demuxdump).
19 *
20 * \verbatim http/demuxdump://example.com/path/to/media\endverbatim
21 *
22 * There is also the possibility of specifying attributes related to the
23 * playback behavior of the referred to resource, such as what range of titles
24 * and chapters that are to be played.
25 *
26 * \verbatim http://example.com/media.mkv#0:1-1:5\endverbatim
27 *
28 * \section mrl_technical Technical Information
29 *
30 * The overall specification in <a
31 * href="https://tools.ietf.org/html/rfc3986">RFC3986</a> are inherited by \em
32 * MRLs, though some entities have been redefined in order to provide support
33 * for additional \em media-related \em information, other entities (treated as
34 * arbitrary data in a \em URI) is explicitly defined to have special meaning
35 * within an \em MRL.
36 *
37 * \subsection mrl_technical_scheme 3.1. Scheme
38 *
39 * In an \em MRL, what <a href="https://tools.ietf.org/html/rfc3986">RFC3986</a>
40 * refers to as `scheme` is allowed to contain a \em forward-slash, and if such
41 * is present, the data prior to the slash denotes the \em scheme (as originally
42 * defined by \em RFC3986), whereas the data that follows specifies a list of
43 * \link demux demultiplexers\endlink to probe when dealing with the resource.
44 *
45 * mrl-scheme = *( %x20-7E )
46 * mrl-demux = *( %x20-2B / %x2D-7E )
47 * scheme =/ ( mrl-scheme [ "/" mrl-demux ] )
48 *
49 * - If the specified \ref demux specified in `mrl-demuxer` can't
50 * handle the resource, the media shall fail to open.
51 *
52 * \subsection mrl_technical_fragment 3.5. Fragment
53 *
54 * \em MRL extends the <a
55 * href="https://tools.ietf.org/html/rfc5234">ABNF</a> for \em fragment-data as
56 * specified by <a href="https://tools.ietf.org/html/rfc3986">RFC3986</a> so
57 * that individual pieces can be identified within the payload.
58 *
59 * \verbatim
60 mrlfrag-query = query
61 mrlfrag-subdelims = "$" / "&" / "'" / "(" / ")" / "*" / "+" /
62 "," / ";" / "=" / pct-encoded
63 mrlfrag-entity = "!/" *( mrlfrag-subdelims )
64 fragment =/ ( *( mrlfrag-entity ) [ "?" mrlfrag-query ] ) /
65 mrlfrag-query / mrl-section
66 \endverbatim
67 *
68 * <h4>Generating `fragment` </h4>
69 *
70 * 1. Start with an empty payload
71 * 2. For each subentry (from top to bottom)
72 * - append `"!/"` to the payload
73 * - url-encode characters not matching `mrlfrag-subdelims`
74 * - append the url-encoded data
75 * 3. If the payload is not empty, and there is a `mrlfrag-query`
76 * - append "?" to the payload
77 * 4. append the `mrlfrag-query` to the payload
78 *
79 * <h4>Parsing `fragment`</h4>
80 *
81 * 1. If the payload begins with `"!/"`
82 * - skip the initial two characters
83 * - extract data up until the first occurance of either `?` or `!`
84 * - url-decode the extracted data
85 * - the decoded data is a `mrlfrag-entity`
86 * - goto step `1` with the data following the extracted data
87 * 2. If the payload begins with `"?"`
88 * - skip the initial character
89 * 3. the payload contains the `mrlfrag-query`
90 *
91 * \subsubsection mrl_technical_fragment_query Fragment Query
92 *
93 * Data within `fragment`, as defined by the previous section, can have special
94 * meaning if it matches the entities listed below (priority in order of
95 * appearance).
96 *
97 * - \parblock
98 * <h4>`mrl-section`</h4>
99 * \verbatim
100 mrl-title = DIGIT *DIGIT
101 mrl-chapter = DIGIT *DIGIT
102 mrl-section = mrl-title [ ":" mrl-chapter ] [ "-" mrl-title [ ":" mrl-chapter ] ]
103 \endverbatim
104 * If the data contained in the `fragmentof` an \em MRL matches
105 * `mrl-section`, the data denotes the offset to start, and conditionally stop
106 * (if present), the resource during playback,
107 *
108 * `mrl-title` and `mrl-chapter` refers to the index of the \em title and \em
109 * chapter, respectively. Data before the optional hyphen denotes the starting
110 * position, and data following it, if any, denotes where to stop.
111 *
112 * The range is specified as `[start,stop)`, meaning that playback will
113 * continue until \em stop has been reached, it does not include the contents
114 * of the entity referred to by \em stop.
115 *
116 * \endparblock
117 *
118 * - \parblock
119 * <h4>`mrlfrag-query`</h4>
120 *
121 * The data within the `mrlfrag-query` shall be `key=value` pairs, each
122 * delimited by an ampersand (this means that an ampersand in either \em key
123 * or \em value must be URL-encoded). \em key-value pairs not specified in
124 * the table below are ignored.
125 *
126 * <table>
127 * <tr> <td></td> <th>Value</th> <th>Description</th> </tr>
128 * <tr> <th>t</th> <td>Integer</td> <td>specifies where to start playback (in seconds)</td> </tr>
129 * <tr> <th>s</th> <td>Integer</td> <td>specifies where to stop playback (in seconds)</td> </tr>
130 * </table>
131 *
132 * \endparblock
133 **/