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. :type:`nghttp2_send_callback` is invoked one or more times to
  41        send the frame.
  42
  43     8. :type:`nghttp2_on_frame_send_callback` is invoked.
  44
  45     9. If the transmission of the frame triggers closure of the stream,
  46        the stream is closed and
  47        :type:`nghttp2_on_stream_close_callback` is invoked.
  48
  49     This function returns 0 if it succeeds, or one of the following
  50     negative error codes:
  51
  52     :macro:`NGHTTP2_ERR_NOMEM`
  53         Out of memory.
  54     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`
  55         The callback function failed.