Imported Upstream version 1.46.0

[platform/upstream/nghttp2.git] / doc / nghttp2_submit_headers.rst

diff --git a/doc/nghttp2_submit_headers.rst b/doc/nghttp2_submit_headers.rst
index f328bad..d7deb64 100644 (file)
--- a/doc/nghttp2_submit_headers.rst
+++ b/doc/nghttp2_submit_headers.rst
@@ -7,16 +7,16 @@ Synopsis
 
 *#include <nghttp2/nghttp2.h>*
 
-.. function:: int32_t nghttp2_submit_headers(nghttp2_session *session, uint8_t flags, int32_t stream_id, const nghttp2_priority_spec *pri_spec, const nghttp2_nv *nva, size_t nvlen, void *stream_user_data)
+.. function:: int32_t nghttp2_submit_headers( nghttp2_session *session, uint8_t flags, int32_t stream_id, const nghttp2_priority_spec *pri_spec, const nghttp2_nv *nva, size_t nvlen, void *stream_user_data)
 
     
     Submits HEADERS frame. The *flags* is bitwise OR of the
     following values:
     
-    * :macro:`NGHTTP2_FLAG_END_STREAM`
+    * :macro:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`
     
-    If *flags* includes :macro:`NGHTTP2_FLAG_END_STREAM`, this frame has
-    END_STREAM flag set.
+    If *flags* includes :macro:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`,
+    this frame has END_STREAM flag set.
     
     The library handles the CONTINUATION frame internally and it
     correctly sets END_HEADERS to the last sequence of the PUSH_PROMISE
@@ -34,8 +34,8 @@ Synopsis
     this function will copy its data members.
     
     The ``pri_spec->weight`` must be in [:macro:`NGHTTP2_MIN_WEIGHT`,
-    :macro:`NGHTTP2_MAX_WEIGHT`], inclusive.  If ``pri_spec->weight`` is
-    strictly less than :macro:`NGHTTP2_MIN_WEIGHT`, it becomes
+    :macro:`NGHTTP2_MAX_WEIGHT`], inclusive.  If ``pri_spec->weight``
+    is strictly less than :macro:`NGHTTP2_MIN_WEIGHT`, it becomes
     :macro:`NGHTTP2_MIN_WEIGHT`.  If it is strictly greater than
     :macro:`NGHTTP2_MAX_WEIGHT`, it becomes :macro:`NGHTTP2_MAX_WEIGHT`.
     
@@ -47,7 +47,15 @@ Synopsis
     
     This function creates copies of all name/value pairs in *nva*.  It
     also lower-cases all names in *nva*.  The order of elements in
-    *nva* is preserved.
+    *nva* is preserved.  For header fields with
+    :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
+    :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
+    header field name and value are not copied respectively.  With
+    :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
+    is responsible to pass header field name in lowercase.  The
+    application should maintain the references to them until
+    :type:`nghttp2_on_frame_send_callback` or
+    :type:`nghttp2_on_frame_not_send_callback` is called.
     
     The *stream_user_data* is a pointer to an arbitrary data which is
     associated to the stream this frame will open.  Therefore it is
@@ -56,19 +64,27 @@ Synopsis
     
     This function is low-level in a sense that the application code can
     specify flags directly.  For usual HTTP request,
-    `nghttp2_submit_request()` is useful.
+    `nghttp2_submit_request()` is useful.  Likewise, for HTTP response,
+    prefer `nghttp2_submit_response()`.
     
     This function returns newly assigned stream ID if it succeeds and
     *stream_id* is -1.  Otherwise, this function returns 0 if it
     succeeds, or one of the following negative error codes:
     
-    :macro:`NGHTTP2_ERR_NOMEM`
+    :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM`
         Out of memory.
-    :macro:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
+    :macro:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
         No stream ID is available because maximum stream ID was
         reached.
-    :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
-        The *stream_id* is 0.
+    :macro:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
+        The *stream_id* is 0; or trying to depend on itself (stream ID
+        equals ``pri_spec->stream_id``).
+    :macro:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST`
+        DATA or HEADERS has been already submitted and not fully
+        processed yet.  This happens if stream denoted by *stream_id*
+        is in reserved state.
+    :macro:`nghttp2_error.NGHTTP2_ERR_PROTO`
+        The *stream_id* is -1, and *session* is server session.
     
     .. warning::