nghttp2_submit_request2

Synopsis

#include <nghttp2/nghttp2.h>

int32_t nghttp2_submit_request2(nghttp2_session *session, const nghttp2_priority_spec *pri_spec, const nghttp2_nv *nva, size_t nvlen, const nghttp2_data_provider2 *data_prd, void *stream_user_data)

Submits HEADERS frame and optionally one or more DATA frames.

The pri_spec is a deprecated 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. In the future release after the end of 2024, this function will ignore pri_spec and behave as if NULL is given.

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.

If nghttp2_settings_id.NGHTTP2_SETTINGS_NO_RFC7540_PRIORITIES of value of 1 is received by a remote endpoint, pri_spec is ignored, and treated as if NULL is specified.

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.

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:

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

Trying to depend on itself (new stream ID equals pri_spec->stream_id).

nghttp2_error.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 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.