walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity
nghttp2/lib/includes/nghttp2/nghttp2.h

2133 lines
63 KiB
C
Raw Blame History

/*
* nghttp2 - HTTP/2.0 C Library
*
* Copyright (c) 2012 Tatsuhiro Tsujikawa
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
* LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
#ifndef NGHTTP2_H
#define NGHTTP2_H
#ifdef __cplusplus
extern "C" {
#endif
#include <stdlib.h>
#include <stdint.h>
#include <sys/types.h>
#include <nghttp2/nghttp2ver.h>
struct nghttp2_session;
/**
* @struct
*
* The primary structure to hold the resources needed for a SPDY
* session. The details of this structure are intentionally hidden
* from the public API.
*/
typedef struct nghttp2_session nghttp2_session;
/**
* @enum
*
* The SPDY protocol version.
*/
typedef enum {
/**
* SPDY protocol version 2
*/
NGHTTP2_PROTO_SPDY2 = 2,
/**
* SPDY protocol version 3
*/
NGHTTP2_PROTO_SPDY3 = 3
} nghttp2_proto_version;
/**
* @enum
*
* Error codes used in the Spdylay library. The code range is [-999,
* -500], inclusive. The following values are defined:
*/
typedef enum {
/**
* Invalid argument passed.
*/
NGHTTP2_ERR_INVALID_ARGUMENT = -501,
/**
* Zlib error.
*/
NGHTTP2_ERR_ZLIB = -502,
/**
* The specified protocol version is not supported.
*/
NGHTTP2_ERR_UNSUPPORTED_VERSION = -503,
/**
* Used as a return value from :type:`nghttp2_send_callback` and
* :type:`nghttp2_recv_callback` to indicate that the operation
* would block.
*/
NGHTTP2_ERR_WOULDBLOCK = -504,
/**
* General protocol error
*/
NGHTTP2_ERR_PROTO = -505,
/**
* The frame is invalid.
*/
NGHTTP2_ERR_INVALID_FRAME = -506,
/**
* The peer performed a shutdown on the connection.
*/
NGHTTP2_ERR_EOF = -507,
/**
* Used as a return value from
* :func:`nghttp2_data_source_read_callback` to indicate that data
* transfer is postponed. See
* :func:`nghttp2_data_source_read_callback` for details.
*/
NGHTTP2_ERR_DEFERRED = -508,
/**
* Stream ID has reached the maximum value. Therefore no stream ID
* is available.
*/
NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE = -509,
/**
* The stream is already closed; or the stream ID is invalid.
*/
NGHTTP2_ERR_STREAM_CLOSED = -510,
/**
* RST_STREAM has been added to the outbound queue. The stream is in
* closing state.
*/
NGHTTP2_ERR_STREAM_CLOSING = -511,
/**
* The transmission is not allowed for this stream (e.g., a frame
* with FLAG_FIN flag set has already sent).
*/
NGHTTP2_ERR_STREAM_SHUT_WR = -512,
/**
* The stream ID is invalid.
*/
NGHTTP2_ERR_INVALID_STREAM_ID = -513,
/**
* The state of the stream is not valid (e.g., SYN_REPLY cannot be
* sent to the stream if SYN_REPLY has already been sent).
*/
NGHTTP2_ERR_INVALID_STREAM_STATE = -514,
/**
* Another DATA frame has already been deferred.
*/
NGHTTP2_ERR_DEFERRED_DATA_EXIST = -515,
/**
* SYN_STREAM is not allowed. (e.g., GOAWAY has been sent and/or
* received.
*/
NGHTTP2_ERR_SYN_STREAM_NOT_ALLOWED = -516,
/**
* GOAWAY has already been sent.
*/
NGHTTP2_ERR_GOAWAY_ALREADY_SENT = -517,
/**
* The received frame contains the invalid header block. (e.g.,
* There are duplicate header names; or the header names are not
* encoded in US-ASCII character set and not lower cased; or the
* header name is zero-length string; or the header value contains
* multiple in-sequence NUL bytes).
*/
NGHTTP2_ERR_INVALID_HEADER_BLOCK = -518,
/**
* Indicates that the context is not suitable to perform the
* requested operation.
*/
NGHTTP2_ERR_INVALID_STATE = -519,
/**
* The gzip error.
*/
NGHTTP2_ERR_GZIP = -520,
/**
* The user callback function failed due to the temporal error.
*/
NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE = -521,
/**
* The length of the frame is too large.
*/
NGHTTP2_ERR_FRAME_TOO_LARGE = -522,
/**
* The errors < :enum:`NGHTTP2_ERR_FATAL` mean that the library is
* under unexpected condition and cannot process any further data
* reliably (e.g., out of memory).
*/
NGHTTP2_ERR_FATAL = -900,
/**
* Out of memory. This is a fatal error.
*/
NGHTTP2_ERR_NOMEM = -901,
/**
* The user callback function failed. This is a fatal error.
*/
NGHTTP2_ERR_CALLBACK_FAILURE = -902
} nghttp2_error;
typedef enum {
NGHTTP2_MSG_MORE
} nghttp2_io_flag;
/**
* @enum
* The control frame types in SPDY protocol.
*/
typedef enum {
/**
* The SYN_STREAM control frame.
*/
NGHTTP2_SYN_STREAM = 1,
/**
* The SYN_REPLY control frame.
*/
NGHTTP2_SYN_REPLY = 2,
/**
* The RST_STREAM control frame.
*/
NGHTTP2_RST_STREAM = 3,
/**
* The SETTINGS control frame.
*/
NGHTTP2_SETTINGS = 4,
/**
* The NOOP control frame. This was deprecated in SPDY/3.
*/
NGHTTP2_NOOP = 5,
/**
* The PING control frame.
*/
NGHTTP2_PING = 6,
/**
* The GOAWAY control frame.
*/
NGHTTP2_GOAWAY = 7,
/**
* The HEADERS control frame.
*/
NGHTTP2_HEADERS = 8,
/**
* The WINDOW_UPDATE control frame. This first appeared in SPDY/3.
*/
NGHTTP2_WINDOW_UPDATE = 9,
/**
* The CREDENTIAL control frame. This first appeared in SPDY/3.
*/
NGHTTP2_CREDENTIAL = 10
} nghttp2_frame_type;
/**
* @enum
*
* The flags for a control frame.
*/
typedef enum {
/**
* No flag set.
*/
NGHTTP2_CTRL_FLAG_NONE = 0,
/**
* FLAG_FIN flag.
*/
NGHTTP2_CTRL_FLAG_FIN = 0x1,
/**
* FLAG_UNIDIRECTIONAL flag.
*/
NGHTTP2_CTRL_FLAG_UNIDIRECTIONAL = 0x2
} nghttp2_ctrl_flag;
/**
* @enum
* The flags for a DATA frame.
*/
typedef enum {
/**
* No flag set.
*/
NGHTTP2_DATA_FLAG_NONE = 0,
/**
* FLAG_FIN flag.
*/
NGHTTP2_DATA_FLAG_FIN = 0x1
} nghttp2_data_flag;
/**
* @enum
* The flags for the SETTINGS control frame.
*/
typedef enum {
/**
* No flag set.
*/
NGHTTP2_FLAG_SETTINGS_NONE = 0,
/**
* SETTINGS_CLEAR_SETTINGS flag.
*/
NGHTTP2_FLAG_SETTINGS_CLEAR_SETTINGS = 1
} nghttp2_settings_flag;
/**
* @enum
* The flags for SETTINGS ID/value pair.
*/
typedef enum {
/**
* No flag set.
*/
NGHTTP2_ID_FLAG_SETTINGS_NONE = 0,
/**
* FLAG_SETTINGS_PERSIST_VALUE flag.
*/
NGHTTP2_ID_FLAG_SETTINGS_PERSIST_VALUE = 1,
/**
* FLAG_SETTINGS_PERSISTED flag.
*/
NGHTTP2_ID_FLAG_SETTINGS_PERSISTED = 2
} nghttp2_settings_id_flag;
/**
* @enum
* The SETTINGS ID.
*/
typedef enum {
/**
* SETTINGS_UPLOAD_BANDWIDTH
*/
NGHTTP2_SETTINGS_UPLOAD_BANDWIDTH = 1,
/**
* SETTINGS_DOWNLOAD_BANDWIDTH
*/
NGHTTP2_SETTINGS_DOWNLOAD_BANDWIDTH = 2,
/**
* SETTINGS_ROUND_TRIP_TIME
*/
NGHTTP2_SETTINGS_ROUND_TRIP_TIME = 3,
/**
* SETTINGS_MAX_CONCURRENT_STREAMS
*/
NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS = 4,
/**
* SETTINGS_CURRENT_CWND
*/
NGHTTP2_SETTINGS_CURRENT_CWND = 5,
/**
* SETTINGS_DOWNLOAD_RETRANS_RATE
*/
NGHTTP2_SETTINGS_DOWNLOAD_RETRANS_RATE = 6,
/**
* SETTINGS_INITIAL_WINDOW_SIZE
*/
NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE = 7,
/**
* SETTINGS_CLIENT_CERTIFICATE_VECTOR_SIZE. This first appeared in
* SPDY/3.
*/
NGHTTP2_SETTINGS_CLIENT_CERTIFICATE_VECTOR_SIZE = 8,
/**
* Maximum ID of :type:`nghttp2_settings_id`.
*/
NGHTTP2_SETTINGS_MAX = 8
} nghttp2_settings_id;
/**
* @macro
* Default maximum concurrent streams.
*/
#define NGHTTP2_INITIAL_MAX_CONCURRENT_STREAMS 100
/**
* @enum
* The status codes for the RST_STREAM control frame.
*/
typedef enum {
/**
* NGHTTP2_OK is not valid status code for RST_STREAM. It is defined
* just for nghttp2 library use.
*/
NGHTTP2_OK = 0,
/**
* PROTOCOL_ERROR
*/
NGHTTP2_PROTOCOL_ERROR = 1,
/**
* INVALID_STREAM
*/
NGHTTP2_INVALID_STREAM = 2,
/**
* REFUSED_STREAM
*/
NGHTTP2_REFUSED_STREAM = 3,
/**
* UNSUPPORTED_VERSION
*/
NGHTTP2_UNSUPPORTED_VERSION = 4,
/**
* CANCEL
*/
NGHTTP2_CANCEL = 5,
/**
* INTERNAL_ERROR
*/
NGHTTP2_INTERNAL_ERROR = 6,
/**
* FLOW_CONTROL_ERROR
*/
NGHTTP2_FLOW_CONTROL_ERROR = 7,
/* Following status codes were introduced in SPDY/3 */
/**
* STREAM_IN_USE
*/
NGHTTP2_STREAM_IN_USE = 8,
/**
* STREAM_ALREADY_CLOSED
*/
NGHTTP2_STREAM_ALREADY_CLOSED = 9,
/**
* INVALID_CREDENTIALS
*/
NGHTTP2_INVALID_CREDENTIALS = 10,
/**
* FRAME_TOO_LARGE
*/
NGHTTP2_FRAME_TOO_LARGE = 11
} nghttp2_status_code;
/**
* @enum
* The status codes for GOAWAY, introduced in SPDY/3.
*/
typedef enum {
/**
* OK. This indicates a normal session teardown.
*/
NGHTTP2_GOAWAY_OK = 0,
/**
* PROTOCOL_ERROR
*/
NGHTTP2_GOAWAY_PROTOCOL_ERROR = 1,
/**
* INTERNAL_ERROR
*/
NGHTTP2_GOAWAY_INTERNAL_ERROR = 2
} nghttp2_goaway_status_code;
/**
* @struct
* The control frame header.
*/
typedef struct {
/**
* SPDY protocol version.
*/
uint16_t version;
/**
* The type of this control frame.
*/
uint16_t type;
/**
* The control frame flags.
*/
uint8_t flags;
/**
* The length field of this control frame.
*/
int32_t length;
} nghttp2_ctrl_hd;
/**
* @struct
* The SYN_STREAM control frame. It has the following members:
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
/**
* The stream ID.
*/
int32_t stream_id;
/**
* The associated-to-stream ID. 0 if this frame has no
* associated-to-stream.
*/
int32_t assoc_stream_id;
/**
* The priority of this frame. 0 is the highest priority value. Use
* `nghttp2_session_get_pri_lowest()` to know the lowest priority
* value.
*/
uint8_t pri;
/**
* The index in server's CREDENTIAL vector of the client certificate.
* This was introduced in SPDY/3.
*/
uint8_t slot;
/**
* 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 member may be ``NULL``.
*/
char **nv;
} nghttp2_syn_stream;
/**
* @struct
* The SYN_REPLY control frame. It has the following members:
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
/**
* The stream ID.
*/
int32_t stream_id;
/**
* 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 member may be ``NULL``.
*/
char **nv;
} nghttp2_syn_reply;
/**
* @struct
* The HEADERS control frame. It has the following members:
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
/**
* The stream ID.
*/
int32_t stream_id;
/**
* 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 member may be ``NULL``.
*/
char **nv;
} nghttp2_headers;
/**
* @struct
* The RST_STREAM control frame. It has the following members:
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
/**
* The stream ID.
*/
int32_t stream_id;
/**
* The status code. See :type:`nghttp2_status_code`.
*/
uint32_t status_code;
} nghttp2_rst_stream;
/**
* @struct
* The SETTINGS ID/Value pair. It has the following members:
*/
typedef struct {
/**
* The SETTINGS ID. See :type:`nghttp2_settings_id`.
*/
int32_t settings_id;
/**
* The flags. See :type:`nghttp2_settings_id_flag`.
*/
uint8_t flags;
/**
* The value of this entry.
*/
uint32_t value;
} nghttp2_settings_entry;
/**
* @struct
* The SETTINGS control frame. It has the following members:
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
/**
* The number of SETTINGS ID/Value pairs in |iv|.
*/
size_t niv;
/**
* The pointer to the array of SETTINGS ID/Value pair.
*/
nghttp2_settings_entry *iv;
} nghttp2_settings;
/**
* @struct
* The PING control frame. It has the following members:
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
/**
* The unique ID.
*/
uint32_t unique_id;
} nghttp2_ping;
/**
* @struct
* The GOAWAY control frame. It has the following members:
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
/**
* The last-good-stream ID.
*/
int32_t last_good_stream_id;
/**
* The status code. This first appeared in SPDY/3. See
* :type:`nghttp2_goaway_status_code`.
*/
uint32_t status_code;
} nghttp2_goaway;
/**
* @struct
*
* The WINDOW_UPDATE control frame. This first appeared in SPDY/3. It
* has the following members:
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
/**
* The stream ID.
*/
int32_t stream_id;
/**
* The delta-window-size.
*/
int32_t delta_window_size;
} nghttp2_window_update;
/**
* @struct
*
* The structure to hold chunk of memory.
*/
typedef struct {
/**
* The pointer to the data.
*/
uint8_t *data;
/**
* The length of the data.
*/
size_t length;
} nghttp2_mem_chunk;
/**
* @struct
*
* The CREDENTIAL control frame. This first appeared in SPDY/3. It has
* the following members:
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
/**
* The index in the client certificate vector.
*/
uint16_t slot;
/**
* Cryptographic proof that the client has possession of the private
* key associated with the certificate.
*/
nghttp2_mem_chunk proof;
/**
* The certificate chain. The certs[0] is the leaf certificate.
*/
nghttp2_mem_chunk *certs;
/**
* The number of certificates in |certs|.
*/
size_t ncerts;
} nghttp2_credential;
/**
* @struct
*
* Convenient structure to inspect control frame header. It is useful
* to get the frame type.
*/
typedef struct {
/**
* The control frame header.
*/
nghttp2_ctrl_hd hd;
} nghttp2_ctrl_frame;
/**
* @union
*
* This union represents the some kind of data source passed to
* :type:`nghttp2_data_source_read_callback`.
*/
typedef union {
/**
* The integer field, suitable for a file descriptor.
*/
int fd;
/**
* The pointer to an arbitrary object.
*/
void *ptr;
} nghttp2_data_source;
/**
* @functypedef
*
* Callback function invoked when the library wants to read data from
* the |source|. The read data is sent in the stream |stream_id|. The
* implementation of this function must read at most |length| bytes of
* data from |source| (or possibly other places) and store them in
* |buf| and return number of data stored in |buf|. If EOF is reached,
* set |*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 :enum:`NGHTTP2_ERR_DEFERRED` without
* reading any data in this invocation. The library removes DATA
* frame from the outgoing queue temporarily. To move back deferred
* DATA frame to outgoing queue, call `nghttp2_session_resume_data()`.
* In case of error, there are 2 choices. Returning
* :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close the stream
* by issuing RST_STREAM with :enum:`NGHTTP2_INTERNAL_ERROR`.
* Returning :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the
* entire session failure.
*/
typedef ssize_t (*nghttp2_data_source_read_callback)
(nghttp2_session *session, int32_t stream_id,
uint8_t *buf, size_t length, int *eof,
nghttp2_data_source *source, void *user_data);
/**
* @struct
*
* This struct represents the data source and the way to read a chunk
* of data from it.
*/
typedef struct {
/**
* The data source.
*/
nghttp2_data_source source;
/**
* The callback function to read a chunk of data from the |source|.
*/
nghttp2_data_source_read_callback read_callback;
} nghttp2_data_provider;
/**
* @union
*
* This union includes all control frames to pass them
* to various function calls as nghttp2_frame type.
*/
typedef union {
/**
* Convenient structure to inspect control frame header.
*/
nghttp2_ctrl_frame ctrl;
/**
* The SYN_STREAM control frame.
*/
nghttp2_syn_stream syn_stream;
/**
* The SYN_REPLY control frame.
*/
nghttp2_syn_reply syn_reply;
/**
* The RST_STREAM control frame.
*/
nghttp2_rst_stream rst_stream;
/**
* The SETTINGS control frame.
*/
nghttp2_settings settings;
/**
* The PING control frame.
*/
nghttp2_ping ping;
/**
* The GOAWAY control frame.
*/
nghttp2_goaway goaway;
/**
* The HEADERS control frame.
*/
nghttp2_headers headers;
/**
* The WINDOW_UPDATE control frame.
*/
nghttp2_window_update window_update;
/**
* The CREDENTIAL control frame.
*/
nghttp2_credential credential;
} nghttp2_frame;
/**
* @functypedef
*
* 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 :enum:`NGHTTP2_ERR_WOULDBLOCK`. For other errors, it
* must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
typedef ssize_t (*nghttp2_send_callback)
(nghttp2_session *session,
const uint8_t *data, size_t length, int flags, void *user_data);
/**
* @functypedef
*
* Callback function invoked when |session| wants to receive data from
* the remote peer. The implementation of this function must read at
* most |length| bytes of data and store it in |buf|. The |flags| is
* currently not used and always 0. It must return the number of bytes
* written in |buf| if it succeeds. If it cannot read any single byte
* without blocking, it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`. If
* it gets EOF before it reads any single byte, it must return
* :enum:`NGHTTP2_ERR_EOF`. For other errors, it must return
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
*/
typedef ssize_t (*nghttp2_recv_callback)
(nghttp2_session *session,
uint8_t *buf, size_t length, int flags, void *user_data);
/**
* @functypedef
*
* Callback function invoked by `nghttp2_session_recv()` when a
* control frame is received.
*/
typedef void (*nghttp2_on_ctrl_recv_callback)
(nghttp2_session *session, nghttp2_frame_type type, nghttp2_frame *frame,
void *user_data);
/**
* @functypedef
*
* Callback function invoked by `nghttp2_session_recv()` when an
* invalid control frame is received. The |status_code| is one of the
* :enum:`nghttp2_status_code` and indicates the error. When this
* callback function is invoked, the library automatically submits
* either RST_STREAM or GOAWAY frame.
*/
typedef void (*nghttp2_on_invalid_ctrl_recv_callback)
(nghttp2_session *session, nghttp2_frame_type type, nghttp2_frame *frame,
uint32_t status_code, void *user_data);
/**
* @functypedef
*
* 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_DATA_FLAG_FIN) != 0`` does not
* necessarily mean this chunk of data is the last one in the
* stream. You should use :type:`nghttp2_on_data_recv_callback` to
* know all data frames are received.
*/
typedef void (*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);
/**
* @functypedef
*
* Callback function invoked when DATA frame is received. The actual
* data it contains are received by
* :type:`nghttp2_on_data_chunk_recv_callback`.
*/
typedef void (*nghttp2_on_data_recv_callback)
(nghttp2_session *session, uint8_t flags, int32_t stream_id, int32_t length,
void *user_data);
/**
* @functypedef
*
* Callback function invoked before the control frame |frame| of type
* |type| is sent. This may be useful, for example, to know the stream
* ID of SYN_STREAM frame (see also
* `nghttp2_session_get_stream_user_data()`), which is not assigned
* when it was queued.
*/
typedef void (*nghttp2_before_ctrl_send_callback)
(nghttp2_session *session, nghttp2_frame_type type, nghttp2_frame *frame,
void *user_data);
/**
* @functypedef
*
* Callback function invoked after the control frame |frame| of type
* |type| is sent.
*/
typedef void (*nghttp2_on_ctrl_send_callback)
(nghttp2_session *session, nghttp2_frame_type type, nghttp2_frame *frame,
void *user_data);
/**
* @functypedef
*
* Callback function invoked after the control frame |frame| of type
* |type| is not sent because of the error. The error is indicated by
* the |error_code|, which is one of the values defined in
* :type:`nghttp2_error`.
*/
typedef void (*nghttp2_on_ctrl_not_send_callback)
(nghttp2_session *session, nghttp2_frame_type type, nghttp2_frame *frame,
int error_code, void *user_data);
/**
* @functypedef
*
* Callback function invoked after DATA frame is sent.
*/
typedef void (*nghttp2_on_data_send_callback)
(nghttp2_session *session, uint8_t flags, int32_t stream_id, int32_t length,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when the stream |stream_id| is
* closed. The reason of closure is indicated by the
* |status_code|. The stream_user_data, which was specified in
* `nghttp2_submit_request()` or `nghttp2_submit_syn_stream()`, is
* still available in this function.
*/
typedef void (*nghttp2_on_stream_close_callback)
(nghttp2_session *session, int32_t stream_id, nghttp2_status_code status_code,
void *user_data);
/**
* @functypedef
*
* Callback function invoked when the request from the remote peer is
* received. In other words, the frame with FIN flag set is received.
* In HTTP, this means HTTP request, including request body, is fully
* received.
*/
typedef void (*nghttp2_on_request_recv_callback)
(nghttp2_session *session, int32_t stream_id, void *user_data);
/**
* @functypedef
*
* Callback function invoked when the received control frame octets
* could not be parsed correctly. The |type| indicates the type of
* received control frame. The |head| is the pointer to the header of
* the received frame. The |headlen| is the length of the
* |head|. According to the SPDY 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 |error_code| is one of the
* error code defined in :enum:`nghttp2_error` and indicates the
* error.
*/
typedef void (*nghttp2_on_ctrl_recv_parse_error_callback)
(nghttp2_session *session, nghttp2_frame_type type,
const uint8_t *head, size_t headlen,
const uint8_t *payload, size_t payloadlen,
int error_code, void *user_data);
/**
* @functypedef
*
* Callback function invoked when the received control 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
* SPDY 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.
*/
typedef void (*nghttp2_on_unknown_ctrl_recv_callback)
(nghttp2_session *session,
const uint8_t *head, size_t headlen,
const uint8_t *payload, size_t payloadlen,
void *user_data);
#define NGHTTP2_MAX_SCHEME 255
#define NGHTTP2_MAX_HOSTNAME 255
struct nghttp2_origin;
/**
* @struct
*
* The Web origin structure. The origin is the tuple (scheme, host,
* port). The details of this structure is intentionally hidden. To
* access these members, use accessor functions below.
*/
typedef struct nghttp2_origin nghttp2_origin;
/**
* @function
*
* Returns the scheme member of the |origin|.
*/
const char* nghttp2_origin_get_scheme(const nghttp2_origin *origin);
/**
* @function
*
* Returns the host member of the |origin|.
*/
const char* nghttp2_origin_get_host(const nghttp2_origin *origin);
/**
* @function
*
* Returns the port member of the |origin|.
*/
uint16_t nghttp2_origin_get_port(const nghttp2_origin *origin);
/**
* @functypedef
*
* Callback function invoked when the library needs the cryptographic
* proof that the client has possession of the private key associated
* with the certificate for the given |origin|. If called with
* |prooflen| == 0, the implementation of this function must return
* the length of the proof in bytes. If called with |prooflen| > 0,
* write proof into |proof| exactly |prooflen| bytes and return 0.
*
* Because the client certificate vector has limited number of slots,
* the application code may be required to pass the same proof more
* than once.
*/
typedef ssize_t (*nghttp2_get_credential_proof)
(nghttp2_session *session, const nghttp2_origin *origin,
uint8_t *proof, size_t prooflen, void *user_data);
/**
* @functypedef
*
* Callback function invoked when the library needs the length of the
* client certificate chain for the given |origin|. The
* implementation of this function must return the length of the
* client certificate chain. If no client certificate is required for
* the given |origin|, return 0. If positive integer is returned,
* :type:`nghttp2_get_credential_proof` and
* :type:`nghttp2_get_credential_cert` callback functions will be used
* to get the cryptographic proof and certificate respectively.
*/
typedef ssize_t (*nghttp2_get_credential_ncerts)
(nghttp2_session *session, const nghttp2_origin *origin, void *user_data);
/**
* @functypedef
*
* Callback function invoked when the library needs the client
* certificate for the given |origin|. The |idx| is the index of the
* certificate chain and 0 means the leaf certificate of the chain.
* If called with |certlen| == 0, the implementation of this function
* must return the length of the certificate in bytes. If called with
* |certlen| > 0, write certificate into |cert| exactly |certlen|
* bytes and return 0.
*/
typedef ssize_t (*nghttp2_get_credential_cert)
(nghttp2_session *session, const nghttp2_origin *origin, size_t idx,
uint8_t *cert, size_t certlen, void *user_data);
/**
* @struct
*
* Callback functions.
*/
typedef struct {
/**
* Callback function invoked when the |session| wants to send data
* to the remote peer.
*/
nghttp2_send_callback send_callback;
/**
* Callback function invoked when the |session| wants to receive
* data from the remote peer.
*/
nghttp2_recv_callback recv_callback;
/**
* Callback function invoked by `nghttp2_session_recv()` when a
* control frame is received.
*/
nghttp2_on_ctrl_recv_callback on_ctrl_recv_callback;
/**
* Callback function invoked by `nghttp2_session_recv()` when an
* invalid control frame is received.
*/
nghttp2_on_invalid_ctrl_recv_callback on_invalid_ctrl_recv_callback;
/**
* Callback function invoked when a chunk of data in DATA frame is
* received.
*/
nghttp2_on_data_chunk_recv_callback on_data_chunk_recv_callback;
/**
* Callback function invoked when DATA frame is received.
*/
nghttp2_on_data_recv_callback on_data_recv_callback;
/**
* Callback function invoked before the control frame is sent.
*/
nghttp2_before_ctrl_send_callback before_ctrl_send_callback;
/**
* Callback function invoked after the control frame is sent.
*/
nghttp2_on_ctrl_send_callback on_ctrl_send_callback;
/**
* The callback function invoked when a control frame is not sent
* because of an error.
*/
nghttp2_on_ctrl_not_send_callback on_ctrl_not_send_callback;
/**
* Callback function invoked after DATA frame is sent.
*/
nghttp2_on_data_send_callback on_data_send_callback;
/**
* Callback function invoked when the stream is closed.
*/
nghttp2_on_stream_close_callback on_stream_close_callback;
/**
* Callback function invoked when request from the remote peer is
* received.
*/
nghttp2_on_request_recv_callback on_request_recv_callback;
/**
* Callback function invoked when the library needs the
* cryptographic proof that the client has possession of the private
* key associated with the certificate.
*/
nghttp2_get_credential_proof get_credential_proof;
/**
* Callback function invoked when the library needs the length of the
* client certificate chain.
*/
nghttp2_get_credential_ncerts get_credential_ncerts;
/**
* Callback function invoked when the library needs the client
* certificate.
*/
nghttp2_get_credential_cert get_credential_cert;
/**
* Callback function invoked when the received control frame octets
* could not be parsed correctly.
*/
nghttp2_on_ctrl_recv_parse_error_callback on_ctrl_recv_parse_error_callback;
/**
* Callback function invoked when the received control frame type is
* unknown.
*/
nghttp2_on_unknown_ctrl_recv_callback on_unknown_ctrl_recv_callback;
} nghttp2_session_callbacks;
/**
* @function
*
* Initializes |*session_ptr| for client use, using the protocol
* version |version|. 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 :member:`nghttp2_session_callbacks.send_callback` must be
* specified. If the application code uses `nghttp2_session_recv()`,
* the :member:`nghttp2_session_callbacks.recv_callback` must be
* specified. The other members of |callbacks| can be ``NULL``. To
* use CREDENTIAL frame, specify :macro:`NGHTTP2_PROTO_SPDY3` in
* |version| and specify
* :member:`nghttp2_session_callbacks.get_credential_ncerts`,
* :member:`nghttp2_session_callbacks.get_credential_cert` and
* :member:`nghttp2_session_callbacks.get_credential_proof`. See also
* `nghttp2_session_set_initial_client_cert_origin()`.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`NGHTTP2_ERR_ZLIB`
* The z_stream initialization failed.
* :enum:`NGHTTP2_ERR_UNSUPPORTED_VERSION`
* The version is not supported.
*/
int nghttp2_session_client_new(nghttp2_session **session_ptr,
uint16_t version,
const nghttp2_session_callbacks *callbacks,
void *user_data);
/**
* @function
*
* Initializes |*session_ptr| for server use, using the protocol
* version |version|. 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 :member:`nghttp2_session_callbacks.send_callback` must be
* specified. If the application code uses `nghttp2_session_recv()`,
* the :member:`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:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`NGHTTP2_ERR_ZLIB`
* The z_stream initialization failed.
* :enum:`NGHTTP2_ERR_UNSUPPORTED_VERSION`
* The version is not supported.
*/
int nghttp2_session_server_new(nghttp2_session **session_ptr,
uint16_t version,
const nghttp2_session_callbacks *callbacks,
void *user_data);
/**
* @function
*
* Frees any resources allocated for |session|. If |session| is
* ``NULL``, this function does nothing.
*/
void nghttp2_session_del(nghttp2_session *session);
/**
* @enum
*
* Configuration options for :type:`nghttp2_session`.
*/
typedef enum {
/**
* This option prevents the library from sending WINDOW_UPDATE
* automatically. If this option is set, the application is
* responsible for sending WINDOW_UPDATE using
* `nghttp2_submit_window_update`.
*/
NGHTTP2_OPT_NO_AUTO_WINDOW_UPDATE = 1,
/**
* This option sets maximum receive buffer size for incoming control
* frame.
*/
NGHTTP2_OPT_MAX_RECV_CTRL_FRAME_BUFFER = 2
} nghttp2_opt;
/**
* @function
*
* Sets the configuration option for the |session|. The |optname| is
* one of :type:`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:
*
* :enum:`NGHTTP2_OPT_NO_AUTO_WINDOW_UPDATE`
* The |optval| must be a pointer to ``int``. If the |*optval| is
* nonzero, the library will not send WINDOW_UPDATE automatically.
* Therefore, the application is responsible for sending
* WINDOW_UPDATE using `nghttp2_submit_window_update`. This option
* defaults to 0.
*
* :enum:`NGHTTP2_OPT_MAX_RECV_CTRL_FRAME_BUFFER`
* The |optval| must be a pointer to ``uint32_t``. The |*optval|
* must be in the range [(1 << 13), (1 << 24)-1], inclusive. This
* option defaults to (1 << 24)-1.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |optname| is not supported; or the |optval| and/or the
* |optlen| are invalid.
*/
int nghttp2_session_set_option(nghttp2_session *session,
int optname, void *optval, size_t optlen);
/**
* @function
*
* Sets the origin tuple (|scheme|, |host| and |port|) that the
* connection is made to and the client certificate is sent in the
* first TLS handshake. This function must be called before any call
* of `nghttp2_session_send()` and `nghttp2_session_recv()` and be
* called only once per session. This function must not be called if
* the |session| is initialized for server use. If the client did not
* provide the client certificate in the first TLS handshake, this
* function must not be called.
*
* This function stores the given origin at the slot 1 in the client
* certificate vector.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory
* :enum:`NGHTTP2_ERR_INVALID_STATE`
* The |session| is initialized for server use; or the client
* certificate vector size is 0.
*/
int nghttp2_session_set_initial_client_cert_origin(nghttp2_session *session,
const char *scheme,
const char *host,
uint16_t port);
/**
* @function
*
* Returns the origin at the index |slot| in the client certificate
* vector. If there is no origin at the given |slot|, this function
* returns ``NULL``.
*
* This function must not be called if the |session| is initialized
* for server use.
*/
const nghttp2_origin* nghttp2_session_get_client_cert_origin
(nghttp2_session *session,
size_t slot);
/**
* @function
*
* 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
* :member:`nghttp2_session_callbacks.send_callback` returns
* :enum:`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:
*
* 1. Get the next frame to send from outbound queue.
* 2. Prepare transmission of the frame.
* 3. If the control frame cannot be sent because some preconditions
* are not met (e.g., SYN_STREAM cannot be sent after GOAWAY),
* :member:`nghttp2_session_callbacks.on_ctrl_not_send_callback` is
* invoked. Abort the following steps.
* 4. If the frame is SYN_STREAM, the stream is opened here.
* If the |session| is initialized for client use and the protocol
* version is :macro:`NGHTTP2_PROTO_SPDY3` and the library needs
* the client certificate for the origin,
* :member:`nghttp2_session_callbacks.get_credential_ncerts` is
* invoked. If the result is more than zero,
* :member:`nghttp2_session_callbacks.get_credential_proof` and
* :member:`nghttp2_session_callbacks.get_credential_cert` are also
* invoked.
* 5. :member:`nghttp2_session_callbacks.before_ctrl_send_callback` is
* invoked.
* 6. :member:`nghttp2_session_callbacks.send_callback` is invoked one
* or more times to send the frame.
* 7. If the frame is a control frame,
* :member:`nghttp2_session_callbacks.on_ctrl_send_callback` is
* invoked.
* 8. If the frame is a DATA frame,
* :member:`nghttp2_session_callbacks.on_data_send_callback` is
* invoked.
* 9. If the transmission of the frame triggers closure of the stream,
* the stream is closed and
* :member:`nghttp2_session_callbacks.on_stream_close_callback` is
* invoked.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`
* The callback function failed.
*/
int nghttp2_session_send(nghttp2_session *session);
/**
* @function
*
* Receives frames from the remote peer.
*
* This function receives as many frames as possible until the user
* callback :member:`nghttp2_session_callbacks.recv_callback` returns
* :enum:`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:
*
* 1. :member:`nghttp2_session_callbacks.recv_callback` is invoked one
* or more times to receive frame header.
* 2. If the frame is DATA frame:
*
* 2.1. :member:`nghttp2_session_callbacks.recv_callback` is invoked
* to receive DATA payload. For each chunk of data,
* :member:`nghttp2_session_callbacks.on_data_chunk_recv_callback`
* is invoked.
* 2.2. If one DATA frame is completely received,
* :member:`nghttp2_session_callbacks.on_data_recv_callback` is
* invoked. If the frame is the final frame of the request,
* :member:`nghttp2_session_callbacks.on_request_recv_callback`
* is invoked. If the reception of the frame triggers the
* closure of the stream,
* :member:`nghttp2_session_callbacks.on_stream_close_callback`
* is invoked.
*
* 3. If the frame is the control frame:
*
* 3.1. :member:`nghttp2_session_callbacks.recv_callback` is invoked
* one or more times to receive whole frame.
* 3.2. If the received frame is valid,
* :member:`nghttp2_session_callbacks.on_ctrl_recv_callback` is
* invoked. If the frame is the final frame of the request,
* :member:`nghttp2_session_callbacks.on_request_recv_callback`
* is invoked. If the reception of the frame triggers the
* closure of the stream,
* :member:`nghttp2_session_callbacks.on_stream_close_callback`
* is invoked.
* 3.3. If the received frame is unpacked but is interpreted as
* invalid,
* :member:`nghttp2_session_callbacks.on_invalid_ctrl_recv_callback`
* is invoked.
* 3.4. If the received frame could not be unpacked correctly,
* :member:`nghttp2_session_callbacks.on_ctrl_recv_parse_error_callback`
* is invoked.
* 3.5. If the received frame type is unknown,
* :member:`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:
*
* :enum:`NGHTTP2_ERR_EOF`
* The remote peer did shutdown on the connection.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
* :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`
* The callback function failed.
*/
int nghttp2_session_recv(nghttp2_session *session);
/**
* @function
*
* 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 :member:`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 an error occurs.
*
* This function returns the number of processed bytes, or one of the
* following negative error codes:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
ssize_t nghttp2_session_mem_recv(nghttp2_session *session,
const uint8_t *in, size_t inlen);
/**
* @function
*
* 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:
*
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The stream does not exist or no deferred data exist.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_session_resume_data(nghttp2_session *session, int32_t stream_id);
/**
* @function
*
* 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_read(nghttp2_session *session);
/**
* @function
*
* 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.
*/
int nghttp2_session_want_write(nghttp2_session *session);
/**
* @function
*
* 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``.
*/
void* nghttp2_session_get_stream_user_data(nghttp2_session *session,
int32_t stream_id);
/**
* @function
*
* Returns the number of frames in the outbound queue. This does not
* include the deferred DATA frames.
*/
size_t nghttp2_session_get_outbound_queue_size(nghttp2_session *session);
/**
* @function
*
* Returns lowest priority value for the |session|.
*/
uint8_t nghttp2_session_get_pri_lowest(nghttp2_session *session);
/**
* @function
*
* Submits GOAWAY frame. The status code |status_code| is ignored if
* the protocol version is :macro:`NGHTTP2_PROTO_SPDY2`.
*
* 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:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_session_fail_session(nghttp2_session *session,
uint32_t status_code);
/**
* @function
*
* Returns string describing the |error_code|. The |error_code| must
* be one of the :enum:`nghttp2_error`.
*/
const char* nghttp2_strerror(int error_code);
/**
* @function
*
* Submits SYN_STREAM frame and optionally one or more DATA
* frames.
*
* The |pri| is priority of this request. 0 is the highest priority
* value. Use `nghttp2_session_get_pri_lowest()` to know the lowest
* priority value for this |session|.
*
* 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:
*
* ``:method``
* HTTP method (e.g., ``GET``, ``POST``, ``HEAD``, etc)
* ``:scheme``
* URI scheme (e.g., ``https``)
* ``:path``
* Absolute path and parameters of this request (e.g., ``/foo``,
* ``/foo;bar;haz?h=j&y=123``)
* ``:version``
* HTTP version (e.g., ``HTTP/1.1``)
* ``:host``
* The hostport portion of the URI for this request (e.g.,
* ``example.org:443``). This is the same as the HTTP "Host" header
* field.
*
* If the |session| is initialized with the version
* :macro:`NGHTTP2_PROTO_SPDY2`, the above names are translated to
* ``method``, ``scheme``, ``url``, ``version`` and ``host``
* respectively.
*
* 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. 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``,
* SYN_STREAM have FLAG_FIN 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 SPDY 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
* :member:`nghttp2_session_callbacks.before_ctrl_send_callback`. This
* callback is called just before the frame is sent. For SYN_STREAM
* 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 SYN_STREAM we are processing.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |pri| is invalid; or the |nv| includes empty name or NULL
* value.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_request(nghttp2_session *session, uint8_t pri,
const char **nv,
const nghttp2_data_provider *data_prd,
void *stream_user_data);
/**
* @function
*
* Submits SYN_REPLY 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:
*
* ``:status``
* HTTP status code (e.g., ``200`` or ``200 OK``)
* ``:version``
* HTTP response version (e.g., ``HTTP/1.1``)
*
* If the |session| is initialized with the version
* :macro:`NGHTTP2_PROTO_SPDY2`, the above names are translated to
* ``status`` and ``version`` respectively.
*
* 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``, SYN_REPLY will have
* FLAG_FIN set.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |nv| includes empty name or NULL value.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_response(nghttp2_session *session,
int32_t stream_id, const char **nv,
const nghttp2_data_provider *data_prd);
/**
* @function
*
* Submits SYN_STREAM frame. The |flags| is bitwise OR of the
* following values:
*
* * :enum:`NGHTTP2_CTRL_FLAG_FIN`
* * :enum:`NGHTTP2_CTRL_FLAG_UNIDIRECTIONAL`
*
* If |flags| includes :enum:`NGHTTP2_CTRL_FLAG_FIN`, this frame has
* FLAG_FIN flag set.
*
* The |assoc_stream_id| is used for server-push. Specify 0 if this
* stream is not server-push. If |session| is initialized for client
* use, |assoc_stream_id| is ignored.
*
* The |pri| is priority of this request. 0 is the highest priority
* value. Use `nghttp2_session_get_pri_lowest()` to know the lowest
* priority value for this |session|.
*
* 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.
*
* This function is low-level in a sense that the application code can
* specify flags and the Associated-To-Stream-ID 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:
*
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |pri| is invalid; or the |assoc_stream_id| is invalid; or
* the |nv| includes empty name or NULL value.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_syn_stream(nghttp2_session *session, uint8_t flags,
int32_t assoc_stream_id, uint8_t pri,
const char **nv, void *stream_user_data);
/**
* @function
*
* Submits SYN_REPLY frame. The |flags| is bitwise OR of the following
* values:
*
* * :enum:`NGHTTP2_CTRL_FLAG_FIN`
*
* If |flags| includes :enum:`NGHTTP2_CTRL_FLAG_FIN`, this frame has
* FLAG_FIN flag set.
*
* The stream which this frame belongs to is given in the
* |stream_id|. The |nv| is the name/value pairs in this frame.
*
* 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|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |nv| includes empty name or NULL value.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_syn_reply(nghttp2_session *session, uint8_t flags,
int32_t stream_id, const char **nv);
/**
* @function
*
* Submits HEADERS frame. The |flags| is bitwise OR of the following
* values:
*
* * :enum:`NGHTTP2_CTRL_FLAG_FIN`
*
* If |flags| includes :enum:`NGHTTP2_CTRL_FLAG_FIN`, this frame has
* FLAG_FIN flag set.
*
* The stream which this frame belongs to is given in the
* |stream_id|. The |nv| is the name/value pairs in this frame.
*
* 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|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |nv| includes empty name or NULL value.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_headers(nghttp2_session *session, uint8_t flags,
int32_t stream_id, const char **nv);
/**
* @function
*
* Submits one or more DATA frames to the stream |stream_id|. The
* data to be sent are provided by |data_prd|. If |flags| contains
* :enum:`NGHTTP2_DATA_FLAG_FIN`, the last DATA frame has FLAG_FIN
* 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:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_data(nghttp2_session *session, int32_t stream_id,
uint8_t flags, const nghttp2_data_provider *data_prd);
/**
* @function
*
* Submits RST_STREAM frame to cancel/reject the stream |stream_id|
* with the status code |status_code|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_rst_stream(nghttp2_session *session, int32_t stream_id,
uint32_t status_code);
/**
* @function
*
* 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.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_ping(nghttp2_session *session);
/**
* @function
*
* Submits GOAWAY frame. The status code |status_code| is ignored if
* the protocol version is :macro:`NGHTTP2_PROTO_SPDY2`.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_goaway(nghttp2_session *session, uint32_t status_code);
/**
* @function
*
* Stores local settings and submits SETTINGS frame. The |iv| is the
* pointer to the array of :type:`nghttp2_settings_entry`. The |niv|
* indicates the number of :type:`nghttp2_settings_entry`. The |flags|
* is bitwise-OR of one or more values from
* :type:`nghttp2_settings_flag`.
*
* This function does not take ownership of the |iv|. This function
* copies all the elements in the |iv|.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |iv| contains duplicate settings ID or invalid value.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_settings(nghttp2_session *session, uint8_t flags,
const nghttp2_settings_entry *iv, size_t niv);
/**
* @function
*
* Submits WINDOW_UPDATE frame. The effective range of the
* |delta_window_size| is [1, (1 << 31)-1], inclusive. But the
* application must be responsible to keep the resulting window size
* <= (1 << 31)-1.
*
* This function returns 0 if it succeeds, or one of the following
* negative error codes:
*
* :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
* The |delta_window_size| is 0 or negative.
* :enum:`NGHTTP2_ERR_STREAM_CLOSED`
* The stream is already closed or does not exist.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_submit_window_update(nghttp2_session *session, int32_t stream_id,
int32_t delta_window_size);
/**
* @function
*
* 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,
* ``spdy/2`` and ``http/1.1`` stored in |in| like this::
*
* in[0] = 6
* in[1..6] = "spdy/2"
* in[7] = 8
* in[8..15] = "http/1.1"
* inlen = 16
*
* The selection algorithm is as follows:
*
* 1. If server's list contains SPDY versions the nghttp2 library
* supports, this function selects one of them and returns its SPDY
* protocol version which can be used directly with
* `nghttp2_session_client_new()` and
* `nghttp2_session_server_new()` . The following steps are not
* taken.
*
* 2. If server's list contains ``http/1.1``, this function selects
* ``http/1.1`` and returns 0. The following step is not taken.
*
* 3. This function selects nothing and returns -1. (So called
* non-overlap case). In this case, |out| and |outlen| are left
* untouched.
*
* When nghttp2 supports updated version of SPDY in the future, this
* function may select updated protocol and application code which
* relies on nghttp2 for SPDY stuff needs not be modified.
*
* Selecting ``spdy/2`` means that ``spdy/2`` is written into |*out|
* and length of ``spdy/2`` (which is 6) 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 version;
* version = nghttp2_select_next_protocol(out, outlen, in, inlen);
* if(version > 0) {
* ((MyType*)arg)->spdy_version = version;
* }
* return SSL_TLSEXT_ERR_OK;
* }
* ...
* SSL_CTX_set_next_proto_select_cb(ssl_ctx, select_next_proto_cb, my_obj);
*/
int nghttp2_select_next_protocol(unsigned char **out, unsigned char *outlen,
const unsigned char *in, unsigned int inlen);
/**
* @struct
*
* This struct contains SPDY version information this library
* supports.
*/
typedef struct {
/**
* SPDY protocol version name which can be used as TLS NPN protocol
* string.
*/
const unsigned char *proto;
/**
* The length of proto member.
*/
uint8_t len;
/**
* The corresponding SPDY version constant which can be passed to
* `nghttp2_session_client_new()` and `nghttp2_session_server_new()`
* as version argument.
*/
uint16_t version;
} nghttp2_npn_proto;
/**
* @function
*
* Returns a pointer to the supported SPDY version list. The number of
* elements in the list will be assigned to the |*len_ptr|. It
* contains all SPDY version information this library supports. The
* application can use this information to configure NPN protocol
* offerings/selection.
*/
const nghttp2_npn_proto* nghttp2_npn_get_proto_list(size_t *len_ptr);
/**
* @function
*
* Returns spdy version which nghttp2 library supports from the given
* protocol name. The |proto| is the pointer to the protocol name and
* |protolen| is its length. Currently, ``spdy/2`` and ``spdy/3`` are
* supported.
*
* This function returns nonzero spdy version if it succeeds, or 0.
*/
uint16_t nghttp2_npn_get_version(const unsigned char *proto, size_t protolen);
struct nghttp2_gzip;
/**
* @struct
*
* The gzip stream to inflate data. The details of this structure are
* intentionally hidden from the public API.
*/
typedef struct nghttp2_gzip nghttp2_gzip;
/**
* @function
*
* 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:
*
* :enum:`NGHTTP2_ERR_GZIP`
* The initialization of gzip stream failed.
* :enum:`NGHTTP2_ERR_NOMEM`
* Out of memory.
*/
int nghttp2_gzip_inflate_new(nghttp2_gzip **inflater_ptr);
/**
* @function
*
* Frees the inflate stream. The |inflater| may be ``NULL``.
*/
void nghttp2_gzip_inflate_del(nghttp2_gzip *inflater);
/**
* @function
*
* 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:
*
* :enum:`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;
* }
* ....
* }
*/
int nghttp2_gzip_inflate(nghttp2_gzip *inflater,
uint8_t *out, size_t *outlen_ptr,
const uint8_t *in, size_t *inlen_ptr);
#ifdef __cplusplus
}
#endif
#endif /* NGHTTP2_H */
Reference in New Issue View Git Blame Copy Permalink