doc/nghttp2_session_send.rst

   1
   2 nghttp2_session_send
   3 ====================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_session_send(nghttp2_session *session)
  11
  12
  13     Sends pending frames to the remote peer.
  14
  15     This function retrieves the highest prioritized frame from the
  16     outbound queue and sends it to the remote peer.  It does this as
  17     many as possible until the user callback
  18     :type:`nghttp2_send_callback` returns
  19     :macro:`NGHTTP2_ERR_WOULDBLOCK` or the outbound queue becomes empty.
  20     This function calls several callback functions which are passed
  21     when initializing the *session*.  Here is the simple time chart
  22     which tells when each callback is invoked:
  23
  24     1. Get the next frame to send from outbound queue.
  25
  26     2. Prepare transmission of the frame.
  27
  28     3. If the control frame cannot be sent because some preconditions
  29        are not met (e.g., request HEADERS cannot be sent after GOAWAY),
  30        :type:`nghttp2_on_frame_not_send_callback` is invoked.  Abort
  31        the following steps.
  32
  33     4. If the frame is HEADERS, PUSH_PROMISE or DATA,
  34        :type:`nghttp2_select_padding_callback` is invoked.
  35
  36     5. If the frame is request HEADERS, the stream is opened here.
  37
  38     6. :type:`nghttp2_before_frame_send_callback` is invoked.
  39
  40     7. If :macro:`NGHTTP2_ERR_CANCEL` is returned from
  41        :type:`nghttp2_before_frame_send_callback`, the current frame
  42        transmission is canceled, and
  43        :type:`nghttp2_on_frame_not_send_callback` is invoked.  Abort
  44        the following steps.
  45
  46     8. :type:`nghttp2_send_callback` is invoked one or more times to
  47        send the frame.
  48
  49     9. :type:`nghttp2_on_frame_send_callback` is invoked.
  50
  51     10. If the transmission of the frame triggers closure of the
  52         stream, the stream is closed and
  53         :type:`nghttp2_on_stream_close_callback` is invoked.
  54
  55     This function returns 0 if it succeeds, or one of the following
  56     negative error codes:
  57
  58     :macro:`NGHTTP2_ERR_NOMEM`
  59         Out of memory.
  60     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`
  61         The callback function failed.