Macros ====== .. macro:: NGHTTP2_VERSION Version number of the nghttp2 library release. .. macro:: NGHTTP2_VERSION_NUM Numerical representation of the version number of the nghttp2 library release. This is a 24 bit number with 8 bits for major number, 8 bits for minor and 8 bits for patch. Version 1.2.3 becomes 0x010203. HTTP/2 specific macros ---------------------- .. macro:: NGHTTP2_CLIENT_HTTP2_PREFACE :macro:`NGHTTP2_CLIENT_HTTP2_PREFACE` is the client HTTP/2 preface. .. macro:: NGHTTP2_HPACK_DEFAULT_DTABLE_CAPACITY :macro:`NGHTTP2_HPACK_DEFAULT_DTABLE_CAPACITY` is the default maximum HPACK dynamic header table capacity. .. macro:: NGHTTP2_INITIAL_WINDOW_SIZE :macro:`NGHTTP2_INITIAL_WINDOW_SIZE` is the default initial window size for both connection and stream-level flow control. .. macro:: NGHTTP2_MAX_EXTRA_SETTINGS :macro:`NGHTTP2_MAX_EXTRA_SETTINGS` is the maximum number of extra SETTINGS entries that can be specified in :member:`nghttp2_settings.extra_settings` and :member:`nghttp2_settings.extra_settingslen`. nghttp2 library error codes --------------------------- .. macro:: NGHTTP2_ERR_INVALID_ARGUMENT :macro:`NGHTTP2_ERR_INVALID_ARGUMENT` indicates that a passed argument is invalid. .. macro:: NGHTTP2_ERR_NOBUF :macro:`NGHTTP2_ERR_NOBUF` indicates that a provided buffer does not have enough space to store data. .. macro:: NGHTTP2_ERR_PROTO :macro:`NGHTTP2_ERR_PROTO` indicates a general protocol error. .. macro:: NGHTTP2_ERR_INVALID_STATE :macro:`NGHTTP2_ERR_INVALID_STATE` indicates that a requested operation is not allowed at the current connection state. .. macro:: NGHTTP2_ERR_HPACK_FATAL :macro:`NGHTTP2_ERR_HPACK_FATAL` indicates that HPACK encoder or decoder encounters an error. .. macro:: NGHTTP2_ERR_STREAM_ID_BLOCKED :macro:`NGHTTP2_ERR_STREAM_ID_BLOCKED` indicates that there is no spare stream ID available. .. macro:: NGHTTP2_ERR_REFUSED_STREAM :macro:`NGHTTP2_ERR_REFUSED_STREAM` indicates that stream creation is refused. .. macro:: NGHTTP2_ERR_WOULDBLOCK :macro:`NGHTTP2_ERR_WOULDBLOCK` indicates that an operation might block. .. macro:: NGHTTP2_ERR_FLOW_CONTROL :macro:`NGHTTP2_ERR_FLOW_CONTROL` indicates flow control error. .. macro:: NGHTTP2_ERR_FRAME_SIZE :macro:`NGHTTP2_ERR_FRAME_SIZE` indicates that the incoming frame is too large. .. macro:: NGHTTP2_ERR_STREAM_LIMIT :macro:`NGHTTP2_ERR_STREAM_LIMIT` indicates that a remote endpoint opens more streams that is permitted. .. macro:: NGHTTP2_ERR_MALFORMED_HTTP_HEADER :macro:`NGHTTP2_ERR_MALFORMED_HTTP_HEADER` indicates that an HTTP header field is malformed. .. macro:: NGHTTP2_ERR_REMOVE_HTTP_HEADER :macro:`NGHTTP2_ERR_REMOVE_HTTP_HEADER` indicates that an HTTP header field is discarded. .. macro:: NGHTTP2_ERR_MALFORMED_HTTP_MESSAGING :macro:`NGHTTP2_ERR_MALFORMED_HTTP_MESSAGING` indicates that HTTP messaging is malformed. .. macro:: NGHTTP2_ERR_STREAM_DATA_OVERFLOW :macro:`NGHTTP2_ERR_STREAM_DATA_OVERFLOW` indicates that stream data is too large. .. macro:: NGHTTP2_ERR_SETTINGS_TIMEOUT :macro:`NGHTTP2_ERR_SETTINGS_TIMEOUT` indicates that SETTINGS ACK has not been received within the configured period of time. .. macro:: NGHTTP2_ERR_FRAME_ENCODING :macro:`NGHTTP2_ERR_FRAME_ENCODING` indicates there is an error in frame encoding. .. macro:: NGHTTP2_ERR_STREAM_SHUT_WR :macro:`NGHTTP2_ERR_STREAM_SHUT_WR` indicates no more data can be sent to a stream. .. macro:: NGHTTP2_ERR_STREAM_NOT_FOUND :macro:`NGHTTP2_ERR_STREAM_NOT_FOUND` indicates that a stream was not found. .. macro:: NGHTTP2_ERR_STREAM_STATE :macro:`NGHTTP2_ERR_STREAM_STATE` indicates that a requested operation is not allowed at the current stream state. .. macro:: NGHTTP2_ERR_STOP_READING :macro:`NGHTTP2_ERR_STOP_READING` indicates that the local endpoint stops reading any input. .. macro:: NGHTTP2_ERR_CLOSING :macro:`NGHTTP2_ERR_CLOSING` indicates that connection is in closing state. .. macro:: NGHTTP2_ERR_DRAINING :macro:`NGHTTP2_ERR_DRAINING` indicates that connection is in draining state. .. macro:: NGHTTP2_ERR_INTERNAL :macro:`NGHTTP2_ERR_INTERNAL` indicates an internal error. .. macro:: NGHTTP2_ERR_FATAL :macro:`NGHTTP2_ERR_FATAL` indicates that error codes less than this value is fatal error. When this error is returned, an endpoint should close connection immediately. .. macro:: NGHTTP2_ERR_NOMEM :macro:`NGHTTP2_ERR_NOMEM` indicates out of memory. .. macro:: NGHTTP2_ERR_CALLBACK_FAILURE :macro:`NGHTTP2_ERR_CALLBACK_FAILURE` indicates that user defined callback function failed. .. macro:: NGHTTP2_ERR_EXCESSIVE_LOAD :macro:`NGHTTP2_ERR_EXCESSIVE_LOAD` indicates that the remote endpoint exhibits the behavior that causes the excessive load to the local endpoint. HTTP/2 error codes ------------------ .. macro:: NGHTTP2_NO_ERROR :macro:`NGHTTP2_NO_ERROR` is HTTP/2 error code ``NO_ERROR``. .. macro:: NGHTTP2_PROTOCOL_ERROR :macro:`NGHTTP2_PROTOCOL_ERROR` is HTTP/2 error code ``PROTOCOL_ERROR``. .. macro:: NGHTTP2_INTERNAL_ERROR :macro:`NGHTTP2_INTERNAL_ERROR` is HTTP/2 error code ``INTERNAL_ERROR``. .. macro:: NGHTTP2_FLOW_CONTROL_ERROR :macro:`NGHTTP2_FLOW_CONTROL_ERROR` is HTTP/2 error code ``FLOW_CONTROL_ERROR``. .. macro:: NGHTTP2_SETTINGS_TIMEOUT :macro:`NGHTTP2_SETTINGS_TIMEOUT` is HTTP/2 error code ``SETTINGS_TIMEOUT``. .. macro:: NGHTTP2_STREAM_CLOSED :macro:`NGHTTP2_STREAM_CLOSED` is HTTP/2 error code ``STREAM_CLOSED``. .. macro:: NGHTTP2_FRAME_SIZE_ERROR :macro:`NGHTTP2_FRAME_SIZE_ERROR` is HTTP/2 error code ``FRAME_SIZE_ERROR``. .. macro:: NGHTTP2_REFUSED_STREAM :macro:`NGHTTP2_REFUSED_STREAM` is HTTP/2 error code ``REFUSED_STREAM``. .. macro:: NGHTTP2_CANCEL :macro:`NGHTTP2_CANCEL` is HTTP/2 error code ``CANCEL``. .. macro:: NGHTTP2_COMPRESSION_ERROR :macro:`NGHTTP2_COMPRESSION_ERROR` is HTTP/2 error code ``COMPRESSION_ERROR``. .. macro:: NGHTTP2_CONNECT_ERROR :macro:`NGHTTP2_CONNECT_ERROR` is HTTP/2 error code ``CONNECT_ERROR``. .. macro:: NGHTTP2_ENHANCE_YOUR_CALM :macro:`NGHTTP2_ENHANCE_YOUR_CALM` is HTTP/2 error code ``ENHANCE_YOUR_CALM``. .. macro:: NGHTTP2_INADEQUATE_SECURITY :macro:`NGHTTP2_INADEQUATE_SECURITY` is HTTP/2 error code ``INADEQUATE_SECURITY``. .. macro:: NGHTTP2_HTTP_1_1_REQUIRED :macro:`NGHTTP2_HTTP_1_1_REQUIRED` is HTTP/2 error code ``HTTP_1_1_REQUIRED``. Time related macros ------------------- .. macro:: NGHTTP2_NANOSECONDS :macro:`NGHTTP2_NANOSECONDS` is a count of tick which corresponds to 1 nanosecond. .. macro:: NGHTTP2_MICROSECONDS :macro:`NGHTTP2_MICROSECONDS` is a count of tick which corresponds to 1 microsecond. .. macro:: NGHTTP2_MILLISECONDS :macro:`NGHTTP2_MILLISECONDS` is a count of tick which corresponds to 1 millisecond. .. macro:: NGHTTP2_SECONDS :macro:`NGHTTP2_SECONDS` is a count of tick which corresponds to 1 second. .. macro:: NGHTTP2_MINUTES :macro:`NGHTTP2_MINUTES` is a count of tick which corresponds to 1 minute. :type:`nghttp2_buf` helper macros --------------------------------- .. macro:: nghttp2_buf_left(BUF) `nghttp2_buf_left` returns the number of additional bytes which can be written to the underlying buffer. In other words, it returns :member:`buf->end ` - :member:`buf->last `. .. macro:: nghttp2_buf_len(BUF) `nghttp2_buf_len` returns the number of bytes left to read. In other words, it returns :member:`buf->last ` - :member:`buf->pos `. Flags for HTTP field name/value pair ------------------------------------ .. macro:: NGHTTP2_NV_FLAG_NONE :macro:`NGHTTP2_NV_FLAG_NONE` indicates no flag set. .. macro:: NGHTTP2_NV_FLAG_NEVER_INDEX :macro:`NGHTTP2_NV_FLAG_NEVER_INDEX` indicates that this name/value pair must not be indexed. Other implementation calls this bit as "sensitive". .. macro:: NGHTTP2_NV_FLAG_NO_COPY_NAME :macro:`NGHTTP2_NV_FLAG_NO_COPY_NAME` is set solely by application. If this flag is set, the library does not make a copy of field name. This could improve performance. .. macro:: NGHTTP2_NV_FLAG_NO_COPY_VALUE :macro:`NGHTTP2_NV_FLAG_NO_COPY_VALUE` is set solely by application. If this flag is set, the library does not make a copy of field value. This could improve performance. Stream close flags for :type:`nghttp2_stream_close` callback. ------------------------------------------------------------- .. macro:: NGHTTP2_STREAM_CLOSE_FLAG_NONE :macro:`NGHTTP2_STREAM_CLOSE_FLAG_NONE` indicates no flag set. .. macro:: NGHTTP2_STREAM_CLOSE_FLAG_ERROR_CODE_SET :macro:`NGHTTP2_STREAM_CLOSE_FLAG_ERROR_CODE_SET` indicates that error_code parameter is set. Data flags ---------- .. macro:: NGHTTP2_READ_DATA_FLAG_NONE :macro:`NGHTTP2_READ_DATA_FLAG_NONE` indicates no flag set. .. macro:: NGHTTP2_READ_DATA_FLAG_EOF :macro:`NGHTTP2_READ_DATA_FLAG_EOF` indicates that all request or response body has been provided to the library. It also indicates that sending side of stream is closed unless :macro:`NGHTTP2_READ_DATA_FLAG_NO_END_STREAM` is given at the same time. .. macro:: NGHTTP2_READ_DATA_FLAG_NO_END_STREAM :macro:`NGHTTP2_READ_DATA_FLAG_NO_END_STREAM` indicates that sending side of stream is not closed even if :macro:`NGHTTP2_READ_DATA_FLAG_EOF` is set. Usually this flag is used to send trailer fields with `nghttp2_conn_submit_trailers`. If `nghttp2_conn_submit_trailers` has been called, regardless of this flag, the submitted trailer fields are sent. HTTP stream priority flags -------------------------- .. macro:: NGHTTP2_DEFAULT_URGENCY :macro:`NGHTTP2_DEFAULT_URGENCY` is the default urgency level. .. macro:: NGHTTP2_URGENCY_HIGH :macro:`NGHTTP2_URGENCY_HIGH` is the highest urgency level. .. macro:: NGHTTP2_URGENCY_LOW :macro:`NGHTTP2_URGENCY_LOW` is the lowest urgency level. .. macro:: NGHTTP2_URGENCY_LEVELS :macro:`NGHTTP2_URGENCY_LEVELS` is the number of urgency levels. Flags for HPACK decoder ----------------------- .. macro:: NGHTTP2_HPACK_DECODE_FLAG_NONE :macro:`NGHTTP2_HPACK_DECODE_FLAG_NONE` indicates that no flag set. .. macro:: NGHTTP2_HPACK_DECODE_FLAG_EMIT :macro:`NGHTTP2_HPACK_DECODE_FLAG_EMIT` indicates that an HTTP field is successfully decoded. .. macro:: NGHTTP2_HPACK_DECODE_FLAG_FINAL :macro:`NGHTTP2_HPACK_DECODE_FLAG_FINAL` indicates that an entire HTTP field section has been decoded.