Type Definition libnghttp2_sys::nghttp2_on_header_callback

pub type nghttp2_on_header_callback = Option<unsafe extern "C" fn(session: *mut nghttp2_session, frame: *const nghttp2_frame, name: *const u8, namelen: usize, value: *const u8, valuelen: usize, flags: u8, user_data: *mut c_void) -> c_int>;

@functypedef

Callback function invoked when a header name/value pair is received for the |frame|. The |name| of length |namelen| is header name. The |value| of length |valuelen| is header value. The |flags| is bitwise OR of one or more of :type:nghttp2_nv_flag.

If :enum:NGHTTP2_NV_FLAG_NO_INDEX is set in |flags|, the receiver must not index this name/value pair when forwarding it to the next hop. More specifically, “Literal Header Field never Indexed” representation must be used in HPACK encoding.

When this callback is invoked, frame->hd.type is either :enum:NGHTTP2_HEADERS or :enum:NGHTTP2_PUSH_PROMISE. After all header name/value pairs are processed with this callback, and no error has been detected, :type:nghttp2_on_frame_recv_callback will be invoked. If there is an error in decompression, :type:nghttp2_on_frame_recv_callback for the |frame| will not be invoked.

Both |name| and |value| are guaranteed to be NULL-terminated. The |namelen| and |valuelen| do not include terminal NULL. If nghttp2_option_set_no_http_messaging() is used with nonzero value, NULL character may be included in |name| or |value| before terminating NULL.

Please note that unless nghttp2_option_set_no_http_messaging() is used, nghttp2 library does perform validation against the |name| and the |value| using nghttp2_check_header_name() and nghttp2_check_header_value(). In addition to this, nghttp2 performs validation based on HTTP Messaging rule, which is briefly explained in :ref:http-messaging section.

If the application uses nghttp2_session_mem_recv(), it can return :enum:NGHTTP2_ERR_PAUSE to make nghttp2_session_mem_recv() return without processing further input bytes. The memory pointed by |frame|, |name| and |value| parameters are retained until nghttp2_session_mem_recv() or nghttp2_session_recv() is called. The application must retain the input bytes which was used to produce these parameters, because it may refer to the memory region included in the input bytes.

Returning :enum:NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE will close the stream (promised stream if frame is PUSH_PROMISE) by issuing RST_STREAM with :enum:NGHTTP2_INTERNAL_ERROR. In this case, :type:nghttp2_on_header_callback and :type:nghttp2_on_frame_recv_callback will not be invoked. If a different error code is desirable, use nghttp2_submit_rst_stream() with a desired error code and then return :enum:NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE. Again, use frame->push_promise.promised_stream_id as stream_id parameter in nghttp2_submit_rst_stream() if frame is PUSH_PROMISE.

The implementation of this function must return 0 if it succeeds. It may return :enum:NGHTTP2_ERR_PAUSE or :enum:NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE. For other critical failures, it must return :enum:NGHTTP2_ERR_CALLBACK_FAILURE. If the other nonzero value is returned, it is treated as :enum:NGHTTP2_ERR_CALLBACK_FAILURE. If :enum:NGHTTP2_ERR_CALLBACK_FAILURE is returned, nghttp2_session_recv() and nghttp2_session_mem_recv() functions immediately return :enum:NGHTTP2_ERR_CALLBACK_FAILURE.

To set this callback to :type:nghttp2_session_callbacks, use nghttp2_session_callbacks_set_on_header_callback().

.. warning::

Application should properly limit the total buffer size to store incoming header fields. Without it, peer may send large number of header fields or large header fields to cause out of memory in local endpoint. Due to how HPACK works, peer can do this effectively without using much memory on their own.