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.
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.
Version number of the nghttp2 library release
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.
The protocol version identification of this library supports.
The length of NGHTTP2_PROTO_VERSION_ID.
The age of nghttp2_info
The default priority value
The lowest priority value
The maximum window size
The initial window size for stream level flow control.
The initial window size for connection level flow control.
The client connection header.
The length of NGHTTP2_CLIENT_CONNECTION_HEADER.
Default maximum concurrent streams.
Error codes used in this library. The code range is [-999, -500], inclusive. The following values are defined:
(-501) Invalid argument passed.
(-503) The specified protocol version is not supported.
(-504) Used as a return value from nghttp2_send_callback and nghttp2_recv_callback to indicate that the operation would block.
(-505) General protocol error
(-506) The frame is invalid.
(-507) The peer performed a shutdown on the connection.
(-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.
(-509) Stream ID has reached the maximum value. Therefore no stream ID is available.
(-510) The stream is already closed; or the stream ID is invalid.
(-511) RST_STREAM has been added to the outbound queue. The stream is in closing state.
(-512) The transmission is not allowed for this stream (e.g., a frame with END_STREAM flag set has already sent).
(-513) The stream ID is invalid.
(-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).
(-515) Another DATA frame has already been deferred.
(-516) Starting new stream is not allowed. (e.g., GOAWAY has been sent and/or received.
(-517) GOAWAY has already been sent.
(-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).
(-519) Indicates that the context is not suitable to perform the requested operation.
(-520) The gzip error.
(-521) The user callback function failed due to the temporal error.
(-522) The length of the frame is too large.
(-523) Header block inflate/deflate error.
(-524) Flow control error
(-525) Insufficient buffer size given to function.
(-526) Callback was paused by the application
(-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).
(-901) Out of memory. This is a fatal error.
(-902) The user callback function failed. This is a fatal error.
The control frame types in HTTP/2.0.
(0) The DATA frame.
(1) The HEADERS frame.
(2) The PRIORITY frame.
(3) The RST_STREAM frame.
(4) The SETTINGS frame.
(5) The PUSH_PROMISE frame.
(6) The PING frame.
(7) The GOAWAY frame.
(9) The WINDOW_UPDATE frame.
The flags for HTTP/2.0 frames. This enum defines all flags for frames, assuming that the same flag name has the same mask.
(0) No flag set.
(0x1) The END_STREAM flag.
(0x4) The END_HEADERS flag.
(0x8) The PRIORITY flag.
(0x4) The END_PUSH_PROMISE flag.
(0x1) The PONG flag.
The SETTINGS ID.
(4) SETTINGS_MAX_CONCURRENT_STREAMS
(7) SETTINGS_INITIAL_WINDOW_SIZE
(10) SETTINGS_FLOW_CONTROL_OPTIONS
(10) Maximum ID of nghttp2_settings_id.
The status codes for the RST_STREAM and GOAWAY frames.
(0) No errors.
(1) PROTOCOL_ERROR
(2) INTERNAL_ERROR
(3) FLOW_CONTROL_ERROR
(5) STREAM_CLOSED
(6) FRAME_TOO_LARGE
(7) REFUSED_STREAM
(8) CANCEL
(9) COMPRESSION_ERROR
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.
(0) The HEADERS frame is opening new stream, which is analogous to SYN_STREAM in SPDY.
(1) The HEADERS frame is the first response headers, which is analogous to SYN_REPLY in SPDY.
(2) The HEADERS frame is the first headers sent against reserved stream.
(3) The HEADERS frame which does not apply for the above categories, which is analogous to HEADERS in SPDY.
Configuration options for nghttp2_session.
(1) This option prevents the library from sending WINDOW_UPDATE for a stream automatically. If this option is set, the application is responsible for sending WINDOW_UPDATE using nghttp2_submit_window_update().
(2) This option prevents the library from sending WINDOW_UPDATE for a connection automatically. If this option is set, the application is responsible for sending WINDOW_UPDATE with stream ID 0 using nghttp2_submit_window_update().
(3) 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.
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.
This struct is what nghttp2_version() returns. It holds information about the particular nghttp2 version.
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
the NGHTTP2_VERSION_NUM number (since age ==1)
points to the NGHTTP2_VERSION string (since age ==1)
points to the NGHTTP2_PROTO_VERSION_ID string this instance implements (since age ==1)
The name/value pair, which mainly used to represent header fields.
The name byte string, which is not necessarily NULL terminated.
The value byte string, which is not necessarily NULL terminated.
The length of the name.
The length of the value.
The frame header.
The length field of this frame, excluding frame header.
The type of this frame. See nghttp2_frame().
The flags.
The stream identifier (aka, stream ID)
This union represents the some kind of data source passed to nghttp2_data_source_read_callback.
The integer field, suitable for a file descriptor.
The pointer to an arbitrary object.
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.
This struct represents the data source and the way to read a chunk of data from it.
The data source.
The callback function to read a chunk of data from the source.
The HEADERS frame. It has the following members:
The frame header.
The priority.
The name/value pairs.
The number of name/value pairs in nva.
The PRIORITY frame. It has the following members:
The frame header.
The priority.
The RST_STREAM frame. It has the following members:
The frame header.
The error code. See nghttp2_error_code.
The SETTINGS ID/Value pair. It has the following members:
The SETTINGS ID. See nghttp2_settings_id.
The value of this entry.
The SETTINGS frame. It has the following members:
The frame header.
The number of SETTINGS ID/Value pairs in iv.
The pointer to the array of SETTINGS ID/Value pair.
The PUSH_PROMISE frame. It has the following members:
The frame header.
The promised stream ID
The name/value pairs.
The number of name/value pairs in nva.
The PING frame. It has the following members:
The frame header.
The opaque data
The GOAWAY frame. It has the following members:
The frame header.
The last stream stream ID.
The error code. See nghttp2_error_code.
The additional debug data
The length of opaque_data member.
The WINDOW_UPDATE frame. It has the following members:
The frame header.
The window size increment.
This union includes all frames to pass them to various function calls as nghttp2_frame type. The DATA frame is intentionally omitted from here.
The frame header, which is convenient to inspect frame header.
The HEADERS frame.
The PRIORITY frame.
The RST_STREAM frame.
The SETTINGS frame.
The PUSH_PROMISE frame.
The PING frame.
The GOAWAY frame.
The WINDOW_UPDATE frame.
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().
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().
Callback function invoked by nghttp2_session_recv() when a non-DATA frame is received. The user_data pointer is the third argument passed in to the call to nghttp2_session_client_new() or nghttp2_session_server_new().
If 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 frame parameter is retained until nghttp2_session_continue() is called. The application must retain the input bytes which was used to produce the frame parameter, because it may refer to the memory region included in the input bytes. The application which returns NGHTTP2_ERR_PAUSE must call nghttp2_session_continue() before nghttp2_session_mem_recv().
The implementation of this function must return 0 if it succeeds. It may return NGHTTP2_ERR_PAUSE. If the other nonzero value is returned, it is treated as fatal error and nghttp2_session_recv() and nghttp2_session_send() functions immediately return NGHTTP2_ERR_CALLBACK_FAILURE.
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().
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.
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_data_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 frame parameter is retained until nghttp2_session_continue() is called. The application must retain the input bytes which was used to produce the frame parameter, because it may refer to the memory region included in the input bytes. The application which returns NGHTTP2_ERR_PAUSE must call nghttp2_session_continue() before nghttp2_session_mem_recv().
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.
Callback function invoked when DATA frame is received. The actual data it contains are received by nghttp2_on_data_chunk_recv_callback. 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.
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.
Callback function invoked after the non-DATA 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.
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.
Callback function invoked after DATA 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.
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.
Callback function invoked when the request from the remote peer is received. In other words, the frame with END_STREAM flag set is received. In HTTP, this means HTTP request, including request body, is fully received. 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.
Callback function invoked when the received control frame octets could not be parsed correctly. The type indicates the type of received non-DATA frame. 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 lib_error_code is one of the error code defined in nghttp2_error and indicates the 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.
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.
Callback functions.
Callback function invoked when the session wants to send data to the remote peer.
Callback function invoked when the session wants to receive data from the remote peer.
Callback function invoked by nghttp2_session_recv() when a non-DATA frame is received.
Callback function invoked by nghttp2_session_recv() when an invalid non-DATA frame is received.
Callback function invoked when a chunk of data in DATA frame is received.
Callback function invoked when DATA frame is received.
Callback function invoked before the non-DATA frame is sent.
Callback function invoked after the non-DATA frame is sent.
The callback function invoked when a non-DATA frame is not sent because of an error.
Callback function invoked after DATA frame is sent.
Callback function invoked when the stream is closed.
Callback function invoked when request from the remote peer is received.
Callback function invoked when the received non-DATA frame octets could not be parsed correctly.
Callback function invoked when the received frame type is unknown.
The gzip stream to inflate data. The details of this structure are intentionally hidden from the public API.
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:
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:
Frees any resources allocated for session. If session is NULL, this function does nothing.
Sets the configuration option for the session. The optname is one of nghttp2_opt. The optval is the pointer to the option value and the optlen is the size of *optval. The required type of optval varies depending on the optname. See below.
The following optname are supported:
This function returns 0 if it succeeds, or one of the following negative error codes:
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:
This function returns 0 if it succeeds, or one of the following negative error codes:
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:
- 2.1. 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.
- 2.2. If one DATA frame is completely received,
- nghttp2_session_callbacks.on_data_recv_callback is invoked. If the frame is the final frame of the request, nghttp2_session_callbacks.on_request_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.
- 3.1. nghttp2_session_callbacks.recv_callback is invoked
- one or more times to receive whole frame.
- 3.2. If the received frame is valid,
- nghttp2_session_callbacks.on_ctrl_recv_callback is invoked. If the frame is the final frame of the request, nghttp2_session_callbacks.on_request_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.
- 3.3. If the received frame is unpacked but is interpreted as
- invalid, nghttp2_session_callbacks.on_invalid_ctrl_recv_callback is invoked.
- 3.4. If the received frame could not be unpacked correctly,
- nghttp2_session_callbacks.on_ctrl_recv_parse_error_callback is invoked.
- 3.5. If the received frame type is unknown,
- nghttp2_session_callbacks.on_unknown_ctrl_recv_callback is invoked.
This function returns 0 if it succeeds, or one of the following negative error codes:
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_frame_recv_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:
Perform post-processing after nghttp2_session_mem_recv() was paused by NGHTTP2_ERR_PAUSE from nghttp2_session_callbacks.on_frame_recv_callback or nghttp2_session_callbacks.on_data_chunk_recv_callback.
This function frees resources associated with paused frames. It may also call additional callbacks, such as nghttp2_session_callbacks.on_stream_close_callback.
If this function succeeds, the application can call nghttp2_session_mem_recv() again.
This function returns 0 if it succeeds, or one of the following negative error codes:
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:
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.
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.
Returns stream_user_data for the stream stream_id. The stream_user_data is provided by nghttp2_submit_request() or nghttp2_submit_syn_stream(). If the stream is initiated by the remote endpoint, stream_user_data is always NULL. If the stream is initiated by the local endpoint and NULL is given in nghttp2_submit_request() or nghttp2_submit_syn_stream(), then this function returns NULL. If the stream does not exist, this function returns NULL.
Returns the number of frames in the outbound queue. This does not include the deferred DATA frames.
Submits GOAWAY frame with the given error_code.
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:
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:
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:
Returns string describing the lib_error_code. The lib_error_code must be one of the nghttp2_error.
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 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 pointer to the value string. The one beyond last value must be NULL. That is, if the nv contains N name/value pairs, nv[2*N] must be NULL.
The nv must include following name/value pairs:
This function creates copies of all name/value pairs in nv. It also lower-cases all names in nv.
The string in nv must be NULL-terminated. Use nghttp2_submit_request2() if name/value pairs are not NULL-terminated strings.
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 nv (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_ctrl_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:
Just like nghttp2_submit_request(), but this function takes the nva, which is an array of nghttp2_nv with nvlen elements, as name/value pairs. This function is useful if name/value pairs are not NULL-terminated strings.
This function returns 0 if it succeeds, or one of the following negative error codes:
Submits response HEADERS frame and optionally one or more DATA frames against the stream stream_id.
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 pointer to the value string. The one beyond last value must be NULL. That is, if the nv contains N name/value pairs, nv[2*N] must be NULL.
The nv must include following name/value pairs:
This function creates copies of all name/value pairs in nv. It also lower-cases all names in nv.
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 function returns 0 if it succeeds, or one of the following negative error codes:
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 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 pointer to the value string. The one beyond last value must be NULL. That is, if the nv contains N name/value pairs, nv[2*N] must be NULL.
This function creates copies of all name/value pairs in nv. It also lower-cases all names in nv.
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:
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:
Submits PRIORITY frame to change the priority of stream stream_id to the priority value pri.
This function returns 0 if it succeeds, or one of the following negative error codes:
Submits RST_STREAM frame to cancel/reject the stream stream_id with the error code error_code.
This function returns 0 if it succeeds, or one of the following negative error codes:
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.
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.
This function returns 0 if it succeeds, or one of the following negative error codes:
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 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 pointer to the value string. The one beyond last value must be NULL. That is, if the nv contains N name/value pairs, nv[2*N] must be NULL.
This function creates copies of all name/value pairs in nv. It also lower-cases all names in nv.
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.
This function returns 0 if it succeeds, or one of the following negative error codes:
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.
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:
Submits GOAWAY frame with the error code error_code.
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:
Submits WINDOW_UPDATE frame.
The flags is currently ignored.
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.
This function returns 0 if it succeeds, or one of the following negative error codes:
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.
A helper function for dealing with NPN in client side. The in contains server’s protocol 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:
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.
See http://technotes.googlecode.com/git/nextprotoneg.html for more details about 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);
Note that the HTTP/2.0 spec does use ALPN instead of NPN. This function is provided for transitional period before ALPN is got implemented in major SSL/TLS libraries.
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:
Frees the inflate stream. The inflater may be NULL.
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:
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;
}
....
}
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.