Type Definition libnghttp2_sys::nghttp2_data_source_read_callback

pub type nghttp2_data_source_read_callback = Option<unsafe extern "C" fn(session: *mut nghttp2_session, stream_id: i32, buf: *mut u8, length: usize, data_flags: *mut u32, source: *mut nghttp2_data_source, user_data: *mut c_void) -> isize>;

@functypedef

Callback function invoked when the library wants to read data from the |source|. The read data is sent in the stream |stream_id|. The implementation of this function must read at most |length| bytes of data from |source| (or possibly other places) and store them in |buf| and return number of data stored in |buf|. If EOF is reached, set :enum:NGHTTP2_DATA_FLAG_EOF flag in |*data_flags|.

Sometime it is desirable to avoid copying data into |buf| and let application to send data directly. To achieve this, set :enum:NGHTTP2_DATA_FLAG_NO_COPY to |*data_flags| (and possibly other flags, just like when we do copy), and return the number of bytes to send without copying data into |buf|. The library, seeing :enum:NGHTTP2_DATA_FLAG_NO_COPY, will invoke :type:nghttp2_send_data_callback. The application must send complete DATA frame in that callback.

If this callback is set by nghttp2_submit_request(), nghttp2_submit_response() or nghttp2_submit_headers() and nghttp2_submit_data() with flag parameter :enum:NGHTTP2_FLAG_END_STREAM set, and :enum:NGHTTP2_DATA_FLAG_EOF flag is set to |*data_flags|, DATA frame will have END_STREAM flag set. Usually, this is expected behaviour and all are fine. One exception is send trailer fields. You cannot send trailer fields after sending frame with END_STREAM set. To avoid this problem, one can set :enum:NGHTTP2_DATA_FLAG_NO_END_STREAM along with :enum:NGHTTP2_DATA_FLAG_EOF to signal the library not to set END_STREAM in DATA frame. Then application can use nghttp2_submit_trailer() to send trailer fields. nghttp2_submit_trailer() can be called inside this callback.

If the application wants to postpone DATA frames (e.g., asynchronous I/O, or reading data blocks for long time), it is achieved by returning :enum:NGHTTP2_ERR_DEFERRED without reading any data in this invocation. The library removes DATA frame from the outgoing queue temporarily. To move back deferred DATA frame to outgoing queue, call nghttp2_session_resume_data().

By default, |length| is limited to 16KiB at maximum. If peer allows larger frames, application can enlarge transmission buffer size. See :type:nghttp2_data_source_read_length_callback for more details.

If the application just wants to return from nghttp2_session_send() or nghttp2_session_mem_send() without sending anything, return :enum:NGHTTP2_ERR_PAUSE.

In case of error, there are 2 choices. Returning :enum:NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE will close the stream by issuing RST_STREAM with :enum:NGHTTP2_INTERNAL_ERROR. 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. Returning :enum:NGHTTP2_ERR_CALLBACK_FAILURE will signal the entire session failure.