doc/nghttp2_submit_headers.rst

   1
   2 nghttp2_submit_headers
   3 ======================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int32_t nghttp2_submit_headers(nghttp2_session *session, uint8_t flags, int32_t stream_id, const nghttp2_priority_spec *pri_spec, const nghttp2_nv *nva, size_t nvlen, void *stream_user_data)
  11
  12
  13     Submits HEADERS frame. The *flags* is bitwise OR of the
  14     following values:
  15
  16     * :macro:`NGHTTP2_FLAG_END_STREAM`
  17
  18     If *flags* includes :macro:`NGHTTP2_FLAG_END_STREAM`, this frame has
  19     END_STREAM flag set.
  20
  21     The library handles the CONTINUATION frame internally and it
  22     correctly sets END_HEADERS to the last sequence of the PUSH_PROMISE
  23     or CONTINUATION frame.
  24
  25     If the *stream_id* is -1, this frame is assumed as request (i.e.,
  26     request HEADERS frame which opens new stream).  In this case, the
  27     assigned stream ID will be returned.  Otherwise, specify stream ID
  28     in *stream_id*.
  29
  30     The *pri_spec* is priority specification of this request.  ``NULL``
  31     means the default priority (see
  32     `nghttp2_priority_spec_default_init()`).  To specify the priority,
  33     use `nghttp2_priority_spec_init()`.  If *pri_spec* is not ``NULL``,
  34     this function will copy its data members.
  35
  36     The ``pri_spec->weight`` must be in [:macro:`NGHTTP2_MIN_WEIGHT`,
  37     :macro:`NGHTTP2_MAX_WEIGHT`], inclusive.  If ``pri_spec->weight`` is
  38     strictly less than :macro:`NGHTTP2_MIN_WEIGHT`, it becomes
  39     :macro:`NGHTTP2_MIN_WEIGHT`.  If it is strictly greater than
  40     :macro:`NGHTTP2_MAX_WEIGHT`, it becomes :macro:`NGHTTP2_MAX_WEIGHT`.
  41
  42     The *nva* is an array of name/value pair :type:`nghttp2_nv` with
  43     *nvlen* elements.  The application is responsible to include
  44     required pseudo-header fields (header field whose name starts with
  45     ":") in *nva* and must place pseudo-headers before regular header
  46     fields.
  47
  48     This function creates copies of all name/value pairs in *nva*.  It
  49     also lower-cases all names in *nva*.  The order of elements in
  50     *nva* is preserved.
  51
  52     The *stream_user_data* is a pointer to an arbitrary data which is
  53     associated to the stream this frame will open.  Therefore it is
  54     only used if this frame opens streams, in other words, it changes
  55     stream state from idle or reserved to open.
  56
  57     This function is low-level in a sense that the application code can
  58     specify flags directly.  For usual HTTP request,
  59     `nghttp2_submit_request()` is useful.
  60
  61     This function returns newly assigned stream ID if it succeeds and
  62     *stream_id* is -1.  Otherwise, this function returns 0 if it
  63     succeeds, or one of the following negative error codes:
  64
  65     :macro:`NGHTTP2_ERR_NOMEM`
  66         Out of memory.
  67     :macro:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
  68         No stream ID is available because maximum stream ID was
  69         reached.
  70     :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
  71         The *stream_id* is 0.
  72
  73     .. warning::
  74
  75       This function returns assigned stream ID if it succeeds and
  76       *stream_id* is -1.  But that stream is not opened yet.  The
  77       application must not submit frame to that stream ID before
  78       :type:`nghttp2_before_frame_send_callback` is called for this
  79       frame.
  80