1 2nghttp2_submit_headers 3====================== 4 5Synopsis 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.NGHTTP2_FLAG_END_STREAM` 17 18 If *flags* includes :macro:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`, 19 this frame has 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`` 38 is 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. For header fields with 51 :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and 52 :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, 53 header field name and value are not copied respectively. With 54 :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application 55 is responsible to pass header field name in lowercase. The 56 application should maintain the references to them until 57 :type:`nghttp2_on_frame_send_callback` or 58 :type:`nghttp2_on_frame_not_send_callback` is called. 59 60 The *stream_user_data* is a pointer to an arbitrary data which is 61 associated to the stream this frame will open. Therefore it is 62 only used if this frame opens streams, in other words, it changes 63 stream state from idle or reserved to open. 64 65 This function is low-level in a sense that the application code can 66 specify flags directly. For usual HTTP request, 67 `nghttp2_submit_request()` is useful. Likewise, for HTTP response, 68 prefer `nghttp2_submit_response()`. 69 70 This function returns newly assigned stream ID if it succeeds and 71 *stream_id* is -1. Otherwise, this function returns 0 if it 72 succeeds, or one of the following negative error codes: 73 74 :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM` 75 Out of memory. 76 :macro:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE` 77 No stream ID is available because maximum stream ID was 78 reached. 79 :macro:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT` 80 The *stream_id* is 0; or trying to depend on itself (stream ID 81 equals ``pri_spec->stream_id``). 82 :macro:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST` 83 DATA or HEADERS has been already submitted and not fully 84 processed yet. This happens if stream denoted by *stream_id* 85 is in reserved state. 86 :macro:`nghttp2_error.NGHTTP2_ERR_PROTO` 87 The *stream_id* is -1, and *session* is server session. 88 89 .. warning:: 90 91 This function returns assigned stream ID if it succeeds and 92 *stream_id* is -1. But that stream is not opened yet. The 93 application must not submit frame to that stream ID before 94 :type:`nghttp2_before_frame_send_callback` is called for this 95 frame. 96 97