Upgrade to 1.46.0
[platform/upstream/nghttp2.git] / doc / nghttp2_submit_data.rst
1
2 nghttp2_submit_data
3 ===================
4
5 Synopsis
6 --------
7
8 *#include <nghttp2/nghttp2.h>*
9
10 .. function:: int nghttp2_submit_data(nghttp2_session *session, uint8_t flags, int32_t stream_id, const nghttp2_data_provider *data_prd)
11
12     
13     Submits one or more DATA frames to the stream *stream_id*.  The
14     data to be sent are provided by *data_prd*.  If *flags* contains
15     :macro:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM`, the last DATA frame
16     has END_STREAM flag set.
17     
18     This function does not take ownership of the *data_prd*.  The
19     function copies the members of the *data_prd*.
20     
21     This function returns 0 if it succeeds, or one of the following
22     negative error codes:
23     
24     :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM`
25         Out of memory.
26     :macro:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST`
27         DATA or HEADERS has been already submitted and not fully
28         processed yet.
29     :macro:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
30         The *stream_id* is 0.
31     :macro:`nghttp2_error.NGHTTP2_ERR_STREAM_CLOSED`
32         The stream was already closed; or the *stream_id* is invalid.
33     
34     .. note::
35     
36       Currently, only one DATA or HEADERS is allowed for a stream at a
37       time.  Submitting these frames more than once before first DATA
38       or HEADERS is finished results in
39       :macro:`nghttp2_error.NGHTTP2_ERR_DATA_EXIST` error code.  The
40       earliest callback which tells that previous frame is done is
41       :type:`nghttp2_on_frame_send_callback`.  In side that callback,
42       new data can be submitted using `nghttp2_submit_data()`.  Of
43       course, all data except for last one must not have
44       :macro:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` flag set in *flags*.
45       This sounds a bit complicated, and we recommend to use
46       `nghttp2_submit_request()` and `nghttp2_submit_response()` to
47       avoid this cascading issue.  The experience shows that for HTTP
48       use, these two functions are enough to implement both client and
49       server.