Skip to content

N
nghttp2
Commit 792938d4 authored by Tatsuhiro Tsujikawa's avatar Tatsuhiro Tsujikawa
Browse files
Options

Update doc

parent 9b3d5a8b
Hide whitespace changes
Inline Side-by-side
Showing with 359 additions and 335 deletions
lib/includes/nghttp2/nghttp2.h
View file @ 792938d4
......@@ -70,7 +70,7 @@ struct nghttp2_session;
* @struct
*
* The primary structure to hold the resources needed for a HTTP/2
* session. The details of this structure are intentionally hidden
* session. The details of this structure are intentionally hidden
* from the public API.
*/
typedef struct nghttp2_session nghttp2_session;
......@@ -85,12 +85,12 @@ typedef struct nghttp2_session nghttp2_session;
/**
* @struct
*
* This struct is what `nghttp2_version()` returns. It holds
* This struct is what `nghttp2_version()` returns. It holds
* information about the particular nghttp2 version.
*/
typedef struct {
/**
* Age of this struct. This instance of nghttp2 sets it to
* Age of this struct. This instance of nghttp2 sets it to
* :macro:`NGHTTP2_VERSION_AGE` but a future version may bump it and
* add more struct fields at the bottom
*/
......@@ -193,7 +193,7 @@ typedef struct {
/**
* @enum
*
* Error codes used in this library. The code range is [-999, -500],
* Error codes used in this library. The code range is [-999, -500],
* inclusive. The following values are defined:
*/
typedef enum {
......@@ -226,12 +226,12 @@ typedef enum {
/**
* Used as a return value from
* :func:`nghttp2_data_source_read_callback` to indicate that data
* transfer is postponed. See
* transfer is postponed. See
* :func:`nghttp2_data_source_read_callback` for details.
*/
NGHTTP2_ERR_DEFERRED = -508,
/**
* Stream ID has reached the maximum value. Therefore no stream ID
* Stream ID has reached the maximum value. Therefore no stream ID
* is available.
*/
NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE = -509,
......@@ -240,8 +240,8 @@ typedef enum {
*/
NGHTTP2_ERR_STREAM_CLOSED = -510,
/**
* RST_STREAM has been added to the outbound queue. The stream is in
* closing state.
* RST_STREAM has been added to the outbound queue. The stream is
* in closing state.
*/
NGHTTP2_ERR_STREAM_CLOSING = -511,
/**
......@@ -263,8 +263,8 @@ typedef enum {
*/
NGHTTP2_ERR_DEFERRED_DATA_EXIST = -515,
/**
* Starting new stream is not allowed. (e.g., GOAWAY has been sent
* and/or received.
* Starting new stream is not allowed (e.g., GOAWAY has been sent
* and/or received).
*/
NGHTTP2_ERR_START_STREAM_NOT_ALLOWED = -516,
/**
......@@ -272,11 +272,11 @@ typedef enum {
*/
NGHTTP2_ERR_GOAWAY_ALREADY_SENT = -517,
/**
* The received frame contains the invalid header block. (e.g.,
* There are duplicate header names; or the header names are not
* encoded in US-ASCII character set and not lower cased; or the
* header name is zero-length string; or the header value contains
* multiple in-sequence NUL bytes).
* The received frame contains the invalid header block (e.g., There
* are duplicate header names; or the header names are not encoded
* in US-ASCII character set and not lower cased; or the header name
* is zero-length string; or the header value contains multiple
* in-sequence NUL bytes).
*/
NGHTTP2_ERR_INVALID_HEADER_BLOCK = -518,
/**
......@@ -328,16 +328,19 @@ typedef enum {
NGHTTP2_ERR_DATA_EXIST = -529,
/**
* The errors < :enum:`NGHTTP2_ERR_FATAL` mean that the library is
* under unexpected condition and cannot process any further data
* reliably (e.g., out of memory).
* under unexpected condition and processing was terminated (e.g.,
* out of memory). If application receives this error code, it must
* stop using that :type:`nghttp2_session` object and only allowed
* operation for that object is deallocate it using
* `nghttp2_session_del()`.
*/
NGHTTP2_ERR_FATAL = -900,
/**
* Out of memory. This is a fatal error.
* Out of memory. This is a fatal error.
*/
NGHTTP2_ERR_NOMEM = -901,
/**
* The user callback function failed. This is a fatal error.
* The user callback function failed. This is a fatal error.
*/
NGHTTP2_ERR_CALLBACK_FAILURE = -902
} nghttp2_error;
......@@ -446,8 +449,8 @@ typedef enum {
/**
* @enum
*
* The flags for HTTP/2 frames. This enum defines all flags for
* frames, assuming that the same flag name has the same mask.
* The flags for HTTP/2 frames. This enum defines all flags for all
* frames.
*/
typedef enum {
/**
......@@ -594,7 +597,7 @@ typedef struct {
*/
int32_t stream_id;
/**
* The type of this frame. See `nghttp2_frame`.
* The type of this frame. See `nghttp2_frame`.
*/
uint8_t type;
/**
......@@ -642,22 +645,22 @@ typedef enum {
* @functypedef
*
* Callback function invoked when the library wants to read data from
* the |source|. The read data is sent in the stream |stream_id|. The
* implementation of this function must read at most |length| bytes of
* data from |source| (or possibly other places) and store them in
* |buf| and return number of data stored in |buf|. If EOF is reached,
* set :enum:`NGHTTP2_DATA_FLAG_EOF` flag in |*data_falgs|. If the
* application wants to postpone DATA frames, (e.g., asynchronous I/O,
* or reading data blocks for long time), it is achieved by returning
* :enum:`NGHTTP2_ERR_DEFERRED` without reading any data in this
* invocation. The library removes DATA frame from the outgoing queue
* temporarily. To move back deferred DATA frame to outgoing queue,
* call `nghttp2_session_resume_data()`. In case of error, there are
* 2 choices. Returning :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`
* will close the stream by issuing RST_STREAM with
* :enum:`NGHTTP2_INTERNAL_ERROR`. Returning
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the entire session
* failure.
* the |source|. The read data is sent in the stream |stream_id|.
* The implementation of this function must read at most |length|
* bytes of data from |source| (or possibly other places) and store
* them in |buf| and return number of data stored in |buf|. If EOF is
* reached, set :enum:`NGHTTP2_DATA_FLAG_EOF` flag in |*data_falgs|.
* If the application wants to postpone DATA frames (e.g.,
* asynchronous I/O, or reading data blocks for long time), it is
* achieved by returning :enum:`NGHTTP2_ERR_DEFERRED` without reading
* any data in this invocation. The library removes DATA frame from
* the outgoing queue temporarily. To move back deferred DATA frame
* to outgoing queue, call `nghttp2_session_resume_data()`. In case
* of error, there are 2 choices. Returning
* :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close the stream
* by issuing RST_STREAM with :enum:`NGHTTP2_INTERNAL_ERROR`.
* Returning :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the
* entire session failure.
*/
typedef ssize_t (*nghttp2_data_source_read_callback)
(nghttp2_session *session, int32_t stream_id,
......@@ -684,13 +687,13 @@ typedef struct {
/**
* @struct
*
* The DATA frame. The received data is delivered via
* The DATA frame. The received data is delivered via
* :type:`nghttp2_on_data_chunk_recv_callback`.
*/
typedef struct {
nghttp2_frame_hd hd;
/**
* The length of the padding in this frame. This includes PAD_HIGH
* The length of the padding in this frame. This includes PAD_HIGH
* and PAD_LOW.
*/
size_t padlen;
......@@ -699,9 +702,9 @@ typedef struct {
/**
* @enum
*
* The category of HEADERS, which indicates the role of the frame. In
* The category of HEADERS, which indicates the role of the frame. In
* HTTP/2 spec, request, response, push response and other arbitrary
* headers (e.g., trailers) are all called just HEADERS. To give the
* headers (e.g., trailers) are all called just HEADERS. To give the
* application the role of incoming HEADERS frame, we define several
* categories.
*/
......@@ -819,7 +822,8 @@ typedef struct {
/**
* @struct
* The HEADERS frame. It has the following members:
*
* The HEADERS frame. It has the following members:
*/
typedef struct {
/**
......@@ -827,7 +831,7 @@ typedef struct {
*/
nghttp2_frame_hd hd;
/**
* The length of the padding in this frame. This includes PAD_HIGH
* The length of the padding in this frame. This includes PAD_HIGH
* and PAD_LOW.
*/
size_t padlen;
......@@ -851,7 +855,8 @@ typedef struct {
/**
* @struct
* The PRIORITY frame. It has the following members:
*
* The PRIORITY frame. It has the following members:
*/
typedef struct {
/**
......@@ -866,7 +871,8 @@ typedef struct {
/**
* @struct
* The RST_STREAM frame. It has the following members:
*
* The RST_STREAM frame. It has the following members:
*/
typedef struct {
/**
......@@ -874,18 +880,19 @@ typedef struct {
*/
nghttp2_frame_hd hd;
/**
* The error code. See :type:`nghttp2_error_code`.
* The error code. See :type:`nghttp2_error_code`.
*/
nghttp2_error_code error_code;
} nghttp2_rst_stream;
/**
* @struct
* The SETTINGS ID/Value pair. It has the following members:
*
* The SETTINGS ID/Value pair. It has the following members:
*/
typedef struct {
/**
* The SETTINGS ID. See :type:`nghttp2_settings_id`.
* The SETTINGS ID. See :type:`nghttp2_settings_id`.
*/
int32_t settings_id;
/**
......@@ -896,7 +903,8 @@ typedef struct {
/**
* @struct
* The SETTINGS frame. It has the following members:
*
* The SETTINGS frame. It has the following members:
*/
typedef struct {
/**
......@@ -915,7 +923,8 @@ typedef struct {
/**
* @struct
* The PUSH_PROMISE frame. It has the following members:
*
* The PUSH_PROMISE frame. It has the following members:
*/
typedef struct {
/**
......@@ -923,7 +932,7 @@ typedef struct {
*/
nghttp2_frame_hd hd;
/**
* The length of the padding in this frame. This includes PAD_HIGH
* The length of the padding in this frame. This includes PAD_HIGH
* and PAD_LOW.
*/
size_t padlen;
......@@ -943,7 +952,8 @@ typedef struct {
/**
* @struct
* The PING frame. It has the following members:
*
* The PING frame. It has the following members:
*/
typedef struct {
/**
......@@ -958,7 +968,8 @@ typedef struct {
/**
* @struct
* The GOAWAY frame. It has the following members:
*
* The GOAWAY frame. It has the following members:
*/
typedef struct {
/**
......@@ -970,7 +981,7 @@ typedef struct {
*/
int32_t last_stream_id;
/**
* The error code. See :type:`nghttp2_error_code`.
* The error code. See :type:`nghttp2_error_code`.
*/
nghttp2_error_code error_code;
/**
......@@ -986,7 +997,7 @@ typedef struct {
/**
* @struct
*
* The WINDOW_UPDATE frame. It has the following members:
* The WINDOW_UPDATE frame. It has the following members:
*/
typedef struct {
/**
......@@ -1047,8 +1058,8 @@ typedef struct {
* @union
*
* This union includes all frames to pass them to various function
* calls as nghttp2_frame type. The CONTINUATION frame is omitted from
* here because the library deals with it internally.
* calls as nghttp2_frame type. The CONTINUATION frame is omitted
* from here because the library deals with it internally.
*/
typedef union {
/**
......@@ -1101,19 +1112,19 @@ typedef union {
* @functypedef
*
* Callback function invoked when |session| wants to send data to the
* remote peer. The implementation of this function must send at most
* |length| bytes of data stored in |data|. The |flags| is currently
* remote peer. The implementation of this function must send at most
* |length| bytes of data stored in |data|. The |flags| is currently
* not used and always 0. It must return the number of bytes sent if
* it succeeds. If it cannot send any single byte without blocking,
* it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`. For other errors, it
* must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. The |user_data|
* pointer is the third argument passed in to the call to
* it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`. For other errors,
* it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. The
* |user_data| pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* This callback is required if the application uses
* `nghttp2_session_send()` to send data to the remote endpoint. If
* the application uses `nghttp2_session_mem_send()` instead, this
* callback function is unnecessary.
* `nghttp2_session_send()` to send data to the remote endpoint. If
* the application uses solely `nghttp2_session_mem_send()` instead,
* this callback function is unnecessary.
*/
typedef ssize_t (*nghttp2_send_callback)
(nghttp2_session *session,
......@@ -1123,21 +1134,21 @@ typedef ssize_t (*nghttp2_send_callback)
* @functypedef
*
* Callback function invoked when |session| wants to receive data from
* the remote peer. The implementation of this function must read at
* most |length| bytes of data and store it in |buf|. The |flags| is
* currently not used and always 0. It must return the number of bytes
* written in |buf| if it succeeds. If it cannot read any single byte
* without blocking, it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`. If
* it gets EOF before it reads any single byte, it must return
* :enum:`NGHTTP2_ERR_EOF`. For other errors, it must return
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. Returning 0 is treated as
* :enum:`NGHTTP2_ERR_WOULDBLOCK`. The |user_data| pointer is the
* third argument passed in to the call to
* the remote peer. The implementation of this function must read at
* most |length| bytes of data and store it in |buf|. The |flags| is
* currently not used and always 0. It must return the number of
* bytes written in |buf| if it succeeds. If it cannot read any
* single byte without blocking, it must return
* :enum:`NGHTTP2_ERR_WOULDBLOCK`. If it gets EOF before it reads any
* single byte, it must return :enum:`NGHTTP2_ERR_EOF`. For other
* errors, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
* Returning 0 is treated as :enum:`NGHTTP2_ERR_WOULDBLOCK`. The
* |user_data| pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* This callback is required if the application uses
* `nghttp2_session_recv()` to receive data from the remote
* endpoint. If the application uses `nghttp2_session_mem_recv()`
* `nghttp2_session_recv()` to receive data from the remote endpoint.
* If the application uses solely `nghttp2_session_mem_recv()`
* instead, this callback function is unnecessary.
*/
typedef ssize_t (*nghttp2_recv_callback)
......@@ -1147,30 +1158,30 @@ typedef ssize_t (*nghttp2_recv_callback)
/**
* @functypedef
*
* Callback function invoked by `nghttp2_session_recv()` when a aframe
* is received. The |user_data| pointer is the third argument passed
* Callback function invoked by `nghttp2_session_recv()` when a frame
* is received. The |user_data| pointer is the third argument passed
* in to the call to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
*
* If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
* member of their data structure are always ``NULL`` and 0
* respectively. The header name/value pairs are emitted via
* respectively. The header name/value pairs are emitted via
* :type:`nghttp2_on_header_callback`.
*
* For HEADERS, PUSH_PROMISE and DATA frames, this callback may be
* called after stream is closed (see
* :type:`nghttp2_on_stream_close_callback`). The application should
* :type:`nghttp2_on_stream_close_callback`). The application should
* check that stream is still alive using its own stream management or
* :func:`nghttp2_session_get_stream_user_data()`.
*
* Only HEADERS and DATA frame can signal the end of incoming data. If
* ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the
* Only HEADERS and DATA frame can signal the end of incoming data.
* If ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the
* |frame| is the last frame from the remote peer in this stream.
*
* The implementation of this function must return 0 if it
* succeeds. If nonzero value is returned, it is treated as fatal
* error and `nghttp2_session_recv()` and `nghttp2_session_mem_recv()`
* functions immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
* The implementation of this function must return 0 if it succeeds.
* If nonzero value is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
* immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
typedef int (*nghttp2_on_frame_recv_callback)
(nghttp2_session *session, const nghttp2_frame *frame, void *user_data);
......@@ -1179,10 +1190,10 @@ typedef int (*nghttp2_on_frame_recv_callback)
* @functypedef
*
* Callback function invoked by `nghttp2_session_recv()` when an
* invalid non-DATA frame is received. The |error_code| is one of the
* :enum:`nghttp2_error_code` and indicates the error. When this
* invalid non-DATA frame is received. The |error_code| is one of the
* :enum:`nghttp2_error_code` and indicates the error. When this
* callback function is invoked, the library automatically submits
* either RST_STREAM or GOAWAY frame. The |user_data| pointer is the
* either RST_STREAM or GOAWAY frame. The |user_data| pointer is the
* third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
......@@ -1190,8 +1201,8 @@ typedef int (*nghttp2_on_frame_recv_callback)
* member of their data structure are always ``NULL`` and 0
* respectively.
*
* The implementation of this function must return 0 if it
* succeeds. If nonzero is returned, it is treated as fatal error and
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_send()` functions
* immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
......@@ -1203,26 +1214,26 @@ typedef int (*nghttp2_on_invalid_frame_recv_callback)
* @functypedef
*
* Callback function invoked when a chunk of data in DATA frame is
* received. The |stream_id| is the stream ID this DATA frame belongs
* to. The |flags| is the flags of DATA frame which this data chunk is
* contained. ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not
* necessarily mean this chunk of data is the last one in the
* stream. You should use :type:`nghttp2_on_frame_recv_callback` to
* know all data frames are received. The |user_data| pointer is the
* third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
* received. The |stream_id| is the stream ID this DATA frame belongs
* to. The |flags| is the flags of DATA frame which this data chunk
* is contained. ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not
* necessarily mean this chunk of data is the last one in the stream.
* You should use :type:`nghttp2_on_frame_recv_callback` to know all
* data frames are received. The |user_data| pointer is the third
* argument passed in to the call to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
*
* If the application uses `nghttp2_session_mem_recv()`, it can return
* :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
* return without processing further input bytes. The memory by
* pointed by the |data| is retained until
* `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is
* called. The application must retain the input bytes which was used
* to produce the |data| parameter, because it may refer to the memory
* `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
* The application must retain the input bytes which was used to
* produce the |data| parameter, because it may refer to the memory
* region included in the input bytes.
*
* The implementation of this function must return 0 if it
* succeeds. If nonzero is returned, it is treated as fatal error and
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
* immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
......@@ -1234,15 +1245,15 @@ typedef int (*nghttp2_on_data_chunk_recv_callback)
* @functypedef
*
* Callback function invoked before the non-DATA frame |frame| is
* sent. This may be useful, for example, to know the stream ID of
* sent. This may be useful, for example, to know the stream ID of
* HEADERS and PUSH_PROMISE frame (see also
* `nghttp2_session_get_stream_user_data()`), which is not assigned
* when it was queued. The |user_data| pointer is the third argument
* when it was queued. The |user_data| pointer is the third argument
* passed in to the call to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
*
* The implementation of this function must return 0 if it
* succeeds. If nonzero is returned, it is treated as fatal error and
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_send()` functions
* immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
......@@ -1256,8 +1267,8 @@ typedef int (*nghttp2_before_frame_send_callback)
* |user_data| pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* The implementation of this function must return 0 if it
* succeeds. If nonzero is returned, it is treated as fatal error and
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_send()` functions
* immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
......@@ -1268,14 +1279,14 @@ typedef int (*nghttp2_on_frame_send_callback)
* @functypedef
*
* Callback function invoked after the non-DATA frame |frame| is not
* sent because of the error. The error is indicated by the
* sent because of the error. The error is indicated by the
* |lib_error_code|, which is one of the values defined in
* :type:`nghttp2_error`. The |user_data| pointer is the third
* :type:`nghttp2_error`. The |user_data| pointer is the third
* argument passed in to the call to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
*
* The implementation of this function must return 0 if it
* succeeds. If nonzero is returned, it is treated as fatal error and
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_send()` functions
* immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
......@@ -1286,16 +1297,18 @@ typedef int (*nghttp2_on_frame_not_send_callback)
/**
* @functypedef
*
* Callback function invoked when the stream |stream_id| is
* closed. The reason of closure is indicated by the |error_code|. The
* Callback function invoked when the stream |stream_id| is closed.
* The reason of closure is indicated by the |error_code|. The
* stream_user_data, which was specified in `nghttp2_submit_request()`
* or `nghttp2_submit_headers()`, is still available in this
* function. The |user_data| pointer is the third argument passed in
* to the call to `nghttp2_session_client_new()` or
* or `nghttp2_submit_headers()`, is still available in this function.
* The |user_data| pointer is the third argument passed in to the call
* to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
*
* The implementation of this function must return 0 if it
* succeeds. If nonzero is returned, it is treated as fatal error and
* This function is also called for a stream in reserved state.
*
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_send()` functions
* immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
......@@ -1306,19 +1319,18 @@ typedef int (*nghttp2_on_stream_close_callback)
/**
* @functypedef
*
* Callback function invoked when the received frame type is
* unknown. The |head| is the pointer to the header of the received
* frame. The |headlen| is the length of the |head|. According to the
* spec, the |headlen| is always 8. In other words, the |head| is the
* first 8 bytes of the received frame. The |payload| is the pointer
* to the data portion of the received frame. The |payloadlen| is the
* length of the |payload|. This is the data after the length
* field. The |user_data| pointer is the third argument passed in to
* the call to `nghttp2_session_client_new()` or
* `nghttp2_session_server_new()`.
* Callback function invoked when the received frame type is unknown.
* The |head| is the pointer to the header of the received frame. The
* |headlen| is the length of the |head|. According to the spec, the
* |headlen| is always 8. In other words, the |head| is the first 8
* bytes of the received frame. The |payload| is the pointer to the
* data portion of the received frame. The |payloadlen| is the length
* of the |payload|. This is the data after the length field. The
* |user_data| pointer is the third argument passed in to the call to
* `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
*
* The implementation of this function must return 0 if it
* succeeds. If nonzero is returned, it is treated as fatal error and
* The implementation of this function must return 0 if it succeeds.
* If nonzero is returned, it is treated as fatal error and
* `nghttp2_session_recv()` and `nghttp2_session_send()` functions
* immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
......@@ -1332,19 +1344,19 @@ typedef int (*nghttp2_on_unknown_frame_recv_callback)
* @functypedef
*
* Callback function invoked when the reception of header block in
* HEADERS or PUSH_PROMISE is started. Each header name/value pair
* HEADERS or PUSH_PROMISE is started. Each header name/value pair
* will be emitted by :type:`nghttp2_on_header_callback`.
*
* The ``frame->hd.flags`` may not have
* :enum:`NGHTTP2_FLAG_END_HEADERS` flag set, which indicates that one
* or more CONTINUATION frames are involved. But the application does
* or more CONTINUATION frames are involved. But the application does
* not need to care about that because the header name/value pairs are
* emitted transparently regardless of CONTINUATION frames.
*
* The implementation of this function must return 0 if it succeeds or
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If nonzero value other than
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If nonzero value other than
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned, it is treated as
* if :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned. If
* if :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned. If
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
* `nghttp2_session_mem_recv()` function will immediately return
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
......@@ -1372,43 +1384,43 @@ typedef int (*nghttp2_on_begin_headers_callback)
* :type:`nghttp2_on_frame_recv_callback` for the |frame| will not be
* invoked.
*
* The |name| may be ``NULL`` if the |namelen| is 0. The same thing
* The |name| may be ``NULL`` if the |namelen| is 0. The same thing
* can be said about the |value|.
*
* Please note that nghttp2 library does not perform any validity
* check against the |name| and the |value|. For example, the
* check against the |name| and the |value|. For example, the
* |namelen| could be 0, and/or the |value| contains ``0x0a`` or
* ``0x0d``. The application must check them if it matters. The
* ``0x0d``. The application must check them if it matters. The
* helper function `nghttp2_check_header_name()` and
* `nghttp2_check_header_value()` provide simple validation against
* HTTP2 header field construction rule.
*
* One more thing to note is that the |value| may contain ``NULL``
* (``0x00``) characters. It is used to concatenate header values
* which share the same header field name. The application should
* split these values if it wants to get individual value. This
* (``0x00``) characters. It is used to concatenate header values
* which share the same header field name. The application should
* split these values if it wants to get individual value. This
* concatenation is used in order to keep the ordering of headers.
*
* If the application uses `nghttp2_session_mem_recv()`, it can return
* :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
* return without processing further input bytes. The memory pointed
* by |frame|, |name| and |value| parameters are retained until
* `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is
* called. The application must retain the input bytes which was used
* to produce these parameters, because it may refer to the memory
* region included in the input bytes.
* `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
* The application must retain the input bytes which was used to
* produce these parameters, because it may refer to the memory region
* included in the input bytes.
*
* Returning :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close
* the stream by issuing RST_STREAM with
* :enum:`NGHTTP2_INTERNAL_ERROR`. In this case,
* :enum:`NGHTTP2_INTERNAL_ERROR`. In this case,
* :type:`nghttp2_on_frame_recv_callback` will not be invoked.
*
* The implementation of this function must return 0 if it
* succeeds. It may return :enum:`NGHTTP2_ERR_PAUSE` or
* :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. For other critical
* failures, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If
* The implementation of this function must return 0 if it succeeds.
* It may return :enum:`NGHTTP2_ERR_PAUSE` or
* :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. For other critical
* failures, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If
* the other nonzero value is returned, it is treated as
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. If
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
* `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
* immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
......@@ -1425,11 +1437,11 @@ typedef int (*nghttp2_on_header_callback)
* @functypedef
*
* Callback function invoked when the library asks application how
* much padding is required for the transmission of the |frame|. The
* application must choose the total length of payload including
* padded bytes in range [frame->hd.length, max_payloadlen],
* inclusive. Choosing number not in this range will be treated as
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. Returning
* many padding bytes are required for the transmission of the
* |frame|. The application must choose the total length of payload
* including padded bytes in range [frame->hd.length, max_payloadlen],
* inclusive. Choosing number not in this range will be treated as
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. Returning
* ``frame->hd.length`` means no padding is added. Returning
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will make
* `nghttp2_session_send()` function immediately return
......@@ -1449,16 +1461,16 @@ typedef ssize_t (*nghttp2_select_padding_callback)
typedef struct {
/**
* Callback function invoked when the |session| wants to send data
* to the remote peer. This callback is not necessary if the
* application uses `nghttp2_session_mem_send()` to serialize data
* to transmit.
* to the remote peer. This callback is not necessary if the
* application uses solely `nghttp2_session_mem_send()` to serialize
* data to transmit.
*/
nghttp2_send_callback send_callback;
/**
* Callback function invoked when the |session| wants to receive
* data from the remote peer. This callback is not necessary if the
* application uses `nghttp2_session_mem_recv()` to process received
* data.
* data from the remote peer. This callback is not necessary if the
* application uses solely `nghttp2_session_mem_recv()` to process
* received data.
*/
nghttp2_recv_callback recv_callback;
/**
......@@ -1510,7 +1522,8 @@ typedef struct {
nghttp2_on_header_callback on_header_callback;
/**
* Callback function invoked when the library asks application how
* much padding is required for the transmission of the given frame.
* many padding bytes are required for the transmission of the given
* frame.
*/
nghttp2_select_padding_callback select_padding_callback;
} nghttp2_session_callbacks;
......@@ -1553,10 +1566,10 @@ void nghttp2_option_del(nghttp2_option *option);
* @function
*
* This option prevents the library from sending WINDOW_UPDATE for a
* stream automatically. If this option is set to nonzero, the
* stream automatically. If this option is set to nonzero, the
* library won't send WINDOW_UPDATE for a stream and the application
* is responsible for sending WINDOW_UPDATE using
* `nghttp2_submit_window_update`. By default, this option is set to
* `nghttp2_submit_window_update`. By default, this option is set to
* zero.
*/
void nghttp2_option_set_no_auto_stream_window_update(nghttp2_option *option,
......@@ -1566,11 +1579,11 @@ void nghttp2_option_set_no_auto_stream_window_update(nghttp2_option *option,
* @function
*
* This option prevents the library from sending WINDOW_UPDATE for a
* connection automatically. If this option is set to nonzero, the
* connection automatically. If this option is set to nonzero, the
* library won't send WINDOW_UPDATE for a connection and the
* application is responsible for sending WINDOW_UPDATE with stream
* ID 0 using `nghttp2_submit_window_update`. By default, this
* option is set to zero.
* application is responsible for sending WINDOW_UPDATE with stream ID
* 0 using `nghttp2_submit_window_update`. By default, this option is
* set to zero.
*/
void nghttp2_option_set_no_auto_connection_window_update
(nghttp2_option *option, int val);
......@@ -1579,15 +1592,15 @@ void nghttp2_option_set_no_auto_connection_window_update
* @function
*
* This option sets the SETTINGS_MAX_CONCURRENT_STREAMS value of
* remote endpoint as if it is received in SETTINGS frame. Without
* remote endpoint as if it is received in SETTINGS frame. Without
* specifying this option, before the local endpoint receives
* SETTINGS_MAX_CONCURRENT_STREAMS in SETTINGS frame from remote
* endpoint, SETTINGS_MAX_CONCURRENT_STREAMS is unlimited. This may
* cause problem if local endpoint submits lots of requests
* initially and sending them at once to the remote peer may lead to
* the rejection of some requests. Specifying this option to the
* sensible value, say 100, may avoid this kind of issue. This value
* will be overwritten if the local endpoint receives
* endpoint, SETTINGS_MAX_CONCURRENT_STREAMS is unlimited. This may
* cause problem if local endpoint submits lots of requests initially
* and sending them at once to the remote peer may lead to the
* rejection of some requests. Specifying this option to the sensible
* value, say 100, may avoid this kind of issue. This value will be
* overwritten if the local endpoint receives
* SETTINGS_MAX_CONCURRENT_STREAMS from the remote endpoint.
*/
void nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option,
......@@ -1596,15 +1609,15 @@ void nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option,
/**
* @function
*
* Initializes |*session_ptr| for client use. The all members of
* |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
* does not store |callbacks|. |user_data| is an arbitrary user
* Initializes |*session_ptr| for client use. The all members of
* |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
* does not store |callbacks|. The |user_data| is an arbitrary user
* supplied data, which will be passed to the callback functions.
*
* The :member:`nghttp2_session_callbacks.send_callback` must be
* specified. If the application code uses `nghttp2_session_recv()`,
* the :member:`nghttp2_session_callbacks.recv_callback` must be
* specified. The other members of |callbacks| can be ``NULL``.
* specified. The other members of |callbacks| can be ``NULL``.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
......@@ -1619,15 +1632,15 @@ int nghttp2_session_client_new(nghttp2_session **session_ptr,
/**
* @function
*
* Initializes |*session_ptr| for server use. The all members of
* Initializes |*session_ptr| for server use. The all members of
* |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
* does not store |callbacks|. |user_data| is an arbitrary user
* does not store |callbacks|. The |user_data| is an arbitrary user
* supplied data, which will be passed to the callback functions.
*
* The :member:`nghttp2_session_callbacks.send_callback` must be
* specified. If the application code uses `nghttp2_session_recv()`,
* the :member:`nghttp2_session_callbacks.recv_callback` must be
* specified. The other members of |callbacks| can be ``NULL``.
* specified. The other members of |callbacks| can be ``NULL``.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
......@@ -1694,7 +1707,7 @@ int nghttp2_session_server_new2(nghttp2_session **session_ptr,
/**
* @function
*
* Frees any resources allocated for |session|. If |session| is
* Frees any resources allocated for |session|. If |session| is
* ``NULL``, this function does nothing.
*/
void nghttp2_session_del(nghttp2_session *session);
......@@ -1705,30 +1718,31 @@ void nghttp2_session_del(nghttp2_session *session);
* Sends pending frames to the remote peer.
*
* This function retrieves the highest prioritized frame from the
* outbound queue and sends it to the remote peer. It does this as
* outbound queue and sends it to the remote peer. It does this as
* many as possible until the user callback
* :member:`nghttp2_session_callbacks.send_callback` returns
* :enum:`NGHTTP2_ERR_WOULDBLOCK` or the outbound queue becomes empty.
* This function calls several callback functions which are passed
* when initializing the |session|. Here is the simple time chart
* when initializing the |session|. Here is the simple time chart
* which tells when each callback is invoked:
*
* 1. Get the next frame to send from outbound queue.
* 2. Prepare transmission of the frame.
* 3. If the control frame cannot be sent because some preconditions
* are not met (e.g., request HEADERS cannot be sent after
* GOAWAY),
* :member:`nghttp2_session_callbacks.on_frame_not_send_callback` is
* invoked. Abort the following steps.
* 4. If the frame is request HEADERS, the stream is opened
* here.
* 5. :member:`nghttp2_session_callbacks.before_frame_send_callback` is
* are not met (e.g., request HEADERS cannot be sent after GOAWAY),
* :member:`nghttp2_session_callbacks.on_frame_not_send_callback`
* is invoked. Abort the following steps.
* 4. If the frame is HEADERS, PUSH_PROMISE or DATA,
* :member:`nghttp2_session_callbacks.select_padding_callback` is
* invoked.
* 6. :member:`nghttp2_session_callbacks.send_callback` is invoked one
* 5. If the frame is request HEADERS, the stream is opened here.
* 6. :member:`nghttp2_session_callbacks.before_frame_send_callback` is
* invoked.
* 7. :member:`nghttp2_session_callbacks.send_callback` is invoked one
* or more times to send the frame.
* 7. :member:`nghttp2_session_callbacks.on_frame_send_callback` is
* 8. :member:`nghttp2_session_callbacks.on_frame_send_callback` is
* invoked.
* 8. If the transmission of the frame triggers closure of the stream,
* 9. If the transmission of the frame triggers closure of the stream,
* the stream is closed and
* :member:`nghttp2_session_callbacks.on_stream_close_callback` is
* invoked.
......@@ -1748,17 +1762,18 @@ int nghttp2_session_send(nghttp2_session *session);
*
* Returns the serialized data to send.
*
* This function behaves like `nghttp2_session_send()` except that
* it does not use :member:`nghttp2_session_callbacks.send_callback`
* to transmit data. Instead, it assigns the pointer to the serialized
* data to the |*data_ptr| and returns its length. The other callbacks
* are called in the same way as they are in `nghttp2_session_send()`.
* This function behaves like `nghttp2_session_send()` except that it
* does not use :member:`nghttp2_session_callbacks.send_callback` to
* transmit data. Instead, it assigns the pointer to the serialized
* data to the |*data_ptr| and returns its length. The other
* callbacks are called in the same way as they are in
* `nghttp2_session_send()`.
*
* If no data is available to send, this function returns 0.
*
* This function may not return all serialized data in one
* invocation. To get all data, call this function repeatedly until it
* returns 0 or one of negative error codes.
* This function may not return all serialized data in one invocation.
* To get all data, call this function repeatedly until it returns 0
* or one of negative error codes.
*
* The assigned |*data_ptr| is valid until the next call of
* `nghttp2_session_mem_send()` or `nghttp2_session_send()`.
......@@ -1783,9 +1798,9 @@ ssize_t nghttp2_session_mem_send(nghttp2_session *session,
*
* This function receives as many frames as possible until the user
* callback :member:`nghttp2_session_callbacks.recv_callback` returns
* :enum:`NGHTTP2_ERR_WOULDBLOCK`. This function calls several
* :enum:`NGHTTP2_ERR_WOULDBLOCK`. This function calls several
* callback functions which are passed when initializing the
* |session|. Here is the simple time chart which tells when each
* |session|. Here is the simple time chart which tells when each
* callback is invoked:
*
* 1. :member:`nghttp2_session_callbacks.recv_callback` is invoked one
......@@ -1798,7 +1813,7 @@ ssize_t nghttp2_session_mem_send(nghttp2_session *session,
* is invoked.
* 2. If one DATA frame is completely received,
* :member:`nghttp2_session_callbacks.on_frame_recv_callback` is
* invoked. If the reception of the frame triggers the
* invoked. If the reception of the frame triggers the
* closure of the stream,
* :member:`nghttp2_session_callbacks.on_stream_close_callback`
* is invoked.
......@@ -1809,11 +1824,11 @@ ssize_t nghttp2_session_mem_send(nghttp2_session *session,
* one or more times to receive whole frame.
*
* 2. If the received frame is valid, then following actions are
* taken. If the frame is either HEADERS or PUSH_PROMISE,
* taken. If the frame is either HEADERS or PUSH_PROMISE,
* :member:`nghttp2_session_callbacks.on_begin_headers_callback`
* is invoked. Then
* is invoked. Then
* :member:`nghttp2_session_callbacks.on_header_callback` is
* invoked for each header name/value pair. After all name/value
* invoked for each header name/value pair. After all name/value
* pairs are emitted successfully,
* :member:`nghttp2_session_callbacks.on_frame_recv_callback` is
* invoked. For other frames,
......@@ -1846,13 +1861,13 @@ int nghttp2_session_recv(nghttp2_session *session);
/**
* @function
*
* Processes data |in| as an input from the remote endpoint. The
* Processes data |in| as an input from the remote endpoint. The
* |inlen| indicates the number of bytes in the |in|.
*
* This function behaves like `nghttp2_session_recv()` except that it
* does not use :member:`nghttp2_session_callbacks.recv_callback` to
* receive data; the |in| is the only data for the invocation of this
* function. If all bytes are processed, this function returns. The
* function. If all bytes are processed, this function returns. The
* other callbacks are called in the same way as they are in
* `nghttp2_session_recv()`.
*
......@@ -1920,13 +1935,13 @@ int nghttp2_session_want_write(nghttp2_session *session);
/**
* @function
*
* Returns stream_user_data for the stream |stream_id|. The
* Returns stream_user_data for the stream |stream_id|. The
* stream_user_data is provided by `nghttp2_submit_request()`,
* `nghttp2_submit_headers()` or
* `nghttp2_session_set_stream_user_data()`. Unless it is set using
* `nghttp2_session_set_stream_user_data()`. Unless it is set using
* `nghttp2_session_set_stream_user_data()`, if the stream is
* initiated by the remote endpoint, stream_user_data is always
* ``NULL``. If the stream does not exist, this function returns
* ``NULL``. If the stream does not exist, this function returns
* ``NULL``.
*/
void* nghttp2_session_get_stream_user_data(nghttp2_session *session,
......@@ -1936,8 +1951,8 @@ void* nghttp2_session_get_stream_user_data(nghttp2_session *session,
* @function
*
* Sets the |stream_user_data| to the stream denoted by the
* |stream_id|. If a stream user data is already set to the stream, it
* is replaced with the |stream_user_data|. It is valid to specify
* |stream_id|. If a stream user data is already set to the stream,
* it is replaced with the |stream_user_data|. It is valid to specify
* ``NULL`` in the |stream_user_data|, which nullifies the associated
* data pointer.
*
......@@ -1957,7 +1972,7 @@ int nghttp2_session_set_stream_user_data(nghttp2_session *session,
/**
* @function
*
* Returns the number of frames in the outbound queue. This does not
* Returns the number of frames in the outbound queue. This does not
* include the deferred DATA frames.
*/
size_t nghttp2_session_get_outbound_queue_size(nghttp2_session *session);
......@@ -1966,10 +1981,10 @@ size_t nghttp2_session_get_outbound_queue_size(nghttp2_session *session);
* @function
*
* Returns the number of DATA payload in bytes received without
* WINDOW_UPDATE transmission for the stream |stream_id|. The local
* WINDOW_UPDATE transmission for the stream |stream_id|. The local
* (receive) window size can be adjusted by
* `nghttp2_submit_window_update()`. This function takes into account
* that and returns effective data length. In particular, if the
* `nghttp2_submit_window_update()`. This function takes into account
* that and returns effective data length. In particular, if the
* local window size is reduced by submitting negative
* window_size_increment with `nghttp2_submit_window_update()`, this
* function returns the number of bytes less than actually received.
......@@ -1982,9 +1997,9 @@ int32_t nghttp2_session_get_stream_effective_recv_data_length
/**
* @function
*
* Returns the local (receive) window size for the stream
* |stream_id|. The local window size can be adjusted by
* `nghttp2_submit_window_update()`. This function takes into account
* Returns the local (receive) window size for the stream |stream_id|.
* The local window size can be adjusted by
* `nghttp2_submit_window_update()`. This function takes into account
* that and returns effective window size.
*
* This function returns -1 if it fails.
......@@ -1996,13 +2011,13 @@ int32_t nghttp2_session_get_stream_effective_local_window_size
* @function
*
* Returns the number of DATA payload in bytes received without
* WINDOW_UPDATE transmission for a connection. The local (receive)
* window size can be adjusted by
* `nghttp2_submit_window_update()`. This function takes into account
* that and returns effective data length. In particular, if the local
* window size is reduced by submitting negative window_size_increment
* with `nghttp2_submit_window_update()`, this function returns the
* number of bytes less than actually received.
* WINDOW_UPDATE transmission for a connection. The local (receive)
* window size can be adjusted by `nghttp2_submit_window_update()`.
* This function takes into account that and returns effective data
* length. In particular, if the local window size is reduced by
* submitting negative window_size_increment with
* `nghttp2_submit_window_update()`, this function returns the number
* of bytes less than actually received.
*
* This function returns -1 if it fails.
*/
......@@ -2012,9 +2027,9 @@ int32_t nghttp2_session_get_effective_recv_data_length
/**
* @function
*
* Returns the local (receive) window size for a connection. The local
* window size can be adjusted by
* `nghttp2_submit_window_update()`. This function takes into account
* Returns the local (receive) window size for a connection. The
* local window size can be adjusted by
* `nghttp2_submit_window_update()`. This function takes into account
* that and returns effective window size.
*
* This function returns -1 if it fails.
......@@ -2040,16 +2055,16 @@ int32_t nghttp2_session_get_stream_remote_window_size(nghttp2_session* session,
* Signals the session so that the connection should be terminated.
*
* GOAWAY frame with the given |error_code| will be submitted if it
* has not been transmitted. After the transmission, both
* has not been transmitted. After the transmission, both
* `nghttp2_session_want_read()` and `nghttp2_session_want_write()`
* return 0. If GOAWAY frame has already transmitted at the time when
* return 0. If GOAWAY frame has already transmitted at the time when
* this function is invoked, `nghttp2_session_want_read()` and
* `nghttp2_session_want_write()` returns 0 immediately after this
* function succeeds.
*
* This function should be called when the connection should be
* terminated after sending GOAWAY. If the remaining streams should be
* processed after GOAWAY, use `nghttp2_submit_goaway()` instead.
* terminated after sending GOAWAY. If the remaining streams should
* be processed after GOAWAY, use `nghttp2_submit_goaway()` instead.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
......@@ -2063,28 +2078,27 @@ int nghttp2_session_terminate_session(nghttp2_session *session,
/**
* @function
*
* Performs post-process of HTTP Upgrade request. This function can be
* called from both client and server, but the behavior is very
* Performs post-process of HTTP Upgrade request. This function can
* be called from both client and server, but the behavior is very
* different in each other.
*
* If called from client side, the |settings_payload| must be the
* value sent in ``HTTP2-Settings`` header field and must be decoded
* by base64url decoder. The |settings_payloadlen| is the length of
* |settings_payload|. The |settings_payload| is unpacked and its
* setting values will be submitted using
* `nghttp2_submit_settings()`. This means that the client application
* code does not need to submit SETTINGS by itself. The stream with
* stream ID=1 is opened and the |stream_user_data| is used for its
* stream_user_data. The opened stream becomes half-closed (local)
* state.
* by base64url decoder. The |settings_payloadlen| is the length of
* |settings_payload|. The |settings_payload| is unpacked and its
* setting values will be submitted using `nghttp2_submit_settings()`.
* This means that the client application code does not need to submit
* SETTINGS by itself. The stream with stream ID=1 is opened and the
* |stream_user_data| is used for its stream_user_data. The opened
* stream becomes half-closed (local) state.
*
* If called from server side, the |settings_payload| must be the
* value received in ``HTTP2-Settings`` header field and must be
* decoded by base64url decoder. The |settings_payloadlen| is the
* length of |settings_payload|. It is treated as if the SETTINGS
* frame with that payload is received. Thus, callback functions for
* the reception of SETTINGS frame will be invoked. The stream with
* stream ID=1 is opened. The |stream_user_data| is ignored. The
* decoded by base64url decoder. The |settings_payloadlen| is the
* length of |settings_payload|. It is treated as if the SETTINGS
* frame with that payload is received. Thus, callback functions for
* the reception of SETTINGS frame will be invoked. The stream with
* stream ID=1 is opened. The |stream_user_data| is ignored. The
* opened stream becomes half-closed (remote).
*
* This function returns 0 if it succeeds, or one of the following
......@@ -2105,13 +2119,13 @@ int nghttp2_session_upgrade(nghttp2_session *session,
/**
* @function
*
* Serializes the SETTINGS values |iv| in the |buf|. The size of the
* |buf| is specified by |buflen|. The number of entries in the |iv|
* array is given by |niv|. The required space in |buf| for the |niv|
* Serializes the SETTINGS values |iv| in the |buf|. The size of the
* |buf| is specified by |buflen|. The number of entries in the |iv|
* array is given by |niv|. The required space in |buf| for the |niv|
* entries is ``8*niv`` bytes and if the given buffer is too small, an
* error is returned. This function is used mainly for creating a
* error is returned. This function is used mainly for creating a
* SETTINGS payload to be sent with the ``HTTP2-Settings`` header
* field in an HTTP Upgrade request. The data written in |buf| is NOT
* field in an HTTP Upgrade request. The data written in |buf| is NOT
* base64url encoded and the application is responsible for encoding.
*
* This function returns the number of bytes written in |buf|, or one
......@@ -2131,7 +2145,7 @@ ssize_t nghttp2_pack_settings_payload(uint8_t *buf,
/**
* @function
*
* Returns string describing the |lib_error_code|. The
* Returns string describing the |lib_error_code|. The
* |lib_error_code| must be one of the :enum:`nghttp2_error`.
*/
const char* nghttp2_strerror(int lib_error_code);
......@@ -2160,7 +2174,7 @@ void nghttp2_priority_spec_group_init(nghttp2_priority_spec *pri_spec,
* @function
*
* Initializes |pri_spec| with the |stream_id| of the stream to depend
* on and its exclusive flag. If |exclusive| is nonzero, exclusive
* on and its exclusive flag. If |exclusive| is nonzero, exclusive
* flag is set.
*/
void nghttp2_priority_spec_dep_init(nghttp2_priority_spec *pri_spec,
......@@ -2179,26 +2193,26 @@ void nghttp2_priority_spec_dep_init(nghttp2_priority_spec *pri_spec,
* this function will copy its data members.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The value is opaque sequence of bytes and
* therefore can contain NULL byte (0x0). If the application requires
* |nvlen| elements. The value is opaque sequence of bytes and
* therefore can contain NULL byte (0x0). If the application requires
* that the ordering of values for a single header field name
* appearing in different header fields, it has to concatenate them
* using NULL byte (0x0) before passing them to this function.
*
* HTTP/2 specification has requirement about header fields in the
* request HEADERS. See the specification for more details.
* request HEADERS. See the specification for more details.
*
* This function creates copies of all name/value pairs in |nva|. It
* also lower-cases all names in |nva|.
*
* If |data_prd| is not ``NULL``, it provides data which will be sent
* in subsequent DATA frames. In this case, a method that allows
* in subsequent DATA frames. In this case, a method that allows
* request message bodies
* (http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9) must
* be specified with ``:method`` key in |nva| (e.g. ``POST``). This
* function does not take ownership of the |data_prd|. The function
* copies the members of the |data_prd|. If |data_prd| is ``NULL``,
* HEADERS have END_STREAM set. The |stream_user_data| is data
* be specified with ``:method`` key in |nva| (e.g. ``POST``). This
* function does not take ownership of the |data_prd|. The function
* copies the members of the |data_prd|. If |data_prd| is ``NULL``,
* HEADERS have END_STREAM set. The |stream_user_data| is data
* associated to the stream opened by this request and can be an
* arbitrary pointer, which can be retrieved later by
* `nghttp2_session_get_stream_user_data()`.
......@@ -2208,9 +2222,9 @@ void nghttp2_priority_spec_dep_init(nghttp2_priority_spec *pri_spec,
* stream ID must be strictly increasing, the stream ID of this
* request cannot be known until it is about to sent. To know the
* stream ID of the request, the application can use
* :member:`nghttp2_session_callbacks.before_frame_send_callback`. This
* callback is called just before the frame is sent. For HEADERS
* frame, the argument frame has the stream ID assigned. Also since
* :member:`nghttp2_session_callbacks.before_frame_send_callback`.
* This callback is called just before the frame is sent. For HEADERS
* frame, the argument frame has the stream ID assigned. Also since
* the stream is already opened,
* `nghttp2_session_get_stream_user_data()` can be used to get
* |stream_user_data| to identify which HEADERS we are processing.
......@@ -2220,6 +2234,8 @@ void nghttp2_priority_spec_dep_init(nghttp2_priority_spec *pri_spec,
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |pri_spec->pri_type| is invalid.
*/
int nghttp2_submit_request(nghttp2_session *session,
const nghttp2_priority_spec *pri_spec,
......@@ -2234,29 +2250,29 @@ int nghttp2_submit_request(nghttp2_session *session,
* frames against the stream |stream_id|.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The value is opaque sequence of bytes and
* therefore can contain NULL byte (0x0). If the application requires
* |nvlen| elements. The value is opaque sequence of bytes and
* therefore can contain NULL byte (0x0). If the application requires
* that the ordering of values for a single header field name
* appearing in different header fields, it has to concatenate them
* using NULL byte (0x0) before passing them to this function.
*
* HTTP/2 specification has requirement about header fields in the
* response HEADERS. See the specification for more details.
* response HEADERS. See the specification for more details.
*
* This function creates copies of all name/value pairs in |nva|. It
* also lower-cases all names in |nva|.
*
* If |data_prd| is not ``NULL``, it provides data which will be sent
* in subsequent DATA frames. This function does not take ownership
* of the |data_prd|. The function copies the members of the
* of the |data_prd|. The function copies the members of the
* |data_prd|. If |data_prd| is ``NULL``, HEADERS will have
* END_STREAM flag set.
*
* This method can be used as normal HTTP response and push
* response. When pushing a resource using this function, the
* |session| must be configured using `nghttp2_session_server_new()`
* or its variants and the target stream denoted by the |stream_id|
* must be reserved using `nghttp2_submit_push_promise()`.
* This method can be used as normal HTTP response and push response.
* When pushing a resource using this function, the |session| must be
* configured using `nghttp2_session_server_new()` or its variants and
* the target stream denoted by the |stream_id| must be reserved using
* `nghttp2_submit_push_promise()`.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
......@@ -2285,8 +2301,8 @@ int nghttp2_submit_response(nghttp2_session *session,
* or CONTINUATION frame.
*
* If the |stream_id| is -1, this frame is assumed as request (i.e.,
* request HEADERS frame which opens new stream). In this case, the
* actual stream ID is assigned just before the frame is sent. For
* request HEADERS frame which opens new stream). In this case, the
* actual stream ID is assigned just before the frame is sent. For
* response, specify stream ID in |stream_id|.
*
* The |pri_spec| is priority specification of this request. ``NULL``
......@@ -2297,8 +2313,8 @@ int nghttp2_submit_response(nghttp2_session *session,
* this function will copy its data members.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The value is opaque sequence of bytes and
* therefore can contain NULL byte (0x0). If the application requires
* |nvlen| elements. The value is opaque sequence of bytes and
* therefore can contain NULL byte (0x0). If the application requires
* that the ordering of values for a single header field name
* appearing in different header fields, it has to concatenate them
* using NULL byte (0x0) before passing them to this function.
......@@ -2307,12 +2323,12 @@ int nghttp2_submit_response(nghttp2_session *session,
* also lower-cases all names in |nva|.
*
* The |stream_user_data| is a pointer to an arbitrary data which is
* associated to the stream this frame will open. Therefore it is only
* used if this frame opens streams, in other words, it changes stream
* state from idle or reserved to open.
* associated to the stream this frame will open. Therefore it is
* only used if this frame opens streams, in other words, it changes
* stream state from idle or reserved to open.
*
* This function is low-level in a sense that the application code can
* specify flags directly. For usual HTTP request,
* specify flags directly. For usual HTTP request,
* `nghttp2_submit_request()` is useful.
*
* This function returns 0 if it succeeds, or one of the following
......@@ -2320,6 +2336,8 @@ int nghttp2_submit_response(nghttp2_session *session,
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |pri_spec->pri_type| is invalid.
*/
int nghttp2_submit_headers(nghttp2_session *session, uint8_t flags,
int32_t stream_id,
......@@ -2331,12 +2349,12 @@ int nghttp2_submit_headers(nghttp2_session *session, uint8_t flags,
* @function
*
* Submits one or more DATA frames to the stream |stream_id|. The
* data to be sent are provided by |data_prd|. If |flags| contains
* data to be sent are provided by |data_prd|. If |flags| contains
* :enum:`NGHTTP2_FLAG_END_STREAM`, the last DATA frame has END_STREAM
* flag set. If |flags| contains :enum:`NGHTTP2_FLAG_END_SEGMENT`, the
* last DATA frame has END_SEGMENT flag set.
* flag set. If |flags| contains :enum:`NGHTTP2_FLAG_END_SEGMENT`,
* the last DATA frame has END_SEGMENT flag set.
*
* This function does not take ownership of the |data_prd|. The
* This function does not take ownership of the |data_prd|. The
* function copies the members of the |data_prd|.
*
* This function returns 0 if it succeeds, or one of the following
......@@ -2372,7 +2390,8 @@ int nghttp2_submit_data(nghttp2_session *session, uint8_t flags,
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |pri_spec| is NULL; or trying to depend on itself.
* The |pri_spec| is NULL; or the |pri_spec->pri_type| is invalid;
* or trying to depend on itself.
*/
int nghttp2_submit_priority(nghttp2_session *session, uint8_t flags,
int32_t stream_id,
......@@ -2400,14 +2419,14 @@ int nghttp2_submit_rst_stream(nghttp2_session *session, uint8_t flags,
/**
* @function
*
* Stores local settings and submits SETTINGS frame. The |iv| is the
* pointer to the array of :type:`nghttp2_settings_entry`. The |niv|
* Stores local settings and submits SETTINGS frame. The |iv| is the
* pointer to the array of :type:`nghttp2_settings_entry`. The |niv|
* indicates the number of :type:`nghttp2_settings_entry`.
*
* The |flags| is currently ignored and should be
* :enum:`NGHTTP2_FLAG_NONE`.
*
* This function does not take ownership of the |iv|. This function
* This function does not take ownership of the |iv|. This function
* copies all the elements in the |iv|.
*
* While updating individual stream's local window size, if the window
......@@ -2439,15 +2458,15 @@ int nghttp2_submit_settings(nghttp2_session *session, uint8_t flags,
*
* Submits PUSH_PROMISE frame.
*
* The |flags| is currently ignored. The library handles the
* The |flags| is currently ignored. The library handles the
* CONTINUATION frame internally and it correctly sets END_HEADERS to
* the last sequence of the PUSH_PROMISE or CONTINUATION frame.
*
* The |stream_id| must be client initiated stream ID.
*
* The |nva| is an array of name/value pair :type:`nghttp2_nv` with
* |nvlen| elements. The value is opaque sequence of bytes and
* therefore can contain NULL byte (0x0). If the application requires
* |nvlen| elements. The value is opaque sequence of bytes and
* therefore can contain NULL byte (0x0). If the application requires
* that the ordering of values for a single header field name
* appearing in different header fields, it has to concatenate them
* using NULL byte (0x0) before passing them to this function.
......@@ -2457,8 +2476,8 @@ int nghttp2_submit_settings(nghttp2_session *session, uint8_t flags,
*
* The |promised_stream_user_data| is a pointer to an arbitrary data
* which is associated to the promised stream this frame will open and
* make it in reserved state. It is available using
* `nghttp2_session_get_stream_user_data()`. The application can
* make it in reserved state. It is available using
* `nghttp2_session_get_stream_user_data()`. The application can
* access it in :type:`nghttp2_before_frame_send_callback` and
* :type:`nghttp2_on_frame_send_callback` of this frame.
*
......@@ -2467,18 +2486,21 @@ int nghttp2_submit_settings(nghttp2_session *session, uint8_t flags,
* stream ID must be strictly increasing, the promised stream ID
* cannot be known until it is about to sent. To know the promised
* stream ID, the application can use
* :member:`nghttp2_session_callbacks.before_frame_send_callback`. This
* callback is called just before the frame is sent. For PUSH_PROMISE
* frame, the argument frame has the promised stream ID assigned.
* :member:`nghttp2_session_callbacks.before_frame_send_callback`.
* This callback is called just before the frame is sent. For
* PUSH_PROMISE frame, the argument frame has the promised stream ID
* assigned.
*
* The client side can use this function to send PUSH_PROMISE to the
* server. But in normal HTTP usage, the server may treat it error.
* The client side is not allowed to use this function.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`NGHTTP2_ERR_PROTO`
* This function was invoked when |session| is initialized as
* client.
*/
int nghttp2_submit_push_promise(nghttp2_session *session, uint8_t flags,
int32_t stream_id,
......@@ -2488,8 +2510,8 @@ int nghttp2_submit_push_promise(nghttp2_session *session, uint8_t flags,
/**
* @function
*
* Submits PING frame. You don't have to send PING back when you
* received PING frame. The library automatically submits PING frame
* Submits PING frame. You don't have to send PING back when you
* received PING frame. The library automatically submits PING frame
* in this case.
*
* The |flags| is currently ignored and should be
......@@ -2497,7 +2519,7 @@ int nghttp2_submit_push_promise(nghttp2_session *session, uint8_t flags,
*
* If the |opaque_data| is non ``NULL``, then it should point to the 8
* bytes array of memory to specify opaque data to send with PING
* frame. If the |opaque_data| is ``NULL``, zero-cleared 8 bytes will
* frame. If the |opaque_data| is ``NULL``, zero-cleared 8 bytes will
* be sent as opaque data.
*
* This function returns 0 if it succeeds, or one of the following
......@@ -2521,7 +2543,7 @@ int nghttp2_submit_ping(nghttp2_session *session, uint8_t flags,
* zero, those data will be sent as additional debug data. The
* library makes a copy of the memory region pointed by |opaque_data|
* with the length |opaque_data_len|, so the caller does not need to
* keep this memory after the return of this function. If the
* keep this memory after the return of this function. If the
* |opaque_data_len| is 0, the |opaque_data| could be ``NULL``.
*
* This function returns 0 if it succeeds, or one of the following
......@@ -2545,7 +2567,7 @@ int nghttp2_submit_goaway(nghttp2_session *session, uint8_t flags,
* :enum:`NGHTTP2_FLAG_NONE`.
*
* If the |window_size_increment| is positive, the WINDOW_UPDATE with
* that value as window_size_increment is queued. If the
* that value as window_size_increment is queued. If the
* |window_size_increment| is larger than the received bytes from the
* remote endpoint, the local window size is increased by that
* difference.
......@@ -2596,7 +2618,7 @@ int nghttp2_submit_window_update(nghttp2_session *session, uint8_t flags,
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`NGHTTP2_ERR_INVALID_STATE`
* :enum:`NGHTTP2_ERR_PROTO`
* The function is invoked with |session| which was initialized as
* client.
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
......@@ -2613,10 +2635,11 @@ int nghttp2_submit_altsvc(nghttp2_session *session, uint8_t flags,
/**
* @function
*
* Compares lhs->name with lhs->namelen bytes and rhs->name with
* rhs->namelen bytes. Returns negative integer if lhs->name is found
* to be less than rhs->name; or returns positive integer if lhs->name
* is found to be greater than rhs->name; or returns 0 otherwise.
* Compares ``lhs->name`` of length ``lhs->namelen`` bytes and
* ``rhs->name`` of length ``rhs->namelen`` bytes. Returns negative
* integer if ``lhs->name`` is found to be less than ``rhs->name``; or
* returns positive integer if ``lhs->name`` is found to be greater
* than ``rhs->name``; or returns 0 otherwise.
*/
int nghttp2_nv_compare_name(const nghttp2_nv *lhs, const nghttp2_nv *rhs);
......@@ -2624,7 +2647,7 @@ int nghttp2_nv_compare_name(const nghttp2_nv *lhs, const nghttp2_nv *rhs);
* @function
*
* A helper function for dealing with NPN in client side or ALPN in
* server side. The |in| contains peer's protocol list in preferable
* server side. The |in| contains peer's protocol list in preferable
* order. The format of |in| is length-prefixed and not
* null-terminated. For example, ``HTTP-draft-04/2.0`` and
* ``http/1.1`` stored in |in| like this::
......@@ -2641,18 +2664,18 @@ int nghttp2_nv_compare_name(const nghttp2_nv *lhs, const nghttp2_nv *rhs);
* it is selected and returns 1. The following step is not taken.
*
* 2. If peer's list contains ``http/1.1``, this function selects
* ``http/1.1`` and returns 0. The following step is not taken.
* ``http/1.1`` and returns 0. The following step is not taken.
*
* 3. This function selects nothing and returns -1. (So called
* non-overlap case). In this case, |out| and |outlen| are left
* 3. This function selects nothing and returns -1 (So called
* non-overlap case). In this case, |out| and |outlen| are left
* untouched.
*
* Selecting ``HTTP-draft-04/2.0`` means that ``HTTP-draft-04/2.0`` is
* written into |*out| and its length (which is 17) is
* assigned to |*outlen|.
* written into |*out| and its length (which is 17) is assigned to
* |*outlen|.
*
* For ALPN, refer to
* http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-04
* https://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-05
*
* See http://technotes.googlecode.com/git/nextprotoneg.html for more
* details about NPN.
......@@ -2685,7 +2708,7 @@ struct nghttp2_gzip;
/**
* @struct
*
* The gzip stream to inflate data. The details of this structure are
* The gzip stream to inflate data. The details of this structure are
* intentionally hidden from the public API.
*/
typedef struct nghttp2_gzip nghttp2_gzip;
......@@ -2693,7 +2716,8 @@ typedef struct nghttp2_gzip nghttp2_gzip;
/**
* @function
*
* A helper function to set up a per request gzip stream to inflate data.
* A helper function to set up a per request gzip stream to inflate
* data.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
......@@ -2717,7 +2741,7 @@ void nghttp2_gzip_inflate_del(nghttp2_gzip *inflater);
*
* Inflates data in |in| with the length |*inlen_ptr| and stores the
* inflated data to |out| which has allocated size at least
* |*outlen_ptr|. On return, |*outlen_ptr| is updated to represent
* |*outlen_ptr|. On return, |*outlen_ptr| is updated to represent
* the number of data written in |out|. Similarly, |*inlen_ptr| is
* updated to represent the number of input bytes processed.
*
......@@ -2763,11 +2787,11 @@ int nghttp2_gzip_inflate(nghttp2_gzip *inflater,
/**
* @function
*
* Returns a pointer to a nghttp2_info struct with version information about
* the run-time library in use. The |least_version| argument can be set to a
* 24 bit numerical value for the least accepted version number and if the
* condition is not met, this function will return a NULL. Pass in 0 to skip
* the version checking.
* Returns a pointer to a nghttp2_info struct with version information
* about the run-time library in use. The |least_version| argument
* can be set to a 24 bit numerical value for the least accepted
* version number and if the condition is not met, this function will
* return a ``NULL``. Pass in 0 to skip the version checking.
*/
nghttp2_info *nghttp2_version(int least_version);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment