doc/nghttp2_submit_data.rst

   1
   2 nghttp2_submit_data
   3 ===================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_submit_data(nghttp2_session *session, uint8_t flags, int32_t stream_id, const nghttp2_data_provider *data_prd)
  11
  12
  13     Submits one or more DATA frames to the stream *stream_id*.  The
  14     data to be sent are provided by *data_prd*.  If *flags* contains
  15     :macro:`NGHTTP2_FLAG_END_STREAM`, the last DATA frame has END_STREAM
  16     flag set.
  17
  18     This function does not take ownership of the *data_prd*.  The
  19     function copies the members of the *data_prd*.
  20
  21     This function returns 0 if it succeeds, or one of the following
  22     negative error codes:
  23
  24     :macro:`NGHTTP2_ERR_NOMEM`
  25         Out of memory.
  26     :macro:`NGHTTP2_ERR_DATA_EXIST`
  27         DATA or HEADERS has been already submitted and not fully
  28         processed yet.
  29     :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
  30         The *stream_id* is 0.
  31     :macro:`NGHTTP2_ERR_STREAM_CLOSED`
  32         The stream was already closed; or the *stream_id* is invalid.
  33
  34     .. note::
  35
  36       Currently, only one DATA or HEADERS is allowed for a stream at a
  37       time.  Submitting these frames more than once before first DATA
  38       or HEADERS is finished results in :macro:`NGHTTP2_ERR_DATA_EXIST`
  39       error code.  The earliest callback which tells that previous
  40       frame is done is :type:`nghttp2_on_frame_send_callback`.  In side
  41       that callback, new data can be submitted using
  42       `nghttp2_submit_data()`.  Of course, all data except for last one
  43       must not have :macro:`NGHTTP2_FLAG_END_STREAM` flag set in
  44       *flags*.  This sounds a bit complicated, and we recommend to use
  45       `nghttp2_submit_request()` and `nghttp2_submit_response()` to
  46       avoid this cascading issue.  The experience shows that for HTTP
  47       use, these two functions are enough to implement both client and
  48       server.