Skip to content

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

Update doc

parent 9b3d5a8b
Show whitespace changes
Inline Side-by-side
Showing with 359 additions and 335 deletions
lib/includes/nghttp2/nghttp2.h
View file @ 792938d4
......@@ -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,8 +328,11 @@ 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,
/**
......@@ -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 {
/**
......@@ -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,
......@@ -819,6 +822,7 @@ typedef struct {
/**
* @struct
*
* The HEADERS frame. It has the following members:
*/
typedef struct {
......@@ -851,6 +855,7 @@ typedef struct {
/**
* @struct
*
* The PRIORITY frame. It has the following members:
*/
typedef struct {
......@@ -866,6 +871,7 @@ typedef struct {
/**
* @struct
*
* The RST_STREAM frame. It has the following members:
*/
typedef struct {
......@@ -881,6 +887,7 @@ typedef struct {
/**
* @struct
*
* The SETTINGS ID/Value pair. It has the following members:
*/
typedef struct {
......@@ -896,6 +903,7 @@ typedef struct {
/**
* @struct
*
* The SETTINGS frame. It has the following members:
*/
typedef struct {
......@@ -915,6 +923,7 @@ typedef struct {
/**
* @struct
*
* The PUSH_PROMISE frame. It has the following members:
*/
typedef struct {
......@@ -943,6 +952,7 @@ typedef struct {
/**
* @struct
*
* The PING frame. It has the following members:
*/
typedef struct {
......@@ -958,6 +968,7 @@ typedef struct {
/**
* @struct
*
* The GOAWAY 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 {
/**
......@@ -1105,15 +1116,15 @@ typedef union {
* |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.
* the application uses solely `nghttp2_session_mem_send()` instead,
* this callback function is unnecessary.
*/
typedef ssize_t (*nghttp2_send_callback)
(nghttp2_session *session,
......@@ -1125,19 +1136,19 @@ typedef ssize_t (*nghttp2_send_callback)
* 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
* 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,7 +1158,7 @@ typedef ssize_t (*nghttp2_recv_callback)
/**
* @functypedef
*
* Callback function invoked by `nghttp2_session_recv()` when a aframe
* 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()`.
......@@ -1163,14 +1174,14 @@ typedef ssize_t (*nghttp2_recv_callback)
* 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);
......@@ -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`.
*/
......@@ -1204,25 +1215,25 @@ typedef int (*nghttp2_on_invalid_frame_recv_callback)
*
* 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()`.
* 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`.
*/
......@@ -1241,8 +1252,8 @@ typedef int (*nghttp2_on_data_chunk_recv_callback)
* 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`.
*/
......@@ -1274,8 +1285,8 @@ typedef int (*nghttp2_on_frame_send_callback)
* 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`.
*/
......@@ -1393,18 +1405,18 @@ typedef int (*nghttp2_on_begin_headers_callback)
* :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,
* :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
* 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
......@@ -1425,9 +1437,9 @@ 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],
* 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
......@@ -1450,15 +1462,15 @@ 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.
* 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.
* 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;
......@@ -1568,9 +1581,9 @@ void nghttp2_option_set_no_auto_stream_window_update(nghttp2_option *option,
* This option prevents the library from sending WINDOW_UPDATE for a
* 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);
......@@ -1583,11 +1596,11 @@ void nghttp2_option_set_no_auto_connection_window_update
* 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
* 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,
......@@ -1598,7 +1611,7 @@ void nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option,
*
* 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
* 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
......@@ -1621,7 +1634,7 @@ int nghttp2_session_client_new(nghttp2_session **session_ptr,
*
* 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
......@@ -1716,19 +1729,20 @@ void nghttp2_session_del(nghttp2_session *session);
* 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()`.
......@@ -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.
*
......@@ -1982,8 +1997,8 @@ 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
* 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.
*
......@@ -1997,12 +2012,12 @@ int32_t nghttp2_session_get_stream_effective_local_window_size
*
* 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 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,8 +2027,8 @@ 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
* 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.
*
......@@ -2048,8 +2063,8 @@ int32_t nghttp2_session_get_stream_remote_window_size(nghttp2_session* session,
* 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,20 +2078,19 @@ 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.
* 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
......@@ -2208,8 +2222,8 @@ 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
* :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
......@@ -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,
......@@ -2252,11 +2268,11 @@ int nghttp2_submit_request(nghttp2_session *session,
* |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:
......@@ -2307,9 +2323,9 @@ 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,
......@@ -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,
......@@ -2333,8 +2351,8 @@ int nghttp2_submit_headers(nghttp2_session *session, uint8_t flags,
* Submits one or more DATA frames to the stream |stream_id|. The
* 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
* function copies the members of the |data_prd|.
......@@ -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,
......@@ -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,
......@@ -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);
......@@ -2643,16 +2666,16 @@ int nghttp2_nv_compare_name(const nghttp2_nv *lhs, const nghttp2_nv *rhs);
* 2. If peer's list contains ``http/1.1``, this function selects
* ``http/1.1`` and returns 0. The following step is not taken.
*
* 3. This function selects nothing and returns -1. (So called
* 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.
......@@ -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:
......@@ -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