Skip to content

N
nghttp2
Commit 425a54a9 authored by Tatsuhiro Tsujikawa's avatar Tatsuhiro Tsujikawa
Browse files
Options

Update doc

parent de27a9bf
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 115 additions and 3 deletions
_sources/apiref.txt
View file @ 425a54a9
......@@ -997,6 +997,20 @@ Types (structs, unions and typedefs)
The *name* may be ``NULL`` if the *namelen* is 0. The same thing
can be said about the *value*.
Please note that nghttp2 library does not perform any validity
check against the *name* and the *value*. For example, the
*namelen* could be 0, and/or the *value* contains ``0x0a`` or
``0x0d``. The application must check them if it matters. The
helper function `nghttp2_check_header_name()` and
`nghttp2_check_header_value()` provide simple validation against
HTTP2 header field construction rule.
One more thing to note is that the *value* may contain ``NULL``
(``0x00``) characters. It is used to concatenate header values
which share the same header field name. The application should
split these values if it wants to get individual value. This
concatenation is used in order to keep the ordering of headers.
If the application uses `nghttp2_session_mem_recv()`, it can return
:macro:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
return without processing further input bytes. The memory pointed
......@@ -2007,4 +2021,24 @@ Functions
Returns nonzero if the :type:`nghttp2_error` library error code
*lib_error* is fatal.
.. function:: int nghttp2_check_header_name(const uint8_t *name, size_t len)
Returns nonzero if HTTP header field name *name* of length *len* is
valid according to
http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2
Because this is a header field name in HTTP2, the upper cased alphabet
is treated as error.
.. function:: int nghttp2_check_header_value(const uint8_t *value, size_t len)
Returns nonzero if HTTP header field value *value* of length *len*
is valid according to
http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2
Because this is HTTP2 header field value, it can contain NULL
character (0x00).
apiref.html
View file @ 425a54a9
......@@ -1502,6 +1502,18 @@ is an error in decompression,
invoked.</p>
<p>The <em>name</em> may be <tt class="docutils literal"><span class="pre">NULL</span></tt> if the <em>namelen</em> is 0. The same thing
can be said about the <em>value</em>.</p>
<p>Please note that nghttp2 library does not perform any validity
check against the <em>name</em> and the <em>value</em>. For example, the
<em>namelen</em> could be 0, and/or the <em>value</em> contains <tt class="docutils literal"><span class="pre">0x0a</span></tt> or
<tt class="docutils literal"><span class="pre">0x0d</span></tt>. The application must check them if it matters. The
helper function <a class="reference internal" href="#nghttp2_check_header_name" title="nghttp2_check_header_name"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_check_header_name()</span></tt></a> and
<a class="reference internal" href="#nghttp2_check_header_value" title="nghttp2_check_header_value"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_check_header_value()</span></tt></a> provide simple validation against
HTTP2 header field construction rule.</p>
<p>One more thing to note is that the <em>value</em> may contain <tt class="docutils literal"><span class="pre">NULL</span></tt>
(<tt class="docutils literal"><span class="pre">0x00</span></tt>) characters. It is used to concatenate header values
which share the same header field name. The application should
split these values if it wants to get individual value. This
concatenation is used in order to keep the ordering of headers.</p>
<p>If the application uses <a class="reference internal" href="#nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a>, it can return
<a class="reference internal" href="#NGHTTP2_ERR_PAUSE" title="NGHTTP2_ERR_PAUSE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_PAUSE</span></tt></a> to make <a class="reference internal" href="#nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a>
return without processing further input bytes. The memory pointed
......@@ -2532,6 +2544,26 @@ int <tt class="descname">nghttp2_is_fatal</tt><big>(</big>int<em>&nbsp;lib_error
<em>lib_error</em> is fatal.</p>
</dd></dl>
<dl class="function">
<dt id="nghttp2_check_header_name">
int <tt class="descname">nghttp2_check_header_name</tt><big>(</big>const uint8_t<em>&nbsp;*name</em>, size_t<em>&nbsp;len</em><big>)</big><a class="headerlink" href="#nghttp2_check_header_name" title="Permalink to this definition"></a></dt>
<dd><p>Returns nonzero if HTTP header field name <em>name</em> of length <em>len</em> is
valid according to
<a class="reference external" href="http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2">http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2</a></p>
<p>Because this is a header field name in HTTP2, the upper cased alphabet
is treated as error.</p>
</dd></dl>
<dl class="function">
<dt id="nghttp2_check_header_value">
int <tt class="descname">nghttp2_check_header_value</tt><big>(</big>const uint8_t<em>&nbsp;*value</em>, size_t<em>&nbsp;len</em><big>)</big><a class="headerlink" href="#nghttp2_check_header_value" title="Permalink to this definition"></a></dt>
<dd><p>Returns nonzero if HTTP header field value <em>value</em> of length <em>len</em>
is valid according to
<a class="reference external" href="http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2">http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2</a></p>
<p>Because this is HTTP2 header field value, it can contain NULL
character (0x00).</p>
</dd></dl>
</div>
</div>
......
genindex.html
View file @ 425a54a9
......@@ -151,6 +151,14 @@
</dt>
<dt><a href="apiref.html#nghttp2_check_header_name">nghttp2_check_header_name (C function)</a>
</dt>
<dt><a href="apiref.html#nghttp2_check_header_value">nghttp2_check_header_value (C function)</a>
</dt>
<dt><a href="apiref.html#NGHTTP2_CLIENT_CONNECTION_HEADER">NGHTTP2_CLIENT_CONNECTION_HEADER (C macro)</a>
</dt>
......@@ -602,12 +610,12 @@
<dt><a href="apiref.html#nghttp2_nv.value">nghttp2_nv.value (C member)</a>
</dt>
</dl></td>
<td style="width: 33%" valign="top"><dl>
<dt><a href="apiref.html#nghttp2_nv.valuelen">nghttp2_nv.valuelen (C member)</a>
</dt>
</dl></td>
<td style="width: 33%" valign="top"><dl>
<dt><a href="apiref.html#nghttp2_nv_compare_name">nghttp2_nv_compare_name (C function)</a>
</dt>
......
nghttp2.h.html
View file @ 425a54a9
......@@ -1242,6 +1242,20 @@
<span class="cm"> * The |name| may be ``NULL`` if the |namelen| is 0. The same thing</span>
<span class="cm"> * can be said about the |value|.</span>
<span class="cm"> *</span>
<span class="cm"> * Please note that nghttp2 library does not perform any validity</span>
<span class="cm"> * check against the |name| and the |value|. For example, the</span>
<span class="cm"> * |namelen| could be 0, and/or the |value| contains ``0x0a`` or</span>
<span class="cm"> * ``0x0d``. The application must check them if it matters. The</span>
<span class="cm"> * helper function `nghttp2_check_header_name()` and</span>
<span class="cm"> * `nghttp2_check_header_value()` provide simple validation against</span>
<span class="cm"> * HTTP2 header field construction rule.</span>
<span class="cm"> *</span>
<span class="cm"> * One more thing to note is that the |value| may contain ``NULL``</span>
<span class="cm"> * (``0x00``) characters. It is used to concatenate header values</span>
<span class="cm"> * which share the same header field name. The application should</span>
<span class="cm"> * split these values if it wants to get individual value. This</span>
<span class="cm"> * concatenation is used in order to keep the ordering of headers.</span>
<span class="cm"> *</span>
<span class="cm"> * If the application uses `nghttp2_session_mem_recv()`, it can return</span>
<span class="cm"> * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`</span>
<span class="cm"> * return without processing further input bytes. The memory pointed</span>
......@@ -2448,6 +2462,30 @@
<span class="cm"> */</span>
<span class="kt">int</span> <span class="nf">nghttp2_is_fatal</span><span class="p">(</span><span class="kt">int</span> <span class="n">lib_error</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * @function</span>
<span class="cm"> *</span>
<span class="cm"> * Returns nonzero if HTTP header field name |name| of length |len| is</span>
<span class="cm"> * valid according to</span>
<span class="cm"> * http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2</span>
<span class="cm"> *</span>
<span class="cm"> * Because this is a header field name in HTTP2, the upper cased alphabet</span>
<span class="cm"> * is treated as error.</span>
<span class="cm"> */</span>
<span class="kt">int</span> <span class="nf">nghttp2_check_header_name</span><span class="p">(</span><span class="k">const</span> <span class="kt">uint8_t</span> <span class="o">*</span><span class="n">name</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">);</span>
<span class="cm">/**</span>
<span class="cm"> * @function</span>
<span class="cm"> *</span>
<span class="cm"> * Returns nonzero if HTTP header field value |value| of length |len|</span>
<span class="cm"> * is valid according to</span>
<span class="cm"> * http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2</span>
<span class="cm"> *</span>
<span class="cm"> * Because this is HTTP2 header field value, it can contain NULL</span>
<span class="cm"> * character (0x00).</span>
<span class="cm"> */</span>
<span class="kt">int</span> <span class="nf">nghttp2_check_header_value</span><span class="p">(</span><span class="k">const</span> <span class="kt">uint8_t</span> <span class="o">*</span><span class="n">value</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">);</span>
<span class="cp">#ifdef __cplusplus</span>
<span class="p">}</span>
<span class="cp">#endif</span>
......
objects.inv
View file @ 425a54a9
No preview for this file type
searchindex.js
View file @ 425a54a9
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment