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.  After all name/value pairs are emitted
  49           successfully, :type:`nghttp2_on_frame_recv_callback` is
  50           invoked.  For other frames,
  51           :type:`nghttp2_on_frame_recv_callback` is invoked.  If the
  52           reception of the frame triggers the closure of the stream,
  53           :type:`nghttp2_on_stream_close_callback` is invoked.
  54
  55        3. If the received frame is unpacked but is interpreted as
  56           invalid, :type:`nghttp2_on_invalid_frame_recv_callback` is
  57           invoked.
  58
  59     This function returns 0 if it succeeds, or one of the following
  60     negative error codes:
  61
  62     :macro:`NGHTTP2_ERR_EOF`
  63         The remote peer did shutdown on the connection.
  64     :macro:`NGHTTP2_ERR_NOMEM`
  65         Out of memory.
  66     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`
  67         The callback function failed.
  68     :macro:`NGHTTP2_ERR_BAD_CLIENT_MAGIC`
  69         Invalid client magic was detected.  This error only returns
  70         when *session* was configured as server and
  71         `nghttp2_option_set_no_recv_client_magic()` is not used with
  72         nonzero value.