# nghttp2_submit_headers

## Synopsis

#include <nghttp2/nghttp2.h>

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)

  Submits HEADERS frame. The flags is bitwise OR of the following values:

  - `nghttp2_flag.NGHTTP2_FLAG_END_STREAM`

  If flags includes `nghttp2_flag.NGHTTP2_FLAG_END_STREAM`, this frame has END_STREAM flag set.

  The library handles the CONTINUATION frame internally and it correctly sets END_HEADERS to the last sequence of the PUSH_PROMISE or CONTINUATION frame.

  If the stream_id is -1, this frame is assumed as request (i.e., request HEADERS frame which opens new stream). In this case, the assigned stream ID will be returned. Otherwise, specify stream ID in stream_id.

  The pri_spec is priority specification of this request. `NULL` means the default priority (see `nghttp2_priority_spec_default_init()`). To specify the priority, use `nghttp2_priority_spec_init()`. If pri_spec is not `NULL`, this function will copy its data members.

  The `pri_spec->weight` must be in [`NGHTTP2_MIN_WEIGHT`, `NGHTTP2_MAX_WEIGHT`], inclusive. If `pri_spec->weight` is strictly less than `NGHTTP2_MIN_WEIGHT`, it becomes `NGHTTP2_MIN_WEIGHT`. If it is strictly greater than `NGHTTP2_MAX_WEIGHT`, it becomes `NGHTTP2_MAX_WEIGHT`.

  The nva is an array of name/value pair `nghttp2_nv` with nvlen elements. The application is responsible to include required pseudo-header fields (header field whose name starts with “:”) in nva and must place pseudo-headers before regular header fields.

  This function creates copies of all name/value pairs in nva. It also lower-cases all names in nva. The order of elements in nva is preserved. For header fields with `nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and `nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set, header field name and value are not copied respectively. With `nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application is responsible to pass header field name in lowercase. The application should maintain the references to them until `nghttp2_on_frame_send_callback` or `nghttp2_on_frame_not_send_callback` is called.

  The stream_user_data is a pointer to an arbitrary data which is associated to the stream this frame will open. Therefore it is only used if this frame opens streams, in other words, it changes stream state from idle or reserved to open.

  This function is low-level in a sense that the application code can specify flags directly. For usual HTTP request, `nghttp2_submit_request()` is useful. Likewise, for HTTP response, prefer `nghttp2_submit_response()`.

  This function returns newly assigned stream ID if it succeeds and stream_id is -1. Otherwise, this function returns 0 if it succeeds, or one of the following negative error codes:

  `nghttp2_error.NGHTTP2_ERR_NOMEM`

    Out of memory.

  `nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`

    No stream ID is available because maximum stream ID was reached.

  `nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`

    The stream_id is 0; or trying to depend on itself (stream ID equals `pri_spec->stream_id`).

  `nghttp2_error.NGHTTP2_ERR_DATA_EXIST`

    DATA or HEADERS has been already submitted and not fully processed yet. This happens if stream denoted by stream_id is in reserved state.

  `nghttp2_error.NGHTTP2_ERR_PROTO`

    The stream_id is -1, and session is server session.

  Warning

  This function returns assigned stream ID if it succeeds and stream_id is -1. But that stream is not opened yet. The application must not submit frame to that stream ID before `nghttp2_before_frame_send_callback` is called for this frame.