Function libnghttp2_sys::nghttp2_submit_headers

pub unsafe extern "C" fn nghttp2_submit_headers(
    session: *mut nghttp2_session,
    flags: u8,
    stream_id: i32,
    pri_spec: *const nghttp2_priority_spec,
    nva: *const nghttp2_nv,
    nvlen: usize,
    stream_user_data: *mut c_void
) -> i32

@function

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

• :enum:NGHTTP2_FLAG_END_STREAM

If |flags| includes :enum: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 [:enum:NGHTTP2_MIN_WEIGHT, :enum:NGHTTP2_MAX_WEIGHT], inclusive. If pri_spec->weight is strictly less than :enum:NGHTTP2_MIN_WEIGHT, it becomes :enum:NGHTTP2_MIN_WEIGHT. If it is strictly greater than :enum:NGHTTP2_MAX_WEIGHT, it becomes :enum:NGHTTP2_MAX_WEIGHT.

The |nva| is an array of name/value pair :type: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 :enum:NGHTTP2_NV_FLAG_NO_COPY_NAME and :enum:NGHTTP2_NV_FLAG_NO_COPY_VALUE are set, header field name and value are not copied respectively. With :enum: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 :type:nghttp2_on_frame_send_callback or :type: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:

:enum:NGHTTP2_ERR_NOMEM Out of memory. :enum:NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE No stream ID is available because maximum stream ID was reached. :enum:NGHTTP2_ERR_INVALID_ARGUMENT The |stream_id| is 0; or trying to depend on itself (stream ID equals pri_spec->stream_id). :enum: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. :enum: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 :type:nghttp2_before_frame_send_callback is called for this frame.