1 2nghttp2_submit_request 3====================== 4 5Synopsis 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`` 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`. 27 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 32 fields. 33 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. 45 46 HTTP/2 specification has requirement about header fields in the 47 request HEADERS. See the specification for more details. 48 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()`. 60 61 This function returns assigned stream ID if it succeeds, or one of 62 the following negative error codes: 63 64 :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM` 65 Out of memory. 66 :macro:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE` 67 No stream ID is available because maximum stream ID was 68 reached. 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. 74 75 .. warning:: 76 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. 85 86