doc/nghttp2_submit_request.rst

   1
   2 nghttp2_submit_request
   3 ======================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int32_t nghttp2_submit_request( nghttp2_session *session, const nghttp2_priority_spec *pri_spec, const nghttp2_nv *nva, size_t nvlen, const nghttp2_data_provider *data_prd, void *stream_user_data)
  11
  12
  13     Submits HEADERS frame and optionally one or more DATA frames.
  14
  15     The *pri_spec* is priority specification of this request.  ``NULL``
  16     means the default priority (see
  17     `nghttp2_priority_spec_default_init()`).  To specify the priority,
  18     use `nghttp2_priority_spec_init()`.  If *pri_spec* is not ``NULL``,
  19     this function will copy its data members.
  20
  21     The ``pri_spec->weight`` must be in [:macro:`NGHTTP2_MIN_WEIGHT`,
  22     :macro:`NGHTTP2_MAX_WEIGHT`], inclusive.  If ``pri_spec->weight`` is
  23     strictly less than :macro:`NGHTTP2_MIN_WEIGHT`, it becomes
  24     :macro:`NGHTTP2_MIN_WEIGHT`.  If it is strictly greater than
  25     :macro:`NGHTTP2_MAX_WEIGHT`, it becomes :macro:`NGHTTP2_MAX_WEIGHT`.
  26
  27     The *nva* is an array of name/value pair :type:`nghttp2_nv` with
  28     *nvlen* elements.  The application is responsible to include
  29     required pseudo-header fields (header field whose name starts with
  30     ":") in *nva* and must place pseudo-headers before regular header
  31     fields.
  32
  33     This function creates copies of all name/value pairs in *nva*.  It
  34     also lower-cases all names in *nva*.  The order of elements in
  35     *nva* is preserved.  For header fields with
  36     :macro:`NGHTTP2_NV_FLAG_NO_COPY_NAME` and
  37     :macro:`NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, header field name
  38     and value are not copied respectively.  With
  39     :macro:`NGHTTP2_NV_FLAG_NO_COPY_NAME`, application is responsible to
  40     pass header field name in lowercase.  The application should
  41     maintain the references to them until
  42     :type:`nghttp2_on_frame_send_callback` or
  43     :type:`nghttp2_on_frame_not_send_callback` is called.
  44
  45     HTTP/2 specification has requirement about header fields in the
  46     request HEADERS.  See the specification for more details.
  47
  48     If *data_prd* is not ``NULL``, it provides data which will be sent
  49     in subsequent DATA frames.  In this case, a method that allows
  50     request message bodies
  51     (https://tools.ietf.org/html/rfc7231#section-4) must be specified
  52     with ``:method`` key in *nva* (e.g. ``POST``).  This function does
  53     not take ownership of the *data_prd*.  The function copies the
  54     members of the *data_prd*.  If *data_prd* is ``NULL``, HEADERS have
  55     END_STREAM set.  The *stream_user_data* is data associated to the
  56     stream opened by this request and can be an arbitrary pointer,
  57     which can be retrieved later by
  58     `nghttp2_session_get_stream_user_data()`.
  59
  60     This function returns assigned stream ID if it succeeds, or one of
  61     the following negative error codes:
  62
  63     :macro:`NGHTTP2_ERR_NOMEM`
  64         Out of memory.
  65     :macro:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
  66         No stream ID is available because maximum stream ID was
  67         reached.
  68     :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
  69         Trying to depend on itself (new stream ID equals
  70         ``pri_spec->stream_id``).
  71     :macro:`NGHTTP2_ERR_PROTO`
  72         The *session* is server session.
  73
  74     .. warning::
  75
  76       This function returns assigned stream ID if it succeeds.  But
  77       that stream is not created yet.  The application must not submit
  78       frame to that stream ID before
  79       :type:`nghttp2_before_frame_send_callback` is called for this
  80       frame.  This means `nghttp2_session_get_stream_user_data()` does
  81       not work before the callback.  But
  82       `nghttp2_session_set_stream_user_data()` handles this situation
  83       specially, and it can set data to a stream during this period.
  84