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     If called from client side, the *settings_payload* must be the
  18     value sent in ``HTTP2-Settings`` header field and must be decoded
  19     by base64url decoder.  The *settings_payloadlen* is the length of
  20     *settings_payload*.  The *settings_payload* is unpacked and its
  21     setting values will be submitted using `nghttp2_submit_settings()`.
  22     This means that the client application code does not need to submit
  23     SETTINGS by itself.  The stream with stream ID=1 is opened and the
  24     *stream_user_data* is used for its stream_user_data.  The opened
  25     stream becomes half-closed (local) state.
  26
  27     If called from server side, the *settings_payload* must be the
  28     value received in ``HTTP2-Settings`` header field and must be
  29     decoded by base64url decoder.  The *settings_payloadlen* is the
  30     length of *settings_payload*.  It is treated as if the SETTINGS
  31     frame with that payload is received.  Thus, callback functions for
  32     the reception of SETTINGS frame will be invoked.  The stream with
  33     stream ID=1 is opened.  The *stream_user_data* is ignored.  The
  34     opened stream becomes half-closed (remote).
  35
  36     This function returns 0 if it succeeds, or one of the following
  37     negative error codes:
  38
  39     :macro:`NGHTTP2_ERR_NOMEM`
  40         Out of memory.
  41     :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
  42         The *settings_payload* is badly formed.
  43     :macro:`NGHTTP2_ERR_PROTO`
  44         The stream ID 1 is already used or closed; or is not available.