walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Update API doc

This commit is contained in:
Tatsuhiro Tsujikawa 2013-08-04 18:27:07 +09:00
parent ec733a6108
commit c0a5ec8562
1 changed files with 53 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
lib/includes/nghttp2/nghttp2.h
View File

@ -234,11 +234,12 @@ typedef enum {
*/ */
typedef struct { typedef struct {
/** /**
* The |name| byte string, which is not necessarily NULL terminated. * The |name| byte string, which is not necessarily ``NULL``
* terminated.
*/ */
uint8_t *name; uint8_t *name;
/** /**
* The |value| byte string, which is not necessarily NULL * The |value| byte string, which is not necessarily ``NULL``
* terminated. * terminated.
*/ */
uint8_t *value; uint8_t *value;
@ -1313,24 +1314,24 @@ int nghttp2_session_fail_session(nghttp2_session *session,
* different in each other. * different in each other.
* *
* If called from client side, the |settings_payload| must be the * If called from client side, the |settings_payload| must be the
* value sent in HTTP2-Settings header field and must be decoded by * value sent in ``HTTP2-Settings`` header field and must be decoded
* base64url decoder. The |settings_payloadlen| is the length of * by base64url decoder. The |settings_payloadlen| is the length of
* |settings_payload|. The |settings_payload| is unpacked and its * |settings_payload|. The |settings_payload| is unpacked and its
* setting values will be submitted using * setting values will be submitted using
* nghttp2_submit_settings(). This means that the client application * `nghttp2_submit_settings()`. This means that the client application
* code does not need to submit SETTINGS by itself. The stream with * 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 ID=1 is opened and the |stream_user_data| is used for its
* stream_user_data. The opened stream becomes half-closed (local) * stream_user_data. The opened stream becomes half-closed (local)
* state. * state.
* *
* If called from server side, the |settings_payload| must be the * If called from server side, the |settings_payload| must be the
* value received in HTTP2-Settings header field and must be decoded * value received in ``HTTP2-Settings`` header field and must be
* by base64url decoder. The |settings_payloadlen| is the length of * decoded by base64url decoder. The |settings_payloadlen| is the
* |settings_payload|. It is treated as if the SETTINGS frame with * length of |settings_payload|. It is treated as if the SETTINGS
* that payload is received. Thus, callback functions for the * frame with that payload is received. Thus, callback functions for
* reception of SETTINGS frame will be invoked. The stream with stream * the reception of SETTINGS frame will be invoked. The stream with
* ID=1 is opened. The |stream_user_data| is ignored. The opened * stream ID=1 is opened. The |stream_user_data| is ignored. The
* stream becomes half-closed (remote). * opened stream becomes half-closed (remote).
* *
* This function returns 0 if it succeeds, or one of the following * This function returns 0 if it succeeds, or one of the following
* negative error codes: * negative error codes:
@ -1342,8 +1343,8 @@ int nghttp2_session_fail_session(nghttp2_session *session,
* :enum:`NGHTTP2_ERR_PROTO` * :enum:`NGHTTP2_ERR_PROTO`
* The stream ID 1 is already used or closed; or is not available; * The stream ID 1 is already used or closed; or is not available;
* or the |settings_payload| does not include both * or the |settings_payload| does not include both
* NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS and * :enum:`NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS` and
* NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE. * :enum:`NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE`.
*/ */
int nghttp2_session_upgrade(nghttp2_session *session, int nghttp2_session_upgrade(nghttp2_session *session,
const uint8_t *settings_payload, const uint8_t *settings_payload,
@ -1357,10 +1358,10 @@ int nghttp2_session_upgrade(nghttp2_session *session,
* entry pointed by |iv| array is given by the |niv|. This function * entry pointed by |iv| array is given by the |niv|. This function
* may reorder the pointers in |iv|. The |buf| must have enough region * may reorder the pointers in |iv|. The |buf| must have enough region
* to hold serialized data. The required space for the |niv| entries * to hold serialized data. The required space for the |niv| entries
* are 8*|niv| bytes. This function is used mainly for creating * are ``8*niv`` bytes. This function is used mainly for creating
* SETTINGS payload to be sent with HTTP2-Settings header field in * SETTINGS payload to be sent with ``HTTP2-Settings`` header field in
* HTTP Upgrade request. The data written in |buf| is not still * HTTP Upgrade request. The data written in |buf| is not still
* base64url encoded and the application is responsible to do that. * base64url encoded and the application is responsible for encoding.
* *
* This function returns the number of bytes written in |buf|, or one * This function returns the number of bytes written in |buf|, or one
* of the following negative error codes: * of the following negative error codes:
@ -1385,8 +1386,7 @@ const char* nghttp2_strerror(int lib_error_code);
* Submits HEADERS frame and optionally one or more DATA frames. * Submits HEADERS frame and optionally one or more DATA frames.
* *
* The |pri| is priority of this request. 0 is the highest priority * The |pri| is priority of this request. 0 is the highest priority
* value. Use `nghttp2_session_get_pri_lowest()` to know the lowest * value and :macro:`NGHTTP2_PRI_LOWEST` is the lowest value.
* priority value for this |session|.
* *
* The |nv| contains the name/value pairs. For i >= 0, ``nv[2*i]`` * The |nv| contains the name/value pairs. For i >= 0, ``nv[2*i]``
* contains a pointer to the name string and ``nv[2*i+1]`` contains a * contains a pointer to the name string and ``nv[2*i+1]`` contains a
@ -1439,8 +1439,8 @@ const char* nghttp2_strerror(int lib_error_code);
* negative error codes: * negative error codes:
* *
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT` * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |pri| is invalid; or the |nv| includes empty name or NULL * The |pri| is invalid; or the |nv| includes empty name or
* value. * ``NULL`` value.
* :enum:`NGHTTP2_ERR_NOMEM` * :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory. * Out of memory.
*/ */
@ -1479,7 +1479,7 @@ int nghttp2_submit_request(nghttp2_session *session, int32_t pri,
* negative error codes: * negative error codes:
* *
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT` * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |nv| includes empty name or NULL value. * The |nv| includes empty name or ``NULL`` value.
* :enum:`NGHTTP2_ERR_NOMEM` * :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory. * Out of memory.
*/ */
@ -1494,13 +1494,17 @@ int nghttp2_submit_response(nghttp2_session *session,
* following values: * following values:
* *
* * :enum:`NGHTTP2_FLAG_END_STREAM` * * :enum:`NGHTTP2_FLAG_END_STREAM`
* * :enum:`NGHTTP2_FLAG_END_HEADERS`
* * :enum:`NGHTTP2_FLAG_PRIORITY` * * :enum:`NGHTTP2_FLAG_PRIORITY`
* *
* If |flags| includes :enum:`NGHTTP2_FLAG_END_STREAM`, this frame has * If |flags| includes :enum:`NGHTTP2_FLAG_END_STREAM`, this frame has
* END_STREAM flag set. * END_STREAM flag set. The library does not support header
* continuation and the HEADERS frame always has
* :enum:`NGHTTP2_FLAG_END_HEADERS` flag set regardless of the |flags|
* value.
* *
* If the |stream_id| is -1, this frame is assumed as request (i.e., * If the |stream_id| is -1, this frame is assumed as request (i.e.,
* first HEADERS frame which opens new stream). In this case, the * request HEADERS frame which opens new stream). In this case, the
* actual stream ID is assigned just before the frame is sent. For * actual stream ID is assigned just before the frame is sent. For
* response, specify stream ID in |stream_id|. * response, specify stream ID in |stream_id|.
* *
@ -1521,15 +1525,15 @@ int nghttp2_submit_response(nghttp2_session *session,
* state from idle or reserved to open. * state from idle or reserved to open.
* *
* This function is low-level in a sense that the application code can * This function is low-level in a sense that the application code can
* specify flags and the Associated-To-Stream-ID directly. For usual * specify flags directly. For usual HTTP request,
* HTTP request, `nghttp2_submit_request()` is useful. * `nghttp2_submit_request()` is useful.
* *
* This function returns 0 if it succeeds, or one of the following * This function returns 0 if it succeeds, or one of the following
* negative error codes: * negative error codes:
* *
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT` * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |pri| is invalid; or the |assoc_stream_id| is invalid; or * The |pri| is invalid; or the |nv| includes empty name or
* the |nv| includes empty name or NULL value. * ``NULL`` value.
* :enum:`NGHTTP2_ERR_NOMEM` * :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory. * Out of memory.
*/ */
@ -1595,9 +1599,7 @@ int nghttp2_submit_rst_stream(nghttp2_session *session, int32_t stream_id,
* *
* Stores local settings and submits SETTINGS frame. The |iv| is the * Stores local settings and submits SETTINGS frame. The |iv| is the
* pointer to the array of :type:`nghttp2_settings_entry`. The |niv| * pointer to the array of :type:`nghttp2_settings_entry`. The |niv|
* indicates the number of :type:`nghttp2_settings_entry`. The |flags| * indicates the number of :type:`nghttp2_settings_entry`.
* is bitwise-OR of one or more values from
* :type:`nghttp2_settings_flag`.
* *
* 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|. * copies all the elements in the |iv|.
@ -1617,7 +1619,10 @@ int nghttp2_submit_settings(nghttp2_session *session,
/** /**
* @function * @function
* *
* Submits PUSH_PROMISE frame. The |flags| is currently ignored. * Submits PUSH_PROMISE frame. The |flags| is currently ignored and
* the resulting PUSH_PROMISE frame always has
* :enum:`NGHTTP2_FLAG_END_PUSH_PROMISE` flag set due to the lack of
* header continuation support in the library.
* *
* The |stream_id| must be client initiated stream ID. * The |stream_id| must be client initiated stream ID.
* *
@ -1635,7 +1640,7 @@ int nghttp2_submit_settings(nghttp2_session *session,
* stream ID must be strictly increasing, the promised stream ID * stream ID must be strictly increasing, the promised stream ID
* cannot be known until it is about to sent. To know the promised * cannot be known until it is about to sent. To know the promised
* stream ID, the application can use * stream ID, the application can use
* :member:`nghttp2_session_callbacks.before_ctrl_send_callback`. This * :member:`nghttp2_session_callbacks.before_frame_send_callback`. This
* callback is called just before the frame is sent. For PUSH_PROMISE * callback is called just before the frame is sent. For PUSH_PROMISE
* frame, the argument frame has the promised stream ID assigned. * frame, the argument frame has the promised stream ID assigned.
* *
@ -1643,7 +1648,7 @@ int nghttp2_submit_settings(nghttp2_session *session,
* negative error codes: * negative error codes:
* *
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT` * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |nv| includes empty name or NULL value. * The |nv| includes empty name or ``NULL`` value.
* :enum:`NGHTTP2_ERR_NOMEM` * :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory. * Out of memory.
*/ */
@ -1657,10 +1662,10 @@ int nghttp2_submit_push_promise(nghttp2_session *session, uint8_t flags,
* received PING frame. The library automatically submits PING frame * received PING frame. The library automatically submits PING frame
* in this case. * in this case.
* *
* If the |opaque_data| is non NULL, then it should point to the 8 * 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 * bytes array of memory to specify opaque data to send with PING
* frame. If the |opaque_data| is NULL, 8 zero bytes will be sent as * frame. If the |opaque_data| is ``NULL``, zero-cleared 8 bytes will
* opaque data. * be sent as opaque data.
* *
* This function returns 0 if it succeeds, or one of the following * This function returns 0 if it succeeds, or one of the following
* negative error codes: * negative error codes:
@ -1675,12 +1680,12 @@ int nghttp2_submit_ping(nghttp2_session *session, uint8_t *opaque_data);
* *
* Submits GOAWAY frame with the error code |error_code|. * Submits GOAWAY frame with the error code |error_code|.
* *
* If the |opaque_data| is not NULL and opaque_data_len is not zero, * If the |opaque_data| is not ``NULL`` and |opaque_data_len| is not
* those data will be sent as additional debug data. The library * zero, those data will be sent as additional debug data. The
* makes a copy of the memory region pointed by |opaque_data| with the * library makes a copy of the memory region pointed by |opaque_data|
* length |opaque_data_len|, so the caller does not need to keep this * with the length |opaque_data_len|, so the caller does not need to
* memory after the return of this function. If the |opaque_data_len| * keep this memory after the return of this function. If the
* is 0, the |opaque_data| could be NULL. * |opaque_data_len| is 0, the |opaque_data| could be ``NULL``.
* *
* This function returns 0 if it succeeds, or one of the following * This function returns 0 if it succeeds, or one of the following
* negative error codes: * negative error codes:
@ -1698,8 +1703,8 @@ int nghttp2_submit_goaway(nghttp2_session *session,
* Submits WINDOW_UPDATE frame. The effective range of the * Submits WINDOW_UPDATE frame. The effective range of the
* |window_size_increment| is [1, (1 << 31)-1], inclusive. But the * |window_size_increment| is [1, (1 << 31)-1], inclusive. But the
* application must be responsible to keep the resulting window size * application must be responsible to keep the resulting window size
* <= (1 << 31)-1. If NGHTTP2_FLAG_END_FLOW_CONTROL bit set in the * <= (1 << 31)-1. If :enum:`NGHTTP2_FLAG_END_FLOW_CONTROL` bit set in
* |flags|, 0 can be specified in the |window_size_increment|. In * the |flags|, 0 can be specified in the |window_size_increment|. In
* fact, if this flag is set, the value specified in the * fact, if this flag is set, the value specified in the
* |window_size_increment| is ignored. * |window_size_increment| is ignored.
* *
@ -1707,8 +1712,9 @@ int nghttp2_submit_goaway(nghttp2_session *session,
* negative error codes: * negative error codes:
* *
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT` * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |delta_window_size| is 0 or negative if * The |delta_window_size| is 0 or negative and
* NGHTTP2_FLAG_END_FLOW_CONTROL bit is not set in |flags|. * :enum:`NGHTTP2_FLAG_END_FLOW_CONTROL` bit is not set in
* |flags|.
* :enum:`NGHTTP2_ERR_STREAM_CLOSED` * :enum:`NGHTTP2_ERR_STREAM_CLOSED`
* The stream is already closed or does not exist. * The stream is already closed or does not exist.
* :enum:`NGHTTP2_ERR_NOMEM` * :enum:`NGHTTP2_ERR_NOMEM`