8 *#include <nghttp2/nghttp2.h>*
10 .. function:: int nghttp2_session_recv(nghttp2_session *session)
13 Receives frames from the remote peer.
15 This function receives as many frames as possible until the user
16 callback :type:`nghttp2_recv_callback` returns
17 :macro:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. This function calls
18 several callback functions which are passed when initializing the
19 *session*. Here is the simple time chart which tells when each
22 1. :type:`nghttp2_recv_callback` is invoked one or more times to
25 2. When frame header is received,
26 :type:`nghttp2_on_begin_frame_callback` is invoked.
28 3. If the frame is DATA frame:
30 1. :type:`nghttp2_recv_callback` is invoked to receive DATA
31 payload. For each chunk of data,
32 :type:`nghttp2_on_data_chunk_recv_callback` is invoked.
34 2. If one DATA frame is completely received,
35 :type:`nghttp2_on_frame_recv_callback` is invoked. If the
36 reception of the frame triggers the closure of the stream,
37 :type:`nghttp2_on_stream_close_callback` is invoked.
39 4. If the frame is the control frame:
41 1. :type:`nghttp2_recv_callback` is invoked one or more times to
44 2. If the received frame is valid, then following actions are
45 taken. If the frame is either HEADERS or PUSH_PROMISE,
46 :type:`nghttp2_on_begin_headers_callback` is invoked. Then
47 :type:`nghttp2_on_header_callback` is invoked for each header
48 name/value pair. For invalid header field,
49 :type:`nghttp2_on_invalid_header_callback` is called. After
50 all name/value pairs are emitted successfully,
51 :type:`nghttp2_on_frame_recv_callback` is invoked. For other
52 frames, :type:`nghttp2_on_frame_recv_callback` is invoked.
53 If the reception of the frame triggers the closure of the
54 stream, :type:`nghttp2_on_stream_close_callback` is invoked.
56 3. If the received frame is unpacked but is interpreted as
57 invalid, :type:`nghttp2_on_invalid_frame_recv_callback` is
60 This function returns 0 if it succeeds, or one of the following
63 :macro:`nghttp2_error.NGHTTP2_ERR_EOF`
64 The remote peer did shutdown on the connection.
65 :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM`
67 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`
68 The callback function failed.
69 :macro:`nghttp2_error.NGHTTP2_ERR_BAD_CLIENT_MAGIC`
70 Invalid client magic was detected. This error only returns
71 when *session* was configured as server and
72 `nghttp2_option_set_no_recv_client_magic()` is not used with
74 :macro:`nghttp2_error.NGHTTP2_ERR_FLOODED`
75 Flooding was detected in this HTTP/2 session, and it must be
76 closed. This is most likely caused by misbehaviour of peer.