doc/nghttp2_submit_goaway.rst

   1
   2 nghttp2_submit_goaway
   3 =====================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_submit_goaway(nghttp2_session *session, uint8_t flags, int32_t last_stream_id, uint32_t error_code, const uint8_t *opaque_data, size_t opaque_data_len)
  11
  12
  13     Submits GOAWAY frame with the last stream ID *last_stream_id* and
  14     the error code *error_code*.
  15
  16     The pre-defined error code is one of :macro:`nghttp2_error_code`.
  17
  18     The *flags* is currently ignored and should be
  19     :macro:`NGHTTP2_FLAG_NONE`.
  20
  21     The *last_stream_id* is peer's stream ID or 0.  So if *session* is
  22     initialized as client, *last_stream_id* must be even or 0.  If
  23     *session* is initialized as server, *last_stream_id* must be odd or
  24     0.
  25
  26     The HTTP/2 specification says last_stream_id must not be increased
  27     from the value previously sent.  So the actual value sent as
  28     last_stream_id is the minimum value between the given
  29     *last_stream_id* and the last_stream_id previously sent to the
  30     peer.
  31
  32     If the *opaque_data* is not ``NULL`` and *opaque_data_len* is not
  33     zero, those data will be sent as additional debug data.  The
  34     library makes a copy of the memory region pointed by *opaque_data*
  35     with the length *opaque_data_len*, so the caller does not need to
  36     keep this memory after the return of this function.  If the
  37     *opaque_data_len* is 0, the *opaque_data* could be ``NULL``.
  38
  39     After successful transmission of GOAWAY, following things happen.
  40     All incoming streams having strictly more than *last_stream_id* are
  41     closed.  All incoming HEADERS which starts new stream are simply
  42     ignored.  After all active streams are handled, both
  43     `nghttp2_session_want_read()` and `nghttp2_session_want_write()`
  44     return 0 and the application can close session.
  45
  46     This function returns 0 if it succeeds, or one of the following
  47     negative error codes:
  48
  49     :macro:`NGHTTP2_ERR_NOMEM`
  50         Out of memory.
  51     :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
  52         The *opaque_data_len* is too large; the *last_stream_id* is
  53         invalid.