diff --git a/apiref.html b/apiref.html index 1b8902f2..e9b916e8 100644 --- a/apiref.html +++ b/apiref.html @@ -7,7 +7,7 @@ - API Reference — nghttp2 0.4.1 documentation + API Reference — nghttp2 0.4.2-DEV documentation @@ -28,7 +28,7 @@ - + @@ -561,7 +561,7 @@ Indicates that this name/value pair must not be indexed.

nghttp2_frame_type
-

The control frame types in HTTP/2.

+

The frame types in HTTP/2 specification.

NGHTTP2_DATA
@@ -632,18 +632,26 @@ The WINDOW_UPDATE frame.

The CONTINUATION frame.

+ + +
+
+nghttp2_ext_frame_type
+

The extension frame types.

+

TODO: The assigned frame types were carried from draft-12, and now +actually TBD.

-
-NGHTTP2_ALTSVC
+
+NGHTTP2_EXT_ALTSVC

(0x0a) -The ALTSVC frame.

+The ALTSVC extension frame.

-
-NGHTTP2_BLOCKED
+
+NGHTTP2_EXT_BLOCKED

(0x0b) -The BLOCKED frame.

+The BLOCKED extension frame.

@@ -689,17 +697,10 @@ The END_SEGMENT flag.

-
-NGHTTP2_FLAG_PAD_LOW
+
+NGHTTP2_FLAG_PADDED

(0x08) -The PAD_LOW flag.

-
- -
-
-NGHTTP2_FLAG_PAD_HIGH
-

(0x10) -The PAD_HIGH flag.

+The PADDED flag.

@@ -709,13 +710,6 @@ The PAD_HIGH flag.

The PRIORITY flag.

-
-
-NGHTTP2_FLAG_COMPRESSED
-

(0x20) -THE COMPRESSED flag.

-
-
@@ -725,45 +719,31 @@ THE COMPRESSED flag.

NGHTTP2_SETTINGS_HEADER_TABLE_SIZE
-

(1) +

(0x01) SETTINGS_HEADER_TABLE_SIZE

NGHTTP2_SETTINGS_ENABLE_PUSH
-

(2) +

(0x02) SETTINGS_ENABLE_PUSH

NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS
-

(3) +

(0x03) SETTINGS_MAX_CONCURRENT_STREAMS

NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE
-

(4) +

(0x04) SETTINGS_INITIAL_WINDOW_SIZE

-
-
-NGHTTP2_SETTINGS_COMPRESS_DATA
-

(5) -SETTINGS_COMPRESS_DATA

-
- -
-
-NGHTTP2_SETTINGS_MAX
-

(5) -Maximum ID of nghttp2_settings_id.

-
-
@@ -773,91 +753,91 @@ Maximum ID of
NGHTTP2_NO_ERROR
-

(0) +

(0x00) No errors.

NGHTTP2_PROTOCOL_ERROR
-

(1) +

(0x01) PROTOCOL_ERROR

NGHTTP2_INTERNAL_ERROR
-

(2) +

(0x02) INTERNAL_ERROR

NGHTTP2_FLOW_CONTROL_ERROR
-

(3) +

(0x03) FLOW_CONTROL_ERROR

NGHTTP2_SETTINGS_TIMEOUT
-

(4) +

(0x04) SETTINGS_TIMEOUT

NGHTTP2_STREAM_CLOSED
-

(5) +

(0x05) STREAM_CLOSED

NGHTTP2_FRAME_SIZE_ERROR
-

(6) +

(0x06) FRAME_SIZE_ERROR

NGHTTP2_REFUSED_STREAM
-

(7) +

(0x07) REFUSED_STREAM

NGHTTP2_CANCEL
-

(8) +

(0x08) CANCEL

NGHTTP2_COMPRESSION_ERROR
-

(9) +

(0x09) COMPRESSION_ERROR

NGHTTP2_CONNECT_ERROR
-

(10) +

(0x0a) CONNECT_ERROR

NGHTTP2_ENHANCE_YOUR_CALM
-

(11) +

(0x0b) ENHANCE_YOUR_CALM

NGHTTP2_INADEQUATE_SECURITY
-

(12) +

(0x0c) INADEQUATE_SECURITY

@@ -882,13 +862,6 @@ No flag set.

Indicates EOF was sensed.

-
-
-NGHTTP2_DATA_FLAG_COMPRESSED
-

(0x02) -Indicates data was compressed by application.

-
-
@@ -1101,10 +1074,6 @@ 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 NGHTTP2_DATA_FLAG_EOF flag in *data_flags.

-

To send compressed data payload without affecting content-length, -set NGHTTP2_DATA_FLAG_COMPRESSED flag in *data_flags. -Compression must be done by application prior to fill data in -buf.

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 NGHTTP2_ERR_DEFERRED without reading @@ -1407,73 +1376,78 @@ int32_t window_size_increment

-
-nghttp2_altsvc
-

The ALTSVC frame. It has following members:

+
+nghttp2_extension
+

The extension frame. It has following members:

-
-nghttp2_frame_hd hd
+
+nghttp2_frame_hd hd

The frame header.

-
-uint8_t *protocol_id
-

Protocol ID

-
- -
-
-uint8_t *host
-

Host

-
- -
-
-uint8_t *origin
-

Origin

-
- -
-
-size_t protocol_id_len
-

The length of protocol_id

-
- -
-
-size_t host_len
-

The length of host

-
- -
-
-size_t origin_len
-

The length of origin

-
- -
-
-uint32_t max_age
-

Max-Age

-
- -
-
-uint16_t port
-

Port

+
+void *payload
+

The pointer to extension payload. The exact pointer type is +determined by hd.type.

+

If hd.type == NGHTTP2_EXT_ALTSVC, it is a pointer to +nghttp2_ext_altsvc.

+

If hd.type == NGHTTP2_EXT_BLOCKED, it points to NULL, +since BLOCKED extension frame has no payload.

-
-nghttp2_blocked
-

The BLOCKED frame. It has following members:

+
+nghttp2_ext_altsvc
+

The ALTSVC extension frame payload. It has following members:

-
-nghttp2_frame_hd hd
-

The frame header.

+
+uint8_t *protocol_id
+

Protocol ID

+
+ +
+
+uint8_t *host
+

Host

+
+ +
+
+uint8_t *origin
+

Origin

+
+ +
+
+size_t protocol_id_len
+

The length of protocol_id

+
+ +
+
+size_t host_len
+

The length of host

+
+ +
+
+size_t origin_len
+

The length of origin

+
+ +
+
+uint32_t max_age
+

Max-Age

+
+ +
+
+uint16_t port
+

Port

@@ -1545,15 +1519,9 @@ from here because the library deals with it internally.

-
-nghttp2_altsvc altsvc
-

The ALTSVC frame.

-
- -
-
-nghttp2_blocked blocked
-

The BLOCKED frame.

+
+nghttp2_extension ext
+

The extension frame.

@@ -2213,9 +2181,6 @@ is invoked. invalid, nghttp2_session_callbacks.on_invalid_frame_recv_callback is invoked. -
  • If the received frame type is unknown, -nghttp2_session_callbacks.on_unknown_frame_recv_callback -is invoked.
    • @@ -2395,13 +2360,11 @@ local endpoint can send without WINDOW_UPDATE.

    int nghttp2_session_terminate_session(nghttp2_session *session, nghttp2_error_code error_code)

    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 -nghttp2_session_want_read() and nghttp2_session_want_write() -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.

    +

    The last stream ID is the ID of a stream for which +nghttp2_on_frame_recv_callback was called most recently.

    +

    The error_code is the error code of this GOAWAY frame.

    +

    After the transmission, both nghttp2_session_want_read() and +nghttp2_session_want_write() return 0.

    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.

    @@ -2413,10 +2376,27 @@ negative error codes:

    +
    +
    +int nghttp2_session_terminate_session2(nghttp2_session *session, int32_t last_stream_id, nghttp2_error_code error_code)
    +

    Signals the session so that the connection should be terminated.

    +

    This function behaves like nghttp2_session_terminate_session(), +but the last stream ID can be specified by the application for fine +grained control of stream.

    +

    This function returns 0 if it succeeds, or one of the following +negative error codes:

    +
    +
    NGHTTP2_ERR_NOMEM
    +
    Out of memory.
    +
    +
    +
    uint32_t nghttp2_session_get_remote_settings(nghttp2_session *session, nghttp2_settings_id id)
    -

    Returns the value of SETTINGS id notified by a remote endpoint.

    +

    Returns the value of SETTINGS id notified by a remote endpoint. +The id must be one of values defined in +nghttp2_settings_id.

    @@ -2590,6 +2570,8 @@ negative error codes:

    NGHTTP2_ERR_NOMEM
    Out of memory.
    +
    NGHTTP2_ERR_INVALID_ARGUMENT
    +
    The stream_id is 0.
    @@ -2644,6 +2626,8 @@ succeeds, or one of the following negative error codes:

    NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE
    No stream ID is available because maximum stream ID was reached.
    +
    NGHTTP2_ERR_INVALID_ARGUMENT
    +
    The stream_id is 0.

    Warning

    @@ -2672,6 +2656,8 @@ negative error codes:

    Out of memory.
    NGHTTP2_ERR_DATA_EXIST
    DATA has been already submitted and not fully processed yet.
    +
    NGHTTP2_ERR_INVALID_ARGUMENT
    +
    The stream_id is 0.
    @@ -2697,7 +2683,8 @@ negative error codes:

    NGHTTP2_ERR_NOMEM
    Out of memory.
    NGHTTP2_ERR_INVALID_ARGUMENT
    -
    The pri_spec is NULL; or trying to depend on itself.
    +
    The stream_id is 0; or the pri_spec is NULL; or trying to +depend on itself.
    @@ -2713,6 +2700,8 @@ negative error codes:

    NGHTTP2_ERR_NOMEM
    Out of memory.
    +
    NGHTTP2_ERR_INVALID_ARGUMENT
    +
    The stream_id is 0.
    @@ -2780,6 +2769,8 @@ client.
    NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE
    No stream ID is available because maximum stream ID was reached.
    +
    NGHTTP2_ERR_INVALID_ARGUMENT
    +
    The stream_id is 0.

    Warning

    @@ -2813,8 +2804,9 @@ negative error codes:

    -int nghttp2_submit_goaway(nghttp2_session *session, uint8_t flags, nghttp2_error_code error_code, const uint8_t *opaque_data, size_t opaque_data_len)
    -

    Submits GOAWAY frame with the error code error_code.

    +int nghttp2_submit_goaway(nghttp2_session *session, uint8_t flags, int32_t last_stream_id, nghttp2_error_code error_code, const uint8_t *opaque_data, size_t opaque_data_len) +

    Submits GOAWAY frame with the last stream ID last_stream_id and +the error code error_code.

    The flags is currently ignored and should be NGHTTP2_FLAG_NONE.

    If the opaque_data is not NULL and opaque_data_len is not @@ -2823,12 +2815,17 @@ 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 opaque_data_len is 0, the opaque_data could be NULL.

    +

    To shutdown gracefully, first send GOAWAY with last_stream_id = +(1u << 31) - 1. After 1 RTT, call either +nghttp2_submit_goaway(), nghttp2_session_terminate_session() or +nghttp2_session_terminate_session2(). The latter 2 will close +HTTP/2 session immediately after transmission of the frame.

    This function returns 0 if it succeeds, or one of the following negative error codes:

    NGHTTP2_ERR_NOMEM
    Out of memory.
    -
    NGHTTP2_ERR_INVALID_ARGUMENT
    +
    NGHTTP2_ERR_INVALID_ARGUMENT
    The opaque_data_len is too large.
    @@ -3229,7 +3226,7 @@ always succeeds.

    @@ -275,66 +275,10 @@ -
    NGHTTP2_ALTSVC (C macro) -
    - - -
    nghttp2_altsvc (C type) -
    - - -
    nghttp2_altsvc.hd (C member) -
    - - -
    nghttp2_altsvc.host (C member) -
    - - -
    nghttp2_altsvc.host_len (C member) -
    - - -
    nghttp2_altsvc.max_age (C member) -
    - - -
    nghttp2_altsvc.origin (C member) -
    - - -
    nghttp2_altsvc.origin_len (C member) -
    - - -
    nghttp2_altsvc.port (C member) -
    - - -
    nghttp2_altsvc.protocol_id (C member) -
    - - -
    nghttp2_altsvc.protocol_id_len (C member) -
    - -
    nghttp2_before_frame_send_callback (C type)
    -
    NGHTTP2_BLOCKED (C macro) -
    - - -
    nghttp2_blocked (C type) -
    - - -
    nghttp2_blocked.hd (C member) -
    - -
    NGHTTP2_CANCEL (C macro)
    @@ -399,10 +343,6 @@ -
    NGHTTP2_DATA_FLAG_COMPRESSED (C macro) -
    - -
    NGHTTP2_DATA_FLAG_EOF (C macro)
    @@ -583,6 +523,66 @@ +
    NGHTTP2_EXT_ALTSVC (C macro) +
    + + +
    nghttp2_ext_altsvc (C type) +
    + + +
    nghttp2_ext_altsvc.host (C member) +
    + + +
    nghttp2_ext_altsvc.host_len (C member) +
    + + +
    nghttp2_ext_altsvc.max_age (C member) +
    + + +
    nghttp2_ext_altsvc.origin (C member) +
    + + +
    nghttp2_ext_altsvc.origin_len (C member) +
    + + +
    nghttp2_ext_altsvc.port (C member) +
    + + +
    nghttp2_ext_altsvc.protocol_id (C member) +
    + + +
    nghttp2_ext_altsvc.protocol_id_len (C member) +
    + + +
    NGHTTP2_EXT_BLOCKED (C macro) +
    + + +
    nghttp2_ext_frame_type (C type) +
    + + +
    nghttp2_extension (C type) +
    + + +
    nghttp2_extension.hd (C member) +
    + + +
    nghttp2_extension.payload (C member) +
    + +
    nghttp2_flag (C type)
    @@ -591,10 +591,6 @@ -
    NGHTTP2_FLAG_COMPRESSED (C macro) -
    - -
    NGHTTP2_FLAG_END_HEADERS (C macro)
    @@ -611,11 +607,7 @@ -
    NGHTTP2_FLAG_PAD_HIGH (C macro) -
    - - -
    NGHTTP2_FLAG_PAD_LOW (C macro) +
    NGHTTP2_FLAG_PADDED (C macro)
    @@ -631,18 +623,14 @@ -
    nghttp2_frame.altsvc (C member) -
    - - -
    nghttp2_frame.blocked (C member) -
    - -
    nghttp2_frame.data (C member)
    +
    nghttp2_frame.ext (C member) +
    + +
    nghttp2_frame.goaway (C member)
    @@ -862,12 +850,12 @@
    nghttp2_info (C type)
    - -
    nghttp2_info.age (C member)
    +
    +
    nghttp2_info.proto_str (C member)
    @@ -1293,6 +1281,10 @@ +
    nghttp2_session_terminate_session2 (C function) +
    + +
    nghttp2_session_upgrade (C function)
    @@ -1325,10 +1317,6 @@ -
    NGHTTP2_SETTINGS_COMPRESS_DATA (C macro) -
    - -
    NGHTTP2_SETTINGS_ENABLE_PUSH (C macro)
    @@ -1357,10 +1345,6 @@ -
    NGHTTP2_SETTINGS_MAX (C macro) -
    - -
    NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS (C macro)
    @@ -1561,7 +1545,7 @@ @@ -179,7 +179,7 @@