first commit

nghttp2/doc/nghttp2_session_upgrade.rst

@@ -0,0 +1,55 @@
+
+nghttp2_session_upgrade
+=======================
+
+Synopsis
+--------
+
+*#include <nghttp2/nghttp2.h>*
+
+.. 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.
+    
+    .. warning::
+    
+      This function is deprecated in favor of
+      `nghttp2_session_upgrade2()`, because this function lacks the
+      parameter to tell the library the request method used in the
+      original HTTP request.  This information is required for client
+      to validate actual response body length against content-length
+      header field (see `nghttp2_option_set_no_http_messaging()`).  If
+      HEAD is used in request, the length of response body must be 0
+      regardless of value included in content-length header field.
+    
+    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_error.NGHTTP2_ERR_NOMEM`
+        Out of memory.
+    :macro:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
+        The *settings_payload* is badly formed.
+    :macro:`nghttp2_error.NGHTTP2_ERR_PROTO`
+        The stream ID 1 is already used or closed; or is not available.