doc/nghttp2_submit_response.rst

   1
   2 nghttp2_submit_response
   3 =======================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_submit_response(nghttp2_session *session, int32_t stream_id, const nghttp2_nv *nva, size_t nvlen, const nghttp2_data_provider *data_prd)
  11
  12
  13     Submits response HEADERS frame and optionally one or more DATA
  14     frames against the stream *stream_id*.
  15
  16     The *nva* is an array of name/value pair :type:`nghttp2_nv` with
  17     *nvlen* elements.  The application is responsible to include
  18     required pseudo-header fields (header field whose name starts with
  19     ":") in *nva* and must place pseudo-headers before regular header
  20     fields.
  21
  22     This function creates copies of all name/value pairs in *nva*.  It
  23     also lower-cases all names in *nva*.  The order of elements in
  24     *nva* is preserved.  For header fields with
  25     :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
  26     :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
  27     header field name and value are not copied respectively.  With
  28     :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
  29     is responsible to pass header field name in lowercase.  The
  30     application should maintain the references to them until
  31     :type:`nghttp2_on_frame_send_callback` or
  32     :type:`nghttp2_on_frame_not_send_callback` is called.
  33
  34     HTTP/2 specification has requirement about header fields in the
  35     response HEADERS.  See the specification for more details.
  36
  37     If *data_prd* is not ``NULL``, it provides data which will be sent
  38     in subsequent DATA frames.  This function does not take ownership
  39     of the *data_prd*.  The function copies the members of the
  40     *data_prd*.  If *data_prd* is ``NULL``, HEADERS will have
  41     END_STREAM flag set.
  42
  43     This method can be used as normal HTTP response and push response.
  44     When pushing a resource using this function, the *session* must be
  45     configured using `nghttp2_session_server_new()` or its variants and
  46     the target stream denoted by the *stream_id* must be reserved using
  47     `nghttp2_submit_push_promise()`.
  48
  49     To send non-final response headers (e.g., HTTP status 101), don't
  50     use this function because this function half-closes the outbound
  51     stream.  Instead, use `nghttp2_submit_headers()` for this purpose.
  52
  53     This function returns 0 if it succeeds, or one of the following
  54     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.
  60     :macro:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST`
  61         DATA or HEADERS has been already submitted and not fully
  62         processed yet.  Normally, this does not happen, but when
  63         application wrongly calls `nghttp2_submit_response()` twice,
  64         this may happen.
  65     :macro:`nghttp2_error.NGHTTP2_ERR_PROTO`
  66         The *session* is client session.
  67
  68     .. warning::
  69
  70       Calling this function twice for the same stream ID may lead to
  71       program crash.  It is generally considered to a programming error
  72       to commit response twice.