1
2nghttp2_submit_push_promise
3===========================
4
5Synopsis
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
80