Update doc

_sources/apiref.txt

@@ -1126,6 +1126,64 @@ Functions
     :macro:`NGHTTP2_ERR_NOMEM`
         Out of memory.
 
+.. function:: int nghttp2_session_upgrade(nghttp2_session *session, const uint8_t *settings_payload, size_t settings_payloadlen, void *stream_user_data)
+
+    
+    Performs post-process of HTTP Upgrade request. This function can be
+    called from both client and server, but the behavior is very
+    different in each other.
+    
+    If called from client side, the *settings_payload* must be the
+    value sent in HTTP2-Settings header field and must be decoded by
+    base64url decoder. The *settings_payloadlen* is the length of
+    *settings_payload*. The *settings_payload* is unpacked and its
+    setting values will be submitted using
+    nghttp2_submit_settings(). This means that the client application
+    code does not need to submit SETTINGS by itself. The stream with
+    stream ID=1 is opened and the *stream_user_data* is used for its
+    stream_user_data. The opened stream becomes half-closed (local)
+    state.
+    
+    If called from server side, the *settings_payload* must be the
+    value received in HTTP2-Settings header field and must be decoded
+    by base64url decoder. The *settings_payloadlen* is the length of
+    *settings_payload*. It is treated as if the SETTINGS frame with
+    that payload is received. Thus, callback functions for the
+    reception of SETTINGS frame will be invoked. The stream with stream
+    ID=1 is opened. The *stream_user_data* is ignored. The opened
+    stream becomes half-closed (remote).
+    
+    This function returns 0 if it succeeds, or one of the following
+    negative error codes:
+    
+    :macro:`NGHTTP2_ERR_NOMEM`
+        Out of memory.
+    :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
+        The *settings_payload* is badly formed.
+    :macro:`NGHTTP2_ERR_PROTO`
+        The stream ID 1 is already used or closed; or is not available;
+        or the *settings_payload* does not include both
+        NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS and
+        NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE.
+
+.. function:: ssize_t nghttp2_pack_settings_payload(uint8_t *buf, nghttp2_settings_entry *iv, size_t niv)
+
+    
+    Serializes the SETTINGS values *iv* in the *buf*. The number of
+    entry pointed by *iv* array is given by the *niv*. This function
+    may reorder the pointers in *iv*. The *buf* must have enough region
+    to hold serialized data. The required space for the *niv* entries
+    are 8**niv* bytes. This function is used mainly for creating
+    SETTINGS payload to be sent with HTTP2-Settings header field in
+    HTTP Upgrade request. The data written in *buf* is not still
+    base64url encoded and the application is responsible to do that.
+    
+    This function returns the number of bytes written in *buf*, or one
+    of the following negative error codes:
+    
+    :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
+        The *iv* contains duplicate settings ID or invalid value.
+
 .. function:: const char* nghttp2_strerror(int lib_error_code)
 
     

apiref.html

@@ -1566,6 +1566,64 @@ negative error codes:</p>
 </dl>
 </dd></dl>
 
+<dl class="function">
+<dt id="nghttp2_session_upgrade">
+int <tt class="descname">nghttp2_session_upgrade</tt><big>(</big><a class="reference internal" href="#nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, const uint8_t<em>&nbsp;*settings_payload</em>, size_t<em>&nbsp;settings_payloadlen</em>, void<em>&nbsp;*stream_user_data</em><big>)</big><a class="headerlink" href="#nghttp2_session_upgrade" title="Permalink to this definition">¶</a></dt>
+<dd><p>Performs post-process of HTTP Upgrade request. This function can be
+called from both client and server, but the behavior is very
+different in each other.</p>
+<p>If called from client side, the <em>settings_payload</em> must be the
+value sent in HTTP2-Settings header field and must be decoded by
+base64url decoder. The <em>settings_payloadlen</em> is the length of
+<em>settings_payload</em>. The <em>settings_payload</em> is unpacked and its
+setting values will be submitted using
+nghttp2_submit_settings(). This means that the client application
+code does not need to submit SETTINGS by itself. The stream with
+stream ID=1 is opened and the <em>stream_user_data</em> is used for its
+stream_user_data. The opened stream becomes half-closed (local)
+state.</p>
+<p>If called from server side, the <em>settings_payload</em> must be the
+value received in HTTP2-Settings header field and must be decoded
+by base64url decoder. The <em>settings_payloadlen</em> is the length of
+<em>settings_payload</em>. It is treated as if the SETTINGS frame with
+that payload is received. Thus, callback functions for the
+reception of SETTINGS frame will be invoked. The stream with stream
+ID=1 is opened. The <em>stream_user_data</em> is ignored. The opened
+stream becomes half-closed (remote).</p>
+<p>This function returns 0 if it succeeds, or one of the following
+negative error codes:</p>
+<dl class="docutils">
+<dt><a class="reference internal" href="#NGHTTP2_ERR_NOMEM" title="NGHTTP2_ERR_NOMEM"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_NOMEM</span></tt></a></dt>
+<dd>Out of memory.</dd>
+<dt><a class="reference internal" href="#NGHTTP2_ERR_INVALID_ARGUMENT" title="NGHTTP2_ERR_INVALID_ARGUMENT"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_INVALID_ARGUMENT</span></tt></a></dt>
+<dd>The <em>settings_payload</em> is badly formed.</dd>
+<dt><a class="reference internal" href="#NGHTTP2_ERR_PROTO" title="NGHTTP2_ERR_PROTO"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_PROTO</span></tt></a></dt>
+<dd>The stream ID 1 is already used or closed; or is not available;
+or the <em>settings_payload</em> does not include both
+NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS and
+NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE.</dd>
+</dl>
+</dd></dl>
+
+<dl class="function">
+<dt id="nghttp2_pack_settings_payload">
+ssize_t <tt class="descname">nghttp2_pack_settings_payload</tt><big>(</big>uint8_t<em>&nbsp;*buf</em>, <a class="reference internal" href="#nghttp2_settings_entry" title="nghttp2_settings_entry">nghttp2_settings_entry</a><em>&nbsp;*iv</em>, size_t<em>&nbsp;niv</em><big>)</big><a class="headerlink" href="#nghttp2_pack_settings_payload" title="Permalink to this definition">¶</a></dt>
+<dd><p>Serializes the SETTINGS values <em>iv</em> in the <em>buf</em>. The number of
+entry pointed by <em>iv</em> array is given by the <em>niv</em>. This function
+may reorder the pointers in <em>iv</em>. The <em>buf</em> must have enough region
+to hold serialized data. The required space for the <em>niv</em> entries
+are 8**niv* bytes. This function is used mainly for creating
+SETTINGS payload to be sent with HTTP2-Settings header field in
+HTTP Upgrade request. The data written in <em>buf</em> is not still
+base64url encoded and the application is responsible to do that.</p>
+<p>This function returns the number of bytes written in <em>buf</em>, or one
+of the following negative error codes:</p>
+<dl class="docutils">
+<dt><a class="reference internal" href="#NGHTTP2_ERR_INVALID_ARGUMENT" title="NGHTTP2_ERR_INVALID_ARGUMENT"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_INVALID_ARGUMENT</span></tt></a></dt>
+<dd>The <em>iv</em> contains duplicate settings ID or invalid value.</dd>
+</dl>
+</dd></dl>
+
 <dl class="function">
 <dt id="nghttp2_strerror">
 const char* <tt class="descname">nghttp2_strerror</tt><big>(</big>int<em>&nbsp;lib_error_code</em><big>)</big><a class="headerlink" href="#nghttp2_strerror" title="Permalink to this definition">¶</a></dt>

genindex.html

@@ -456,12 +456,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_on_data_chunk_recv_callback">nghttp2_on_data_chunk_recv_callback (C type)</a>
   </dt>
@@ -515,6 +515,10 @@
   </dt>
 
       
+  <dt><a href="apiref.html#nghttp2_pack_settings_payload">nghttp2_pack_settings_payload (C function)</a>
+  </dt>
+
+      
   <dt><a href="apiref.html#NGHTTP2_PING">NGHTTP2_PING (C macro)</a>
   </dt>
 
@@ -727,6 +731,10 @@
   </dt>
 
       
+  <dt><a href="apiref.html#nghttp2_session_upgrade">nghttp2_session_upgrade (C function)</a>
+  </dt>
+
+      
   <dt><a href="apiref.html#nghttp2_session_want_read">nghttp2_session_want_read (C function)</a>
   </dt>