doc/nghttp2_submit_push_promise.rst

   1
   2 nghttp2_submit_push_promise
   3 ===========================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int32_t nghttp2_submit_push_promise(nghttp2_session *session, uint8_t flags, int32_t stream_id, const nghttp2_nv *nva, size_t nvlen, void *promised_stream_user_data)
  11
  12
  13     Submits PUSH_PROMISE frame.
  14
  15     The *flags* is currently ignored.  The library handles the
  16     CONTINUATION frame internally and it correctly sets END_HEADERS to
  17     the last sequence of the PUSH_PROMISE or CONTINUATION frame.
  18
  19     The *stream_id* must be client initiated stream ID.
  20
  21     The *nva* is an array of name/value pair :type:`nghttp2_nv` with
  22     *nvlen* elements.  The application is responsible to include
  23     required pseudo-header fields (header field whose name starts with
  24     ":") in *nva* and must place pseudo-headers before regular header
  25     fields.
  26
  27     This function creates copies of all name/value pairs in *nva*.  It
  28     also lower-cases all names in *nva*.  The order of elements in
  29     *nva* is preserved.
  30
  31     The *promised_stream_user_data* is a pointer to an arbitrary data
  32     which is associated to the promised stream this frame will open and
  33     make it in reserved state.  It is available using
  34     `nghttp2_session_get_stream_user_data()`.  The application can
  35     access it in :type:`nghttp2_before_frame_send_callback` and
  36     :type:`nghttp2_on_frame_send_callback` of this frame.
  37
  38     The client side is not allowed to use this function.
  39
  40     To submit response headers and data, use
  41     `nghttp2_submit_response()`.
  42
  43     This function returns assigned promised stream ID if it succeeds,
  44     or one of the following negative error codes:
  45
  46     :macro:`NGHTTP2_ERR_NOMEM`
  47         Out of memory.
  48     :macro:`NGHTTP2_ERR_PROTO`
  49         This function was invoked when *session* is initialized as
  50         client.
  51     :macro:`NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
  52         No stream ID is available because maximum stream ID was
  53         reached.
  54     :macro:`NGHTTP2_ERR_INVALID_ARGUMENT`
  55         The *stream_id* is 0; The *stream_id* does not designate stream
  56         that peer initiated.
  57
  58     .. warning::
  59
  60       This function returns assigned promised stream ID if it succeeds.
  61       But that stream is not opened yet.  The application must not
  62       submit frame to that stream ID before
  63       :type:`nghttp2_before_frame_send_callback` is called for this
  64       frame.
  65