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.  For header fields with
  30     :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME` and
  31     :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE` are set,
  32     header field name and value are not copied respectively.  With
  33     :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`, application
  34     is responsible to pass header field name in lowercase.  The
  35     application should maintain the references to them until
  36     :type:`nghttp2_on_frame_send_callback` or
  37     :type:`nghttp2_on_frame_not_send_callback` is called.
  38
  39     The *promised_stream_user_data* is a pointer to an arbitrary data
  40     which is associated to the promised stream this frame will open and
  41     make it in reserved state.  It is available using
  42     `nghttp2_session_get_stream_user_data()`.  The application can
  43     access it in :type:`nghttp2_before_frame_send_callback` and
  44     :type:`nghttp2_on_frame_send_callback` of this frame.
  45
  46     The client side is not allowed to use this function.
  47
  48     To submit response headers and data, use
  49     `nghttp2_submit_response()`.
  50
  51     This function returns assigned promised stream ID if it succeeds,
  52     or one of the following negative error codes:
  53
  54     :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM`
  55         Out of memory.
  56     :macro:`nghttp2_error.NGHTTP2_ERR_PROTO`
  57         This function was invoked when *session* is initialized as
  58         client.
  59     :macro:`nghttp2_error.NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE`
  60         No stream ID is available because maximum stream ID was
  61         reached.
  62     :macro:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
  63         The *stream_id* is 0; The *stream_id* does not designate stream
  64         that peer initiated.
  65     :macro:`nghttp2_error.NGHTTP2_ERR_STREAM_CLOSED`
  66         The stream was already closed; or the *stream_id* is invalid.
  67
  68     .. warning::
  69
  70       This function returns assigned promised stream ID if it succeeds.
  71       As of 1.16.0, stream object for pushed resource is created when
  72       this function succeeds.  In that case, the application can submit
  73       push response for the promised frame.
  74
  75       In 1.15.0 or prior versions, pushed stream is not opened yet when
  76       this function succeeds.  The application must not submit frame to
  77       that stream ID before :type:`nghttp2_before_frame_send_callback`
  78       is called for this frame.
  79