8 *#include <nghttp2/nghttp2.h>*
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)
13 Submits HEADERS frame and optionally one or more DATA frames.
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.
21 The ``pri_spec->weight`` must be in [:macro:`NGHTTP2_MIN_WEIGHT`,
22 :macro:`NGHTTP2_MAX_WEIGHT`], inclusive. If ``pri_spec->weight``
23 is 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
26 :macro:`NGHTTP2_MAX_WEIGHT`.
28 The *nva* is an array of name/value pair :type:`nghttp2_nv` with
29 *nvlen* elements. The application is responsible to include
30 required pseudo-header fields (header field whose name starts with
31 ":") in *nva* and must place pseudo-headers before regular header
34 This function creates copies of all name/value pairs in *nva*. It
35 also lower-cases all names in *nva*. The order of elements in
36 *nva* is preserved. For header fields with
37 :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
38 :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
39 header field name and value are not copied respectively. With
40 :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
41 is responsible to pass header field name in lowercase. The
42 application should maintain the references to them until
43 :type:`nghttp2_on_frame_send_callback` or
44 :type:`nghttp2_on_frame_not_send_callback` is called.
46 HTTP/2 specification has requirement about header fields in the
47 request HEADERS. See the specification for more details.
49 If *data_prd* is not ``NULL``, it provides data which will be sent
50 in subsequent DATA frames. In this case, a method that allows
51 request message bodies
52 (https://tools.ietf.org/html/rfc7231#section-4) must be specified
53 with ``:method`` key in *nva* (e.g. ``POST``). This function does
54 not take ownership of the *data_prd*. The function copies the
55 members of the *data_prd*. If *data_prd* is ``NULL``, HEADERS have
56 END_STREAM set. The *stream_user_data* is data associated to the
57 stream opened by this request and can be an arbitrary pointer,
58 which can be retrieved later by
59 `nghttp2_session_get_stream_user_data()`.
61 This function returns assigned stream ID if it succeeds, or one of
62 the following negative error codes:
64 :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM`
66 :macro:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
67 No stream ID is available because maximum stream ID was
69 :macro:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
70 Trying to depend on itself (new stream ID equals
71 ``pri_spec->stream_id``).
72 :macro:`nghttp2_error.NGHTTP2_ERR_PROTO`
73 The *session* is server session.
77 This function returns assigned stream ID if it succeeds. But
78 that stream is not created yet. The application must not submit
79 frame to that stream ID before
80 :type:`nghttp2_before_frame_send_callback` is called for this
81 frame. This means `nghttp2_session_get_stream_user_data()` does
82 not work before the callback. But
83 `nghttp2_session_set_stream_user_data()` handles this situation
84 specially, and it can set data to a stream during this period.