first commit

nghttp2/doc/nghttp2_session_recv.rst

@@ -0,0 +1,76 @@
+
+nghttp2_session_recv
+====================
+
+Synopsis
+--------
+
+*#include <nghttp2/nghttp2.h>*
+
+.. function:: 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 :type:`nghttp2_recv_callback` returns
+    :macro:`nghttp2_error.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. :type:`nghttp2_recv_callback` is invoked one or more times to
+       receive frame header.
+    
+    2. When frame header is received,
+       :type:`nghttp2_on_begin_frame_callback` is invoked.
+    
+    3. If the frame is DATA frame:
+    
+       1. :type:`nghttp2_recv_callback` is invoked to receive DATA
+          payload. For each chunk of data,
+          :type:`nghttp2_on_data_chunk_recv_callback` is invoked.
+    
+       2. If one DATA frame is completely received,
+          :type:`nghttp2_on_frame_recv_callback` is invoked.  If the
+          reception of the frame triggers the closure of the stream,
+          :type:`nghttp2_on_stream_close_callback` is invoked.
+    
+    4. If the frame is the control frame:
+    
+       1. :type:`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,
+          :type:`nghttp2_on_begin_headers_callback` is invoked.  Then
+          :type:`nghttp2_on_header_callback` is invoked for each header
+          name/value pair.  For invalid header field,
+          :type:`nghttp2_on_invalid_header_callback` is called.  After
+          all name/value pairs are emitted successfully,
+          :type:`nghttp2_on_frame_recv_callback` is invoked.  For other
+          frames, :type:`nghttp2_on_frame_recv_callback` is invoked.
+          If the reception of the frame triggers the closure of the
+          stream, :type:`nghttp2_on_stream_close_callback` is invoked.
+    
+       3. If the received frame is unpacked but is interpreted as
+          invalid, :type:`nghttp2_on_invalid_frame_recv_callback` is
+          invoked.
+    
+    This function returns 0 if it succeeds, or one of the following
+    negative error codes:
+    
+    :macro:`nghttp2_error.NGHTTP2_ERR_EOF`
+        The remote peer did shutdown on the connection.
+    :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM`
+        Out of memory.
+    :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`
+        The callback function failed.
+    :macro:`nghttp2_error.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.
+    :macro:`nghttp2_error.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.