nghttp2_session_recv

Synopsis

#include <nghttp2/nghttp2.h>

int nghttp2_session_recv(nghttp2_session *session)

Receives frames from the remote peer.

This function receives as many frames as possible until the user callback nghttp2_recv_callback returns NGHTTP2_ERR_WOULDBLOCK. This function calls several callback functions which are passed when initializing the session. Here is the simple time chart which tells when each callback is invoked:

  1. nghttp2_recv_callback is invoked one or more times to receive frame header.
  2. When frame header is received, nghttp2_on_begin_frame_callback is invoked.
  3. If the frame is DATA frame:
    1. nghttp2_recv_callback is invoked to receive DATA payload. For each chunk of data, nghttp2_on_data_chunk_recv_callback is invoked.
    2. If one DATA frame is completely received, nghttp2_on_frame_recv_callback is invoked. If the reception of the frame triggers the closure of the stream, nghttp2_on_stream_close_callback is invoked.
  4. If the frame is the control frame:
    1. nghttp2_recv_callback is invoked one or more times to receive whole frame.
    2. If the received frame is valid, then following actions are taken. If the frame is either HEADERS or PUSH_PROMISE, nghttp2_on_begin_headers_callback is invoked. Then nghttp2_on_header_callback is invoked for each header name/value pair. For invalid header field, nghttp2_on_invalid_header_callback is called. After all name/value pairs are emitted successfully, nghttp2_on_frame_recv_callback is invoked. For other frames, nghttp2_on_frame_recv_callback is invoked. If the reception of the frame triggers the closure of the stream, nghttp2_on_stream_close_callback is invoked.
    3. If the received frame is unpacked but is interpreted as invalid, nghttp2_on_invalid_frame_recv_callback is invoked.

This function returns 0 if it succeeds, or one of the following negative error codes:

NGHTTP2_ERR_EOF
The remote peer did shutdown on the connection.
NGHTTP2_ERR_NOMEM
Out of memory.
NGHTTP2_ERR_CALLBACK_FAILURE
The callback function failed.
NGHTTP2_ERR_BAD_CLIENT_MAGIC
Invalid client magic was detected. This error only returns when session was configured as server and nghttp2_option_set_no_recv_client_magic() is not used with nonzero value.
NGHTTP2_ERR_FLOODED
Flooding was detected in this HTTP/2 session, and it must be closed. This is most likely caused by misbehaviour of peer.