API ReferenceΒΆ
+IncludesΒΆ
+To use the public APIs, include nghttp2/nghttp2.h:
+#include <nghttp2/nghttp2.h>
+The header files are also available online: nghttp2.h and +nghttp2ver.h.
+RemarksΒΆ
+Do not call nghttp2_session_send(), nghttp2_session_recv() or +nghttp2_session_mem_recv() from the nghttp2 callback functions +directly or indirectly. It will lead to the crash. You can submit +requests or frames in the callbacks then call nghttp2_session_send(), +nghttp2_session_recv() or nghttp2_session_mem_recv() outside of the +callbacks.
+MacrosΒΆ
+-
+
- +NGHTTP2_VERSIONΒΆ +
Version number of the nghttp2 library release
+
-
+
- +NGHTTP2_VERSION_NUMΒΆ +
Numerical representation of the version number of the nghttp2 library +release. This is a 24 bit number with 8 bits for major number, 8 bits +for minor and 8 bits for patch. Version 1.2.3 becomes 0x010203.
+
-
+
- +NGHTTP2_PROTO_VERSION_IDΒΆ +
The protocol version identification of this library supports.
+
-
+
- +NGHTTP2_PROTO_VERSION_ID_LENΒΆ +
The length of NGHTTP2_PROTO_VERSION_ID.
+
-
+
- +NGHTTP2_VERSION_AGEΒΆ +
The age of nghttp2_info
+
-
+
- +NGHTTP2_PRI_DEFAULTΒΆ +
The default priority value
+
-
+
- +NGHTTP2_PRI_LOWESTΒΆ +
The lowest priority value
+
-
+
- +NGHTTP2_MAX_WINDOW_SIZEΒΆ +
The maximum window size
+
-
+
- +NGHTTP2_INITIAL_WINDOW_SIZEΒΆ +
The initial window size for stream level flow control.
+
-
+
- +NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZEΒΆ +
The initial window size for connection level flow control.
+
-
+
- +NGHTTP2_MAX_HEADER_TABLE_SIZEΒΆ +
The maximum header table size.
+
-
+
- +NGHTTP2_CLIENT_CONNECTION_HEADERΒΆ +
The client connection header.
+
-
+
- +NGHTTP2_CLIENT_CONNECTION_HEADER_LENΒΆ +
The length of NGHTTP2_CLIENT_CONNECTION_HEADER.
+
-
+
- +NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMSΒΆ +
Default maximum concurrent streams.
+
EnumsΒΆ
+-
+
- +nghttp2_errorΒΆ +
Error codes used in this library. The code range is [-999, -500], +inclusive. The following values are defined:
+-
+
- +NGHTTP2_ERR_INVALID_ARGUMENTΒΆ +
(-501) +Invalid argument passed.
+
-
+
- +NGHTTP2_ERR_UNSUPPORTED_VERSIONΒΆ +
(-503) +The specified protocol version is not supported.
+
-
+
- +NGHTTP2_ERR_WOULDBLOCKΒΆ +
(-504) +Used as a return value from nghttp2_send_callback and +nghttp2_recv_callback to indicate that the operation +would block.
+
-
+
- +NGHTTP2_ERR_PROTOΒΆ +
(-505) +General protocol error
+
-
+
- +NGHTTP2_ERR_INVALID_FRAMEΒΆ +
(-506) +The frame is invalid.
+
-
+
- +NGHTTP2_ERR_EOFΒΆ +
(-507) +The peer performed a shutdown on the connection.
+
-
+
- +NGHTTP2_ERR_DEFERREDΒΆ +
(-508) +Used as a return value from +nghttp2_data_source_read_callback() to indicate that data +transfer is postponed. See +nghttp2_data_source_read_callback() for details.
+
-
+
- +NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLEΒΆ +
(-509) +Stream ID has reached the maximum value. Therefore no stream ID +is available.
+
-
+
- +NGHTTP2_ERR_STREAM_CLOSEDΒΆ +
(-510) +The stream is already closed; or the stream ID is invalid.
+
-
+
- +NGHTTP2_ERR_STREAM_CLOSINGΒΆ +
(-511) +RST_STREAM has been added to the outbound queue. The stream is in +closing state.
+
-
+
- +NGHTTP2_ERR_STREAM_SHUT_WRΒΆ +
(-512) +The transmission is not allowed for this stream (e.g., a frame +with END_STREAM flag set has already sent).
+
-
+
- +NGHTTP2_ERR_INVALID_STREAM_IDΒΆ +
(-513) +The stream ID is invalid.
+
-
+
- +NGHTTP2_ERR_INVALID_STREAM_STATEΒΆ +
(-514) +The state of the stream is not valid (e.g., DATA cannot be sent +to the stream if response HEADERS has not been sent).
+
-
+
- +NGHTTP2_ERR_DEFERRED_DATA_EXISTΒΆ +
(-515) +Another DATA frame has already been deferred.
+
-
+
- +NGHTTP2_ERR_START_STREAM_NOT_ALLOWEDΒΆ +
(-516) +Starting new stream is not allowed. (e.g., GOAWAY has been sent +and/or received.
+
-
+
- +NGHTTP2_ERR_GOAWAY_ALREADY_SENTΒΆ +
(-517) +GOAWAY has already been sent.
+
-
+
- +NGHTTP2_ERR_INVALID_HEADER_BLOCKΒΆ +
(-518) +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_STATEΒΆ +
(-519) +Indicates that the context is not suitable to perform the +requested operation.
+
-
+
- +NGHTTP2_ERR_GZIPΒΆ +
(-520) +The gzip error.
+
-
+
- +NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILUREΒΆ +
(-521) +The user callback function failed due to the temporal error.
+
-
+
- +NGHTTP2_ERR_FRAME_SIZE_ERRORΒΆ +
(-522) +The length of the frame is invalid, either too large or too small.
+
-
+
- +NGHTTP2_ERR_HEADER_COMPΒΆ +
(-523) +Header block inflate/deflate error.
+
-
+
- +NGHTTP2_ERR_FLOW_CONTROLΒΆ +
(-524) +Flow control error
+
-
+
- +NGHTTP2_ERR_INSUFF_BUFSIZEΒΆ +
(-525) +Insufficient buffer size given to function.
+
-
+
- +NGHTTP2_ERR_PAUSEΒΆ +
(-526) +Callback was paused by the application
+
-
+
- +NGHTTP2_ERR_TOO_MANY_INFLIGHT_SETTINGSΒΆ +
(-527) +There are too many in-flight SETTING frame and no more +transmission of SETTINGS is allowed.
+
-
+
- +NGHTTP2_ERR_PUSH_DISABLEDΒΆ +
(-528) +The server push is disabled.
+
-
+
- +NGHTTP2_ERR_FATALΒΆ +
(-900) +The errors < NGHTTP2_ERR_FATAL mean that the library is +under unexpected condition and cannot process any further data +reliably (e.g., out of memory).
+
-
+
- +NGHTTP2_ERR_NOMEMΒΆ +
(-901) +Out of memory. This is a fatal error.
+
-
+
- +NGHTTP2_ERR_CALLBACK_FAILUREΒΆ +
(-902) +The user callback function failed. This is a fatal error.
+
-
+
- +nghttp2_frame_typeΒΆ +
The control frame types in HTTP/2.0.
+-
+
- +NGHTTP2_DATAΒΆ +
(0) +The DATA frame.
+
-
+
- +NGHTTP2_HEADERSΒΆ +
(1) +The HEADERS frame.
+
-
+
- +NGHTTP2_PRIORITYΒΆ +
(2) +The PRIORITY frame.
+
-
+
- +NGHTTP2_RST_STREAMΒΆ +
(3) +The RST_STREAM frame.
+
-
+
- +NGHTTP2_SETTINGSΒΆ +
(4) +The SETTINGS frame.
+
-
+
- +NGHTTP2_PUSH_PROMISEΒΆ +
(5) +The PUSH_PROMISE frame.
+
-
+
- +NGHTTP2_PINGΒΆ +
(6) +The PING frame.
+
-
+
- +NGHTTP2_GOAWAYΒΆ +
(7) +The GOAWAY frame.
+
-
+
- +NGHTTP2_WINDOW_UPDATEΒΆ +
(9) +The WINDOW_UPDATE frame.
+
-
+
- +NGHTTP2_CONTINUATIONΒΆ +
(10) +The CONTINUATION frame.
+
-
+
- +nghttp2_flagΒΆ +
The flags for HTTP/2.0 frames. This enum defines all flags for +frames, assuming that the same flag name has the same mask.
+-
+
- +NGHTTP2_FLAG_NONEΒΆ +
(0) +No flag set.
+
-
+
- +NGHTTP2_FLAG_END_STREAMΒΆ +
(0x1) +The END_STREAM flag.
+
-
+
- +NGHTTP2_FLAG_END_HEADERSΒΆ +
(0x4) +The END_HEADERS flag.
+
-
+
- +NGHTTP2_FLAG_PRIORITYΒΆ +
(0x8) +The PRIORITY flag.
+
-
+
- +NGHTTP2_FLAG_END_PUSH_PROMISEΒΆ +
(0x4) +The END_PUSH_PROMISE flag.
+
-
+
- +NGHTTP2_FLAG_ACKΒΆ +
(0x1) +The ACK flag.
+
-
+
- +nghttp2_settings_idΒΆ +
The SETTINGS ID.
+-
+
- +NGHTTP2_SETTINGS_HEADER_TABLE_SIZEΒΆ +
(1) +SETTINGS_HEADER_TABLE_SIZE
+
-
+
- +NGHTTP2_SETTINGS_ENABLE_PUSHΒΆ +
(2) +SETTINGS_ENABLE_PUSH
+
-
+
- +NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMSΒΆ +
(4) +SETTINGS_MAX_CONCURRENT_STREAMS
+
-
+
- +NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZEΒΆ +
(7) +SETTINGS_INITIAL_WINDOW_SIZE
+
-
+
- +NGHTTP2_SETTINGS_FLOW_CONTROL_OPTIONSΒΆ +
(10) +SETTINGS_FLOW_CONTROL_OPTIONS
+
-
+
- +NGHTTP2_SETTINGS_MAXΒΆ +
(10) +Maximum ID of nghttp2_settings_id.
+
-
+
- +nghttp2_error_codeΒΆ +
The status codes for the RST_STREAM and GOAWAY frames.
+-
+
- +NGHTTP2_NO_ERRORΒΆ +
(0) +No errors.
+
-
+
- +NGHTTP2_PROTOCOL_ERRORΒΆ +
(1) +PROTOCOL_ERROR
+
-
+
- +NGHTTP2_INTERNAL_ERRORΒΆ +
(2) +INTERNAL_ERROR
+
-
+
- +NGHTTP2_FLOW_CONTROL_ERRORΒΆ +
(3) +FLOW_CONTROL_ERROR
+
-
+
- +NGHTTP2_SETTINGS_TIMEOUTΒΆ +
(4) +SETTINGS_TIMEOUT
+
-
+
- +NGHTTP2_STREAM_CLOSEDΒΆ +
(5) +STREAM_CLOSED
+
-
+
- +NGHTTP2_FRAME_SIZE_ERRORΒΆ +
(6) +FRAME_SIZE_ERROR
+
-
+
- +NGHTTP2_REFUSED_STREAMΒΆ +
(7) +REFUSED_STREAM
+
-
+
- +NGHTTP2_CANCELΒΆ +
(8) +CANCEL
+
-
+
- +NGHTTP2_COMPRESSION_ERRORΒΆ +
(9) +COMPRESSION_ERROR
+
-
+
- +NGHTTP2_CONNECT_ERRORΒΆ +
(10) +CONNECT_ERROR
+
-
+
- +NGHTTP2_ENHANCE_YOUR_CALMΒΆ +
(420) +ENHANCE_YOUR_CALM
+
-
+
- +nghttp2_headers_categoryΒΆ +
The category of HEADERS, which indicates the role of the frame. In +HTTP/2.0 spec, request, response, push response and other arbitrary +headers (e.g., trailers) are all called just HEADERS. To give the +application the role of incoming HEADERS frame, we define several +categories.
+-
+
- +NGHTTP2_HCAT_REQUESTΒΆ +
(0) +The HEADERS frame is opening new stream, which is analogous to +SYN_STREAM in SPDY.
+
-
+
- +NGHTTP2_HCAT_RESPONSEΒΆ +
(1) +The HEADERS frame is the first response headers, which is +analogous to SYN_REPLY in SPDY.
+
-
+
- +NGHTTP2_HCAT_PUSH_RESPONSEΒΆ +
(2) +The HEADERS frame is the first headers sent against reserved +stream.
+
-
+
- +NGHTTP2_HCAT_HEADERSΒΆ +
(3) +The HEADERS frame which does not apply for the above categories, +which is analogous to HEADERS in SPDY.
+
-
+
- +nghttp2_optΒΆ +
Configuration options for nghttp2_session.
+-
+
- +NGHTTP2_OPT_NO_AUTO_STREAM_WINDOW_UPDATEΒΆ +
(1) +This option prevents the library from sending WINDOW_UPDATE for a +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 +zero.
+
-
+
- +NGHTTP2_OPT_NO_AUTO_CONNECTION_WINDOW_UPDATEΒΆ +
(1 << 1) +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.
+
-
+
- +NGHTTP2_OPT_PEER_MAX_CONCURRENT_STREAMSΒΆ +
(1 << 2) +This option sets the SETTINGS_MAX_CONCURRENT_STREAMS value of +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 +SETTINGS_MAX_CONCURRENT_STREAMS from the remote endpoint.
+
Types (structs, unions and typedefs)ΒΆ
+-
+
- +nghttp2_sessionΒΆ +
The primary structure to hold the resources needed for a HTTP/2.0 +session. The details of this structure are intentionally hidden +from the public API.
+
-
+
- +nghttp2_infoΒΆ +
This struct is what nghttp2_version() returns. It holds +information about the particular nghttp2 version.
+-
+
- +int ageΒΆ +
Age of this struct. This instance of nghttp2 sets it to +NGHTTP2_VERSION_AGE but a future version may bump it and +add more struct fields at the bottom
+
-
+
- +int version_numΒΆ +
the NGHTTP2_VERSION_NUM number (since age ==1)
+
-
+
- +const char *version_strΒΆ +
points to the NGHTTP2_VERSION string (since age ==1)
+
-
+
- +const char *proto_strΒΆ +
points to the NGHTTP2_PROTO_VERSION_ID string this +instance implements (since age ==1)
+
-
+
- +nghttp2_nvΒΆ +
The name/value pair, which mainly used to represent header fields.
+-
+
- +uint8_t *nameΒΆ +
The name byte string, which is not necessarily NULL +terminated.
+
-
+
- +uint8_t *valueΒΆ +
The value byte string, which is not necessarily NULL +terminated.
+
-
+
- +uint16_t namelenΒΆ +
The length of the name.
+
-
+
- +uint16_t valuelenΒΆ +
The length of the value.
+
-
+
- +nghttp2_frame_hdΒΆ +
The frame header.
+-
+
- +size_t lengthΒΆ +
The length field of this frame, excluding frame header.
+
-
+
- +int32_t stream_idΒΆ +
The stream identifier (aka, stream ID)
+
-
+
- +uint8_t typeΒΆ +
The type of this frame. See nghttp2_frame().
+
-
+
- +uint8_t flagsΒΆ +
The flags.
+
-
+
- +nghttp2_data_sourceΒΆ +
This union represents the some kind of data source passed to +nghttp2_data_source_read_callback.
+-
+
- +int fdΒΆ +
The integer field, suitable for a file descriptor.
+
-
+
- +void *ptrΒΆ +
The pointer to an arbitrary object.
+
-
+
- +typedef ssize_t (*nghttp2_data_source_read_callback)(nghttp2_session *session, int32_t stream_id, uint8_t *buf, size_t length, int *eof, nghttp2_data_source *source, void *user_data)ΒΆ +
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 *eof to 1. 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 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 +NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE will close the stream +by issuing RST_STREAM with NGHTTP2_INTERNAL_ERROR. +Returning NGHTTP2_ERR_CALLBACK_FAILURE will signal the +entire session failure.
+
-
+
- +nghttp2_data_providerΒΆ +
This struct represents the data source and the way to read a chunk +of data from it.
+-
+
- +nghttp2_data_source sourceΒΆ +
The data source.
+
-
+
- +nghttp2_data_source_read_callback read_callbackΒΆ +
The callback function to read a chunk of data from the source.
+
-
+
- +nghttp2_dataΒΆ +
The DATA frame. The received data is delivered via +nghttp2_on_data_chunk_recv_callback.
+
-
+
- +nghttp2_headersΒΆ +
The HEADERS frame. It has the following members:
+-
+
- +nghttp2_frame_hd hdΒΆ +
The frame header.
+
-
+
- +nghttp2_nv *nvaΒΆ +
The name/value pairs.
+
-
+
- +size_t nvlenΒΆ +
The number of name/value pairs in nva.
+
-
+
- +nghttp2_headers_category catΒΆ +
The category of this HEADERS frame.
+
-
+
- +int32_t priΒΆ +
The priority.
+
-
+
- +nghttp2_priorityΒΆ +
The PRIORITY frame. It has the following members:
+-
+
- +nghttp2_frame_hd hdΒΆ +
The frame header.
+
-
+
- +int32_t priΒΆ +
The priority.
+
-
+
- +nghttp2_rst_streamΒΆ +
The RST_STREAM frame. It has the following members:
+-
+
- +nghttp2_frame_hd hdΒΆ +
The frame header.
+
-
+
- +nghttp2_error_code error_codeΒΆ +
The error code. See nghttp2_error_code.
+
-
+
- +nghttp2_settings_entryΒΆ +
The SETTINGS ID/Value pair. It has the following members:
+-
+
- +int32_t settings_idΒΆ +
The SETTINGS ID. See nghttp2_settings_id.
+
-
+
- +uint32_t valueΒΆ +
The value of this entry.
+
-
+
- +nghttp2_settingsΒΆ +
The SETTINGS frame. It has the following members:
+-
+
- +nghttp2_frame_hd hdΒΆ +
The frame header.
+
-
+
- +size_t nivΒΆ +
The number of SETTINGS ID/Value pairs in iv.
+
-
+
- +nghttp2_settings_entry *ivΒΆ +
The pointer to the array of SETTINGS ID/Value pair.
+
-
+
- +nghttp2_push_promiseΒΆ +
The PUSH_PROMISE frame. It has the following members:
+-
+
- +nghttp2_frame_hd hdΒΆ +
The frame header.
+
-
+
- +nghttp2_nv *nvaΒΆ +
The name/value pairs.
+
-
+
- +size_t nvlenΒΆ +
The number of name/value pairs in nva.
+
-
+
- +int32_t promised_stream_idΒΆ +
The promised stream ID
+
-
+
- +nghttp2_pingΒΆ +
The PING frame. It has the following members:
+-
+
- +nghttp2_frame_hd hdΒΆ +
The frame header.
+
-
+
- +uint8_t opaque_data[8] +
The opaque data
+
-
+
- +nghttp2_goawayΒΆ +
The GOAWAY frame. It has the following members:
+-
+
- +nghttp2_frame_hd hdΒΆ +
The frame header.
+
-
+
- +int32_t last_stream_idΒΆ +
The last stream stream ID.
+
-
+
- +nghttp2_error_code error_codeΒΆ +
The error code. See nghttp2_error_code.
+
-
+
- +uint8_t *opaque_dataΒΆ +
The additional debug data
+
-
+
- +size_t opaque_data_lenΒΆ +
The length of opaque_data member.
+
-
+
- +nghttp2_window_updateΒΆ +
The WINDOW_UPDATE frame. It has the following members:
+-
+
- +nghttp2_frame_hd hdΒΆ +
The frame header.
+
-
+
- +int32_t window_size_incrementΒΆ +
The window size increment.
+
-
+
- +nghttp2_frameΒΆ +
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.
+-
+
- +nghttp2_frame_hd hdΒΆ +
The frame header, which is convenient to inspect frame header.
+
-
+
- +nghttp2_data dataΒΆ +
The DATA frame.
+
-
+
- +nghttp2_headers headersΒΆ +
The HEADERS frame.
+
-
+
- +nghttp2_priority priorityΒΆ +
The PRIORITY frame.
+
-
+
- +nghttp2_rst_stream rst_streamΒΆ +
The RST_STREAM frame.
+
-
+
- +nghttp2_settings settingsΒΆ +
The SETTINGS frame.
+
-
+
- +nghttp2_push_promise push_promiseΒΆ +
The PUSH_PROMISE frame.
+
-
+
- +nghttp2_ping pingΒΆ +
The PING frame.
+
-
+
- +nghttp2_goaway goawayΒΆ +
The GOAWAY frame.
+
-
+
- +nghttp2_window_update window_updateΒΆ +
The WINDOW_UPDATE frame.
+
-
+
- +typedef ssize_t (*nghttp2_send_callback)(nghttp2_session *session, const uint8_t *data, size_t length, int flags, void *user_data)ΒΆ +
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 +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 NGHTTP2_ERR_WOULDBLOCK. For other errors, it +must return 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().
+
-
+
- +typedef ssize_t (*nghttp2_recv_callback)(nghttp2_session *session, uint8_t *buf, size_t length, int flags, void *user_data)ΒΆ +
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 NGHTTP2_ERR_WOULDBLOCK. If +it gets EOF before it reads any single byte, it must return +NGHTTP2_ERR_EOF. For other errors, it must return +NGHTTP2_ERR_CALLBACK_FAILURE. Returning 0 is treated as +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().
+
-
+
- +typedef int (*nghttp2_on_frame_recv_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)ΒΆ +
Callback function invoked by nghttp2_session_recv() when a aframe +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 +nghttp2_on_header_callback.
+For HEADERS, PUSH_PROMISE and DATA frames, this callback may be +called after stream is closed (see +nghttp2_on_stream_close_callback). The application should +check that stream is still alive using its own stream management or +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 +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 NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +typedef int (*nghttp2_on_invalid_frame_recv_callback)(nghttp2_session *session, const nghttp2_frame *frame, nghttp2_error_code error_code, void *user_data)ΒΆ +
Callback function invoked by nghttp2_session_recv() when an +invalid non-DATA frame is received. The error_code is one of the +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 +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 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 NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +typedef int (*nghttp2_on_data_chunk_recv_callback)(nghttp2_session *session, uint8_t flags, int32_t stream_id, const uint8_t *data, size_t len, void *user_data)ΒΆ +
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 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 +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 +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 +nghttp2_session_recv() and nghttp2_session_mem_recv() functions +immediately return NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +typedef int (*nghttp2_before_frame_send_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)ΒΆ +
Callback function invoked before the non-DATA frame frame is +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 +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 +nghttp2_session_recv() and nghttp2_session_send() functions +immediately return NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +typedef int (*nghttp2_on_frame_send_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)ΒΆ +
Callback function invoked after the frame frame is sent. 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 +nghttp2_session_recv() and nghttp2_session_send() functions +immediately return NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +typedef int (*nghttp2_on_frame_not_send_callback)(nghttp2_session *session, const nghttp2_frame *frame, int lib_error_code, void *user_data)ΒΆ +
Callback function invoked after the non-DATA frame frame is not +sent because of the error. The error is indicated by the +lib_error_code, which is one of the values defined in +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 +nghttp2_session_recv() and nghttp2_session_send() functions +immediately return NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +typedef int (*nghttp2_on_stream_close_callback)(nghttp2_session *session, int32_t stream_id, nghttp2_error_code error_code, void *user_data)ΒΆ +
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 +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 +nghttp2_session_recv() and nghttp2_session_send() functions +immediately return NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +typedef int (*nghttp2_on_unknown_frame_recv_callback)(nghttp2_session *session, const uint8_t *head, size_t headlen, const uint8_t *payload, size_t payloadlen, void *user_data)ΒΆ +
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 +nghttp2_session_recv() and nghttp2_session_send() functions +immediately return NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +typedef int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)ΒΆ +
Callback function invoked when the reception of header block in +HEADERS or PUSH_PROMISE is started. Each header name/value pair +will be emitted by nghttp2_on_header_callback.
+The frame->hd.flags may not have +NGHTTP2_FLAG_END_HEADERS flag set, which indicates that one +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 +NGHTTP2_ERR_CALLBACK_FAILURE. If nonzero value other than +NGHTTP2_ERR_CALLBACK_FAILURE is returned, it is treated as +if NGHTTP2_ERR_CALLBACK_FAILURE is returned. If +NGHTTP2_ERR_CALLBACK_FAILURE is returned, +nghttp2_session_mem_recv() function will immediately return +NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +typedef int (*nghttp2_on_header_callback)(nghttp2_session *session, const nghttp2_frame *frame, const uint8_t *name, size_t namelen, const uint8_t *value, size_t valuelen, void *user_data)ΒΆ +
Callback function invoked when a header name/value pair is received +for the frame. When this callback is invoked, frame->hd.type +is either NGHTTP2_HEADERS or NGHTTP2_PUSH_PROMISE. +After all header name/value pairs are processed with this callback, +and no error has been detected, +nghttp2_on_frame_recv_callback will be invoked. If there +is an error in decompression, +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 +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 +namelen could be 0, and/or the value contains 0x0a or +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 +concatenation is used in order to keep the ordering of headers.
+If the application uses nghttp2_session_mem_recv(), it can return +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.
+Returning NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE will close +the stream by issuing RST_STREAM with +NGHTTP2_INTERNAL_ERROR. In this case, +nghttp2_on_frame_recv_callback will not be invoked.
+The implementation of this function must return 0 if it +succeeds. It may return NGHTTP2_ERR_PAUSE or +NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE. For other critical +failures, it must return NGHTTP2_ERR_CALLBACK_FAILURE. If +the other nonzero value is returned, it is treated as +NGHTTP2_ERR_CALLBACK_FAILURE. If +NGHTTP2_ERR_CALLBACK_FAILURE is returned, +nghttp2_session_recv() and nghttp2_session_mem_recv() functions +immediately return NGHTTP2_ERR_CALLBACK_FAILURE.
+
-
+
- +nghttp2_session_callbacksΒΆ +
Callback functions.
+-
+
- +nghttp2_send_callback send_callbackΒΆ +
Callback function invoked when the session wants to send data +to the remote peer.
+
-
+
- +nghttp2_recv_callback recv_callbackΒΆ +
Callback function invoked when the session wants to receive +data from the remote peer.
+
-
+
- +nghttp2_on_frame_recv_callback on_frame_recv_callbackΒΆ +
Callback function invoked by nghttp2_session_recv() when a +frame is received.
+
-
+
- +nghttp2_on_invalid_frame_recv_callback on_invalid_frame_recv_callbackΒΆ +
Callback function invoked by nghttp2_session_recv() when an +invalid non-DATA frame is received.
+
-
+
- +nghttp2_on_data_chunk_recv_callback on_data_chunk_recv_callbackΒΆ +
Callback function invoked when a chunk of data in DATA frame is +received.
+
-
+
- +nghttp2_before_frame_send_callback before_frame_send_callbackΒΆ +
Callback function invoked before a non-DATA frame is sent.
+
-
+
- +nghttp2_on_frame_send_callback on_frame_send_callbackΒΆ +
Callback function invoked after a frame is sent.
+
-
+
- +nghttp2_on_frame_not_send_callback on_frame_not_send_callbackΒΆ +
The callback function invoked when a non-DATA frame is not sent +because of an error.
+
-
+
- +nghttp2_on_stream_close_callback on_stream_close_callbackΒΆ +
Callback function invoked when the stream is closed.
+
-
+
- +nghttp2_on_unknown_frame_recv_callback on_unknown_frame_recv_callbackΒΆ +
Callback function invoked when the received frame type is +unknown.
+
-
+
- +nghttp2_on_begin_headers_callback on_begin_headers_callbackΒΆ +
Callback function invoked when the reception of header block in +HEADERS or PUSH_PROMISE is started.
+
-
+
- +nghttp2_on_header_callback on_header_callbackΒΆ +
Callback function invoked when a header name/value pair is +received.
+
-
+
- +nghttp2_opt_setΒΆ +
Struct to store option values for nghttp2_session.
+-
+
- +uint32_t peer_max_concurrent_streamsΒΆ +
- +
-
+
- +uint8_t no_auto_stream_window_updateΒΆ +
- +
-
+
- +uint8_t no_auto_connection_window_updateΒΆ +
- +
-
+
- +nghttp2_gzipΒΆ +
The gzip stream to inflate data. The details of this structure are +intentionally hidden from the public API.
+
FunctionsΒΆ
+-
+
- +int nghttp2_session_client_new(nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks, void *user_data)ΒΆ +
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 +supplied data, which will be passed to the callback functions.
+The nghttp2_session_callbacks.send_callback must be +specified. If the application code uses nghttp2_session_recv(), +the nghttp2_session_callbacks.recv_callback must be +specified. The other members of callbacks can be NULL.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_session_server_new(nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks, void *user_data)ΒΆ +
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 +supplied data, which will be passed to the callback functions.
+The nghttp2_session_callbacks.send_callback must be +specified. If the application code uses nghttp2_session_recv(), +the nghttp2_session_callbacks.recv_callback must be +specified. The other members of callbacks can be NULL.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_session_client_new2(nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks, void *user_data, uint32_t opt_set_mask, const nghttp2_opt_set *opt_set)ΒΆ +
Like nghttp2_session_client_new(), but with additional options +specified in the opt_set. The caller must set bitwise-OR of +nghttp2_opt for given options. For example, if it +specifies NGHTTP2_OPT_NO_AUTO_CONNECTION_WINDOW_UPDATE and +NGHTTP2_OPT_PEER_MAX_CONCURRENT_STREAMS in the opt_set, +the opt_set_mask should be +NGHTTP2_OPT_NO_AUTO_CONNECTION_WINDOW_UPDATE | +NGHTTP2_OPT_PEER_MAX_CONCURRENT_STREAMS.
+If the opt_set_mask is 0, the opt_set could be NULL safely +and the call is equivalent to nghttp2_session_client_new().
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_session_server_new2(nghttp2_session **session_ptr, const nghttp2_session_callbacks *callbacks, void *user_data, uint32_t opt_set_mask, const nghttp2_opt_set *opt_set)ΒΆ +
Like nghttp2_session_server_new(), but with additional options +specified in the opt_set. The caller must set bitwise-OR of +nghttp2_opt for given options. For example, if it +specifies NGHTTP2_OPT_NO_AUTO_CONNECTION_WINDOW_UPDATE and +NGHTTP2_OPT_PEER_MAX_CONCURRENT_STREAMS in the opt_set, +the opt_set_mask should be +NGHTTP2_OPT_NO_AUTO_CONNECTION_WINDOW_UPDATE | +NGHTTP2_OPT_PEER_MAX_CONCURRENT_STREAMS.
+If the opt_set_mask is 0, the opt_set could be NULL safely +and the call is equivalent to nghttp2_session_server_new().
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +void nghttp2_session_del(nghttp2_session *session)ΒΆ +
Frees any resources allocated for session. If session is +NULL, this function does nothing.
+
-
+
- +int nghttp2_session_send(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 +many as possible until the user callback +nghttp2_session_callbacks.send_callback returns +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 +which tells when each callback is invoked:
+-
+
- Get the next frame to send from outbound queue. +
- Prepare transmission of the frame. +
- If the control frame cannot be sent because some preconditions +are not met (e.g., request HEADERS cannot be sent after +GOAWAY), +nghttp2_session_callbacks.on_frame_not_send_callback is +invoked. Abort the following steps. +
- If the frame is request HEADERS, the stream is opened +here. +
- nghttp2_session_callbacks.before_frame_send_callback is +invoked. +
- nghttp2_session_callbacks.send_callback is invoked one +or more times to send the frame. +
- nghttp2_session_callbacks.on_frame_send_callback is +invoked. +
- If the transmission of the frame triggers closure of the stream, +the stream is closed and +nghttp2_session_callbacks.on_stream_close_callback is +invoked. +
This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
- NGHTTP2_ERR_CALLBACK_FAILURE +
- The callback function failed. +
-
+
- +int nghttp2_session_recv(nghttp2_session *session)ΒΆ +
Receives frames from the remote peer.
+This function receives as many frames as possible until the user +callback nghttp2_session_callbacks.recv_callback returns +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 +callback is invoked:
+-
+
- nghttp2_session_callbacks.recv_callback is invoked one +or more times to receive frame header. +
- If the frame is DATA frame:
-
+
- nghttp2_session_callbacks.recv_callback is invoked +to receive DATA payload. For each chunk of data, +nghttp2_session_callbacks.on_data_chunk_recv_callback +is invoked. +
- If one DATA frame is completely received, +nghttp2_session_callbacks.on_frame_recv_callback is +invoked. If the reception of the frame triggers the +closure of the stream, +nghttp2_session_callbacks.on_stream_close_callback +is invoked. +
+ - If the frame is the control frame:
-
+
- nghttp2_session_callbacks.recv_callback is invoked +one or more times to receive whole frame. +
- If the received frame is valid, then following actions are +taken. If the frame is either HEADERS or PUSH_PROMISE, +nghttp2_session_callbacks.on_begin_headers_callback +is invoked. Then +nghttp2_session_callbacks.on_header_callback is +invoked for each header name/value pair. After all name/value +pairs are emitted successfully, +nghttp2_session_callbacks.on_frame_recv_callback is +invoked. For other frames, +nghttp2_session_callbacks.on_frame_recv_callback is +invoked. +If the reception of the frame triggers the closure of the +stream, +nghttp2_session_callbacks.on_stream_close_callback +is invoked. +
- If the received frame is unpacked but is interpreted as +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. +
+
This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_EOF +
- The remote peer did shutdown on the connection. +
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
- NGHTTP2_ERR_CALLBACK_FAILURE +
- The callback function failed. +
-
+
- +ssize_t nghttp2_session_mem_recv(nghttp2_session *session, const uint8_t *in, size_t inlen)ΒΆ +
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 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 +other callbacks are called in the same way as they are in +nghttp2_session_recv().
+In the current implementation, this function always tries to +processes all input data unless either an error occurs or +NGHTTP2_ERR_PAUSE is returned from +nghttp2_session_callbacks.on_header_callback or +nghttp2_session_callbacks.on_data_chunk_recv_callback. +If NGHTTP2_ERR_PAUSE is used, the return value includes the +number of bytes which was used to produce the data or frame for the +callback.
+This function returns the number of processed bytes, or one of the +following negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
- NGHTTP2_ERR_CALLBACK_FAILURE +
- The callback function failed. +
-
+
- +int nghttp2_session_resume_data(nghttp2_session *session, int32_t stream_id)ΒΆ +
Puts back previously deferred DATA frame in the stream stream_id +to the outbound queue.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_INVALID_ARGUMENT +
- The stream does not exist or no deferred data exist. +
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_session_want_read(nghttp2_session *session)ΒΆ +
Returns nonzero value if session wants to receive data from the +remote peer.
+If both nghttp2_session_want_read() and +nghttp2_session_want_write() return 0, the application should +drop the connection.
+
-
+
- +int nghttp2_session_want_write(nghttp2_session *session)ΒΆ +
Returns nonzero value if session wants to send data to the remote +peer.
+If both nghttp2_session_want_read() and +nghttp2_session_want_write() return 0, the application should +drop the connection.
+
-
+
- +void* nghttp2_session_get_stream_user_data(nghttp2_session *session, int32_t stream_id)ΒΆ +
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(), 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.
+
-
+
- +int nghttp2_session_set_stream_user_data(nghttp2_session *session, int32_t stream_id, void *stream_user_data)ΒΆ +
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 +NULL in the stream_user_data, which nullifies the associated +data pointer.
+It is valid to set the stream_user_data to the stream reserved by +PUSH_PROMISE frame.
+This function returns 0 if it succeeds, or one of following +negative error codes:
+-
+
- NGHTTP2_ERR_INVALID_ARGUMENT +
- The stream does not exist +
-
+
- +size_t nghttp2_session_get_outbound_queue_size(nghttp2_session *session)ΒΆ +
Returns the number of frames in the outbound queue. This does not +include the deferred DATA frames.
+
-
+
- +int32_t nghttp2_session_get_stream_effective_recv_data_length(nghttp2_session *session, int32_t stream_id)ΒΆ +
Returns the number of DATA payload in bytes received without +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 +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.
+If flow control is disabled for that stream, this function returns +0.
+This function returns -1 if it fails.
+
-
+
- +int32_t nghttp2_session_get_stream_effective_local_window_size(nghttp2_session *session, int32_t stream_id)ΒΆ +
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.
+
-
+
- +int32_t nghttp2_session_get_effective_recv_data_length(nghttp2_session *session)ΒΆ +
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.
+If flow control is disabled for a connection, this function returns +0.
+This function returns -1 if it fails.
+
-
+
- +int32_t nghttp2_session_get_effective_local_window_size(nghttp2_session *session)ΒΆ +
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.
+
-
+
- +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.
+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.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_session_upgrade(nghttp2_session *session, const uint8_t *settings_payload, size_t settings_payloadlen, void *stream_user_data)ΒΆ +
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.
+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 +opened stream becomes half-closed (remote).
+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 +
- The settings_payload is badly formed. +
- NGHTTP2_ERR_PROTO +
- The stream ID 1 is already used or closed; or is not available; +or the settings_payload does not include both +NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS and +NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE. +
-
+
- +ssize_t nghttp2_pack_settings_payload(uint8_t *buf, size_t buflen, const nghttp2_settings_entry *iv, size_t 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 +SETTINGS payload to be sent with the HTTP2-Settings header +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 +of the following negative error codes:
+-
+
- NGHTTP2_ERR_INVALID_ARGUMENT +
- The iv contains duplicate settings ID or invalid value. +
- NGHTTP2_ERR_INSUFF_BUFSIZE +
- The provided buflen size is too small to hold the output. +
-
+
- +const char* nghttp2_strerror(int lib_error_code)ΒΆ +
Returns string describing the lib_error_code. The +lib_error_code must be one of the nghttp2_error.
+
-
+
- +int nghttp2_submit_request(nghttp2_session *session, int32_t pri, const nghttp2_nv *nva, size_t nvlen, const nghttp2_data_provider *data_prd, void *stream_user_data)ΒΆ +
Submits HEADERS frame and optionally one or more DATA frames.
+The pri is priority of this request. 0 is the highest priority +value and NGHTTP2_PRI_LOWEST is the lowest value.
+The nva is an array of name/value pair nghttp2_nv with +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.0 specification has requirement about header fields in the +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 +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 +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().
+Since the library reorders the frames and tries to send the highest +prioritized one first and the HTTP/2.0 specification requires the +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 +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.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_INVALID_ARGUMENT +
- The pri is invalid +
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_submit_response(nghttp2_session *session, int32_t stream_id, const nghttp2_nv *nva, size_t nvlen, const nghttp2_data_provider *data_prd)ΒΆ +
Submits response HEADERS frame and optionally one or more DATA +frames against the stream stream_id.
+The nva is an array of name/value pair nghttp2_nv with +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.0 specification has requirement about header fields in the +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 +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 function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_submit_headers(nghttp2_session *session, uint8_t flags, int32_t stream_id, int32_t pri, const nghttp2_nv *nva, size_t nvlen, void *stream_user_data)ΒΆ +
Submits HEADERS frame. The flags is bitwise OR of the +following values:
+ +If flags includes NGHTTP2_FLAG_END_STREAM, this frame has +END_STREAM flag set. The library does not support header +continuation and the HEADERS frame always has +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., +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 is priority of this request.
+The nva is an array of name/value pair nghttp2_nv with +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.
+This function creates copies of all name/value pairs in nva. It +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.
+This function is low-level in a sense that the application code can +specify flags directly. For usual HTTP request, +nghttp2_submit_request() is useful.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_INVALID_ARGUMENT +
- The pri is invalid +
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_submit_data(nghttp2_session *session, uint8_t flags, int32_t stream_id, const nghttp2_data_provider *data_prd)ΒΆ +
Submits one or more DATA frames to the stream stream_id. The +data to be sent are provided by data_prd. If flags contains +NGHTTP2_FLAG_END_STREAM, the last DATA frame has END_STREAM +flag set.
+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 +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_submit_priority(nghttp2_session *session, uint8_t flags, int32_t stream_id, int32_t pri)ΒΆ +
Submits PRIORITY frame to change the priority of stream stream_id +to the priority value pri.
+The flags is currently ignored and should be +NGHTTP2_FLAG_NONE.
+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 +
- The pri is negative. +
-
+
- +int nghttp2_submit_rst_stream(nghttp2_session *session, uint8_t flags, int32_t stream_id, nghttp2_error_code error_code)ΒΆ +
Submits RST_STREAM frame to cancel/reject the stream stream_id +with the error code error_code.
+The flags is currently ignored and should be +NGHTTP2_FLAG_NONE.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_submit_settings(nghttp2_session *session, uint8_t flags, const nghttp2_settings_entry *iv, size_t niv)ΒΆ +
Stores local settings and submits SETTINGS frame. The iv is the +pointer to the array of nghttp2_settings_entry. The niv +indicates the number of nghttp2_settings_entry.
+The flags is currently ignored and should be +NGHTTP2_FLAG_NONE.
+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 +size becomes strictly larger than NGHTTP2_MAX_WINDOW_SIZE, +RST_STREAM is issued against such a stream.
+SETTINGS with NGHTTP2_FLAG_ACK is automatically submitted +by the library and application could not send it at its will.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_INVALID_ARGUMENT +
- The iv contains invalid value (e.g., attempting to re-enable +flow control). +
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_submit_push_promise(nghttp2_session *session, uint8_t flags, int32_t stream_id, const nghttp2_nv *nva, size_t nvlen)ΒΆ +
Submits PUSH_PROMISE frame. The flags is currently ignored and +the resulting PUSH_PROMISE frame always has +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 nva is an array of name/value pair nghttp2_nv with +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.
+This function creates copies of all name/value pairs in nva. It +also lower-cases all names in nva.
+Since the library reorders the frames and tries to send the highest +prioritized one first and the HTTP/2.0 specification requires the +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 +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.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_submit_ping(nghttp2_session *session, uint8_t flags, uint8_t *opaque_data)ΒΆ +
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 +NGHTTP2_FLAG_NONE.
+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 +be sent as opaque data.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_submit_goaway(nghttp2_session *session, uint8_t flags, nghttp2_error_code error_code, uint8_t *opaque_data, size_t opaque_data_len)ΒΆ +
Submits GOAWAY frame with 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 +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 +opaque_data_len is 0, the opaque_data could be NULL.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_submit_window_update(nghttp2_session *session, uint8_t flags, int32_t stream_id, int32_t window_size_increment)ΒΆ +
Submits WINDOW_UPDATE frame.
+The flags is currently ignored and should be +NGHTTP2_FLAG_NONE.
+If the window_size_increment is positive, the WINDOW_UPDATE with +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.
+If the window_size_increment is negative, the local window size +is decreased by -window_size_increment. If +NGHTTP2_OPT_NO_AUTO_STREAM_WINDOW_UPDATE (or +NGHTTP2_OPT_NO_AUTO_CONNECTION_WINDOW_UPDATE if stream_id +is 0) is not set and the library decided that the WINDOW_UPDATE +should be submitted, then WINDOW_UPDATE is queued with the current +received bytes count.
+If the window_size_increment is 0, the function does nothing and +returns 0.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_FLOW_CONTROL +
- The local window size overflow or gets negative. +
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +int nghttp2_nv_compare_name(const nghttp2_nv *lhs, const nghttp2_nv *rhs)ΒΆ +
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.
+
-
+
- +int nghttp2_select_next_protocol(unsigned char **out, unsigned char *outlen, const unsigned char *in, unsigned int inlen)ΒΆ +
A helper function for dealing with NPN in client side or ALPN in +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:
+++in[0] = 17 +in[1..17] = "HTTP-draft-04/2.0" +in[18] = 8 +in[19..26] = "http/1.1" +inlen = 27 +
The selection algorithm is as follows:
+-
+
- If peer’s list contains HTTP/2.0 protocol the library supports, +it is selected and returns 1. The following step is not taken. +
- If peer’s list contains http/1.1, this function selects +http/1.1 and returns 0. The following step is not taken. +
- 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.
+For ALPN, refer to +http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-04
+See http://technotes.googlecode.com/git/nextprotoneg.html for more +details about NPN.
+For NPN, to use this method you should do something like:
+++static int select_next_proto_cb(SSL* ssl, + unsigned char **out, + unsigned char *outlen, + const unsigned char *in, + unsigned int inlen, + void *arg) +{ + int rv; + rv = nghttp2_select_next_protocol(out, outlen, in, inlen); + if(rv == 1) { + ((MyType*)arg)->http2_selected = 1; + } + return SSL_TLSEXT_ERR_OK; +} +... +SSL_CTX_set_next_proto_select_cb(ssl_ctx, select_next_proto_cb, my_obj); +
-
+
- +int nghttp2_gzip_inflate_new(nghttp2_gzip **inflater_ptr)ΒΆ +
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:
+-
+
- NGHTTP2_ERR_GZIP +
- The initialization of gzip stream failed. +
- NGHTTP2_ERR_NOMEM +
- Out of memory. +
-
+
- +void nghttp2_gzip_inflate_del(nghttp2_gzip *inflater)ΒΆ +
Frees the inflate stream. The inflater may be NULL.
+
-
+
- +int nghttp2_gzip_inflate(nghttp2_gzip *inflater, uint8_t *out, size_t *outlen_ptr, const uint8_t *in, size_t *inlen_ptr)ΒΆ +
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 +the number of data written in out. Similarly, *inlen_ptr is +updated to represent the number of input bytes processed.
+This function returns 0 if it succeeds, or one of the following +negative error codes:
+-
+
- NGHTTP2_ERR_GZIP +
- The inflation of gzip stream failed. +
The example follows:
+++void on_data_chunk_recv_callback(nghttp2_session *session, + uint8_t flags, + int32_t stream_id, + const uint8_t *data, size_t len, + void *user_data) +{ + ... + req = nghttp2_session_get_stream_user_data(session, stream_id); + nghttp2_gzip *inflater = req->inflater; + while(len > 0) { + uint8_t out[MAX_OUTLEN]; + size_t outlen = MAX_OUTLEN; + size_t tlen = len; + int rv; + rv = nghttp2_gzip_inflate(inflater, out, &outlen, data, &tlen); + if(rv != 0) { + nghttp2_submit_rst_stream(session, stream_id, + NGHTTP2_INTERNAL_ERROR); + break; + } + ... Do stuff ... + data += tlen; + len -= tlen; + } + .... +} +
-
+
- +nghttp2_info *nghttp2_version(int least_version)ΒΆ +
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.
+
-
+
- +int nghttp2_is_fatal(int lib_error)ΒΆ +
Returns nonzero if the nghttp2_error library error code +lib_error is fatal.
+
-
+
- +int nghttp2_check_header_name(const uint8_t *name, size_t len)ΒΆ +
Returns nonzero if HTTP header field name name of length len is +valid according to +http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2
+Because this is a header field name in HTTP2, the upper cased alphabet +is treated as error.
+
-
+
- +int nghttp2_check_header_value(const uint8_t *value, size_t len)ΒΆ +
Returns nonzero if HTTP header field value value of length len +is valid according to +http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-25#section-3.2
+Because this is HTTP2 header field value, it can contain NULL +character (0x00).
+