Function libnghttp2_sys::nghttp2_submit_request

pub unsafe extern "C" fn nghttp2_submit_request(
    session: *mut nghttp2_session, 
    pri_spec: *const nghttp2_priority_spec, 
    nva: *const nghttp2_nv, 
    nvlen: usize, 
    data_prd: *const nghttp2_data_provider, 
    stream_user_data: *mut c_void
) -> i32

@function

Submits HEADERS frame and optionally one or more DATA frames.

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.

HTTP/2 specification has requirement about header fields in the request HEADERS. See the specification for more details.

If |data_prd| is not NULL, it provides data which will be sent in subsequent DATA frames. In this case, a method that allows request message bodies (https://tools.ietf.org/html/rfc7231#section-4) must be specified with :method key in |nva| (e.g. POST). This function does not take ownership of the |data_prd|. The function copies the members of the |data_prd|. If |data_prd| is NULL, HEADERS have END_STREAM set. The |stream_user_data| is data associated to the stream opened by this request and can be an arbitrary pointer, which can be retrieved later by nghttp2_session_get_stream_user_data().

This function returns assigned stream ID 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 Trying to depend on itself (new stream ID equals pri_spec->stream_id). :enum:NGHTTP2_ERR_PROTO The |session| is server session.

.. warning::

This function returns assigned stream ID if it succeeds. But that stream is not created yet. The application must not submit frame to that stream ID before :type:nghttp2_before_frame_send_callback is called for this frame. This means nghttp2_session_get_stream_user_data() does not work before the callback. But nghttp2_session_set_stream_user_data() handles this situation specially, and it can set data to a stream during this period.