doc/nghttp2_session_upgrade.rst

   1
   2 nghttp2_session_upgrade
   3 =======================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_session_upgrade(nghttp2_session *session, const uint8_t *settings_payload, size_t settings_payloadlen, void *stream_user_data)
  11
  12
  13     Performs post-process of HTTP Upgrade request.  This function can
  14     be called from both client and server, but the behavior is very
  15     different in each other.
  16
  17     .. warning::
  18
  19       This function is deprecated in favor of
  20       `nghttp2_session_upgrade2()`, because this function lacks the
  21       parameter to tell the library the request method used in the
  22       original HTTP request.  This information is required for client
  23       to validate actual response body length against content-length
  24       header field (see `nghttp2_option_set_no_http_messaging()`).  If
  25       HEAD is used in request, the length of response body must be 0
  26       regardless of value included in content-length header field.
  27
  28     If called from client side, the *settings_payload* must be the
  29     value sent in ``HTTP2-Settings`` header field and must be decoded
  30     by base64url decoder.  The *settings_payloadlen* is the length of
  31     *settings_payload*.  The *settings_payload* is unpacked and its
  32     setting values will be submitted using `nghttp2_submit_settings()`.
  33     This means that the client application code does not need to submit
  34     SETTINGS by itself.  The stream with stream ID=1 is opened and the
  35     *stream_user_data* is used for its stream_user_data.  The opened
  36     stream becomes half-closed (local) state.
  37
  38     If called from server side, the *settings_payload* must be the
  39     value received in ``HTTP2-Settings`` header field and must be
  40     decoded by base64url decoder.  The *settings_payloadlen* is the
  41     length of *settings_payload*.  It is treated as if the SETTINGS
  42     frame with that payload is received.  Thus, callback functions for
  43     the reception of SETTINGS frame will be invoked.  The stream with
  44     stream ID=1 is opened.  The *stream_user_data* is ignored.  The
  45     opened stream becomes half-closed (remote).
  46
  47     This function returns 0 if it succeeds, or one of the following
  48     negative error codes:
  49
  50     :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM`
  51         Out of memory.
  52     :macro:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
  53         The *settings_payload* is badly formed.
  54     :macro:`nghttp2_error.NGHTTP2_ERR_PROTO`
  55         The stream ID 1 is already used or closed; or is not available.