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 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 is responsible not to include
  17     required pseudo-header fields (header field whose name starts with
  18     ":") in *nva*.
  19
  20     This function creates copies of all name/value pairs in *nva*.  It
  21     also lower-cases all names in *nva*.  The order of elements in
  22     *nva* is preserved.
  23
  24     For server, trailer must be followed by response HEADERS or
  25     response DATA.  The library does not check that response HEADERS
  26     has already sent and if `nghttp2_submit_trailer()` is called before
  27     any response HEADERS submission (usually by
  28     `nghttp2_submit_response()`), the content of *nva* will be sent as
  29     reponse headers, which will result in error.
  30
  31     This function has the same effect with `nghttp2_submit_headers()`,
  32     with flags = :macro:`NGHTTP2_FLAG_END_HEADERS` and both pri_spec and
  33     stream_user_data to NULL.
  34
  35     To submit trailer after `nghttp2_submit_response()` is called, the
  36     application has to specify :type:`nghttp2_data_provider` to
  37     `nghttp2_submit_response()`.  In side
  38     :type:`nghttp2_data_source_read_callback`, when setting
  39     :macro:`NGHTTP2_DATA_FLAG_EOF`, also set
  40     :macro:`NGHTTP2_DATA_FLAG_NO_END_STREAM`.  After that, the
  41     application can send trailer using `nghttp2_submit_trailer()`.
  42     `nghttp2_submit_trailer()` can be used inside
  43     :type:`nghttp2_data_source_read_callback`.
  44
  45     This function returns 0 if it succeeds and *stream_id* is -1.
  46     Otherwise, this function returns 0 if it succeeds, or one of the
  47     following negative error codes:
  48
  49     :macro:`NGHTTP2_ERR_NOMEM`
  50         Out of memory.
  51     :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
  52         The *stream_id* is 0.