doc/nghttp2_session_recv.rst

   1
   2 nghttp2_session_recv
   3 ====================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_session_recv(nghttp2_session *session)
  11
  12
  13     Receives frames from the remote peer.
  14
  15     This function receives as many frames as possible until the user
  16     callback :type:`nghttp2_recv_callback` returns
  17     :macro:`NGHTTP2_ERR_WOULDBLOCK`.  This function calls several
  18     callback functions which are passed when initializing the
  19     *session*.  Here is the simple time chart which tells when each
  20     callback is invoked:
  21
  22     1. :type:`nghttp2_recv_callback` is invoked one or more times to
  23        receive frame header.
  24
  25     2. When frame header is received,
  26        :type:`nghttp2_on_begin_frame_callback` is invoked.
  27
  28     3. If the frame is DATA frame:
  29
  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.
  33
  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.
  38
  39     4. If the frame is the control frame:
  40
  41        1. :type:`nghttp2_recv_callback` is invoked one or more times to
  42           receive whole frame.
  43
  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.
  55
  56        3. If the received frame is unpacked but is interpreted as
  57           invalid, :type:`nghttp2_on_invalid_frame_recv_callback` is
  58           invoked.
  59
  60     This function returns 0 if it succeeds, or one of the following
  61     negative error codes:
  62
  63     :macro:`NGHTTP2_ERR_EOF`
  64         The remote peer did shutdown on the connection.
  65     :macro:`NGHTTP2_ERR_NOMEM`
  66         Out of memory.
  67     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`
  68         The callback function failed.
  69     :macro:`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
  73         nonzero value.
  74     :macro:`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.