doc/nghttp2_submit_trailer.rst

   1
   2 nghttp2_submit_trailer
   3 ======================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_submit_trailer(nghttp2_session *session, int32_t stream_id, const nghttp2_nv *nva, size_t nvlen)
  11
  12
  13     Submits trailer fields HEADERS against the stream *stream_id*.
  14
  15     The *nva* is an array of name/value pair :type:`nghttp2_nv` with
  16     *nvlen* elements.  The application must not include pseudo-header
  17     fields (headers whose names starts with ":") in *nva*.
  18
  19     This function creates copies of all name/value pairs in *nva*.  It
  20     also lower-cases all names in *nva*.  The order of elements in
  21     *nva* is preserved.  For header fields with
  22     :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
  23     :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
  24     header field name and value are not copied respectively.  With
  25     :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
  26     is responsible to pass header field name in lowercase.  The
  27     application should maintain the references to them until
  28     :type:`nghttp2_on_frame_send_callback` or
  29     :type:`nghttp2_on_frame_not_send_callback` is called.
  30
  31     For server, trailer fields must follow response HEADERS or response
  32     DATA without END_STREAM flat set.  The library does not enforce
  33     this requirement, and applications should do this for themselves.
  34     If `nghttp2_submit_trailer()` is called before any response HEADERS
  35     submission (usually by `nghttp2_submit_response()`), the content of
  36     *nva* will be sent as response headers, which will result in error.
  37
  38     This function has the same effect with `nghttp2_submit_headers()`,
  39     with flags = :macro:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` and both
  40     pri_spec and stream_user_data to NULL.
  41
  42     To submit trailer fields after `nghttp2_submit_response()` is
  43     called, the application has to specify
  44     :type:`nghttp2_data_provider` to `nghttp2_submit_response()`.
  45     Inside of :type:`nghttp2_data_source_read_callback`, when setting
  46     :macro:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF`, also set
  47     :macro:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_END_STREAM`.  After
  48     that, the application can send trailer fields using
  49     `nghttp2_submit_trailer()`.  `nghttp2_submit_trailer()` can be used
  50     inside :type:`nghttp2_data_source_read_callback`.
  51
  52     This function returns 0 if it succeeds and *stream_id* is -1.
  53     Otherwise, this function returns 0 if it succeeds, or one of the
  54     following negative error codes:
  55
  56     :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM`
  57         Out of memory.
  58     :macro:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
  59         The *stream_id* is 0.