Type Definition libnghttp2_sys::nghttp2_on_begin_headers_callback

type nghttp2_on_begin_headers_callback = Option<unsafe extern "C" fn(session: *mut nghttp2_session, frame: *const nghttp2_frame, user_data: *mut c_void) -> c_int>;

@functypedef

Callback function invoked when the reception of header block in HEADERS or PUSH_PROMISE is started. Each header name/value pair will be emitted by :type:nghttp2_on_header_callback.

The frame->hd.flags may not have :enum:NGHTTP2_FLAG_END_HEADERS flag set, which indicates that one or more CONTINUATION frames are involved. But the application does not need to care about that because the header name/value pairs are emitted transparently regardless of CONTINUATION frames.

The server applications probably create an object to store information about new stream if frame->hd.type == NGHTTP2_HEADERS and frame->headers.cat == NGHTTP2_HCAT_REQUEST. If |session| is configured as server side, frame->headers.cat is either NGHTTP2_HCAT_REQUEST containing request headers or NGHTTP2_HCAT_HEADERS containing trailer fields and never get PUSH_PROMISE in this callback.

For the client applications, frame->hd.type is either NGHTTP2_HEADERS or NGHTTP2_PUSH_PROMISE. In case of NGHTTP2_HEADERS, frame->headers.cat == NGHTTP2_HCAT_RESPONSE means that it is the first response headers, but it may be non-final response which is indicated by 1xx status code. In this case, there may be zero or more HEADERS frame with frame->headers.cat == NGHTTP2_HCAT_HEADERS which has non-final response code and finally client gets exactly one HEADERS frame with frame->headers.cat == NGHTTP2_HCAT_HEADERS containing final response headers (non-1xx status code). The trailer fields also has frame->headers.cat == NGHTTP2_HCAT_HEADERS which does not contain any status code.

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 can return :enum:NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE to reset the stream (promised stream if frame is PUSH_PROMISE). For critical errors, it must return :enum:NGHTTP2_ERR_CALLBACK_FAILURE. If the other value is returned, it is treated as if :enum:NGHTTP2_ERR_CALLBACK_FAILURE is returned. If :enum:NGHTTP2_ERR_CALLBACK_FAILURE is returned, nghttp2_session_mem_recv() function will immediately return :enum:NGHTTP2_ERR_CALLBACK_FAILURE.

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