doc/enums.rst

   1
   2 Enums
   3 =====
   4 .. type:: nghttp2_error
   5
   6
   7     Error codes used in this library.  The code range is [-999, -500],
   8     inclusive. The following values are defined:
   9
  10     .. macro:: NGHTTP2_ERR_INVALID_ARGUMENT
  11
  12         (``-501``)
  13         Invalid argument passed.
  14     .. macro:: NGHTTP2_ERR_BUFFER_ERROR
  15
  16         (``-502``)
  17         Out of buffer space.
  18     .. macro:: NGHTTP2_ERR_UNSUPPORTED_VERSION
  19
  20         (``-503``)
  21         The specified protocol version is not supported.
  22     .. macro:: NGHTTP2_ERR_WOULDBLOCK
  23
  24         (``-504``)
  25         Used as a return value from :type:`nghttp2_send_callback`,
  26         :type:`nghttp2_recv_callback` and
  27         :type:`nghttp2_send_data_callback` to indicate that the operation
  28         would block.
  29     .. macro:: NGHTTP2_ERR_PROTO
  30
  31         (``-505``)
  32         General protocol error
  33     .. macro:: NGHTTP2_ERR_INVALID_FRAME
  34
  35         (``-506``)
  36         The frame is invalid.
  37     .. macro:: NGHTTP2_ERR_EOF
  38
  39         (``-507``)
  40         The peer performed a shutdown on the connection.
  41     .. macro:: NGHTTP2_ERR_DEFERRED
  42
  43         (``-508``)
  44         Used as a return value from
  45         :func:`nghttp2_data_source_read_callback` to indicate that data
  46         transfer is postponed.  See
  47         :func:`nghttp2_data_source_read_callback` for details.
  48     .. macro:: NGHTTP2_ERR_STREAM_ID_NOT_AVAILABLE
  49
  50         (``-509``)
  51         Stream ID has reached the maximum value.  Therefore no stream ID
  52         is available.
  53     .. macro:: NGHTTP2_ERR_STREAM_CLOSED
  54
  55         (``-510``)
  56         The stream is already closed; or the stream ID is invalid.
  57     .. macro:: NGHTTP2_ERR_STREAM_CLOSING
  58
  59         (``-511``)
  60         RST_STREAM has been added to the outbound queue.  The stream is
  61         in closing state.
  62     .. macro:: NGHTTP2_ERR_STREAM_SHUT_WR
  63
  64         (``-512``)
  65         The transmission is not allowed for this stream (e.g., a frame
  66         with END_STREAM flag set has already sent).
  67     .. macro:: NGHTTP2_ERR_INVALID_STREAM_ID
  68
  69         (``-513``)
  70         The stream ID is invalid.
  71     .. macro:: NGHTTP2_ERR_INVALID_STREAM_STATE
  72
  73         (``-514``)
  74         The state of the stream is not valid (e.g., DATA cannot be sent
  75         to the stream if response HEADERS has not been sent).
  76     .. macro:: NGHTTP2_ERR_DEFERRED_DATA_EXIST
  77
  78         (``-515``)
  79         Another DATA frame has already been deferred.
  80     .. macro:: NGHTTP2_ERR_START_STREAM_NOT_ALLOWED
  81
  82         (``-516``)
  83         Starting new stream is not allowed (e.g., GOAWAY has been sent
  84         and/or received).
  85     .. macro:: NGHTTP2_ERR_GOAWAY_ALREADY_SENT
  86
  87         (``-517``)
  88         GOAWAY has already been sent.
  89     .. macro:: NGHTTP2_ERR_INVALID_HEADER_BLOCK
  90
  91         (``-518``)
  92         The received frame contains the invalid header block (e.g., There
  93         are duplicate header names; or the header names are not encoded
  94         in US-ASCII character set and not lower cased; or the header name
  95         is zero-length string; or the header value contains multiple
  96         in-sequence NUL bytes).
  97     .. macro:: NGHTTP2_ERR_INVALID_STATE
  98
  99         (``-519``)
 100         Indicates that the context is not suitable to perform the
 101         requested operation.
 102     .. macro:: NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE
 103
 104         (``-521``)
 105         The user callback function failed due to the temporal error.
 106     .. macro:: NGHTTP2_ERR_FRAME_SIZE_ERROR
 107
 108         (``-522``)
 109         The length of the frame is invalid, either too large or too small.
 110     .. macro:: NGHTTP2_ERR_HEADER_COMP
 111
 112         (``-523``)
 113         Header block inflate/deflate error.
 114     .. macro:: NGHTTP2_ERR_FLOW_CONTROL
 115
 116         (``-524``)
 117         Flow control error
 118     .. macro:: NGHTTP2_ERR_INSUFF_BUFSIZE
 119
 120         (``-525``)
 121         Insufficient buffer size given to function.
 122     .. macro:: NGHTTP2_ERR_PAUSE
 123
 124         (``-526``)
 125         Callback was paused by the application
 126     .. macro:: NGHTTP2_ERR_TOO_MANY_INFLIGHT_SETTINGS
 127
 128         (``-527``)
 129         There are too many in-flight SETTING frame and no more
 130         transmission of SETTINGS is allowed.
 131     .. macro:: NGHTTP2_ERR_PUSH_DISABLED
 132
 133         (``-528``)
 134         The server push is disabled.
 135     .. macro:: NGHTTP2_ERR_DATA_EXIST
 136
 137         (``-529``)
 138         DATA or HEADERS frame for a given stream has been already
 139         submitted and has not been fully processed yet.  Application
 140         should wait for the transmission of the previously submitted
 141         frame before submitting another.
 142     .. macro:: NGHTTP2_ERR_SESSION_CLOSING
 143
 144         (``-530``)
 145         The current session is closing due to a connection error or
 146         `nghttp2_session_terminate_session()` is called.
 147     .. macro:: NGHTTP2_ERR_HTTP_HEADER
 148
 149         (``-531``)
 150         Invalid HTTP header field was received and stream is going to be
 151         closed.
 152     .. macro:: NGHTTP2_ERR_HTTP_MESSAGING
 153
 154         (``-532``)
 155         Violation in HTTP messaging rule.
 156     .. macro:: NGHTTP2_ERR_REFUSED_STREAM
 157
 158         (``-533``)
 159         Stream was refused.
 160     .. macro:: NGHTTP2_ERR_INTERNAL
 161
 162         (``-534``)
 163         Unexpected internal error, but recovered.
 164     .. macro:: NGHTTP2_ERR_CANCEL
 165
 166         (``-535``)
 167         Indicates that a processing was canceled.
 168     .. macro:: NGHTTP2_ERR_SETTINGS_EXPECTED
 169
 170         (``-536``)
 171         When a local endpoint expects to receive SETTINGS frame, it
 172         receives an other type of frame.
 173     .. macro:: NGHTTP2_ERR_TOO_MANY_SETTINGS
 174
 175         (``-537``)
 176         When a local endpoint receives too many settings entries
 177         in a single SETTINGS frame.
 178     .. macro:: NGHTTP2_ERR_FATAL
 179
 180         (``-900``)
 181         The errors < :macro:`NGHTTP2_ERR_FATAL` mean that the library is
 182         under unexpected condition and processing was terminated (e.g.,
 183         out of memory).  If application receives this error code, it must
 184         stop using that :type:`nghttp2_session` object and only allowed
 185         operation for that object is deallocate it using
 186         `nghttp2_session_del()`.
 187     .. macro:: NGHTTP2_ERR_NOMEM
 188
 189         (``-901``)
 190         Out of memory.  This is a fatal error.
 191     .. macro:: NGHTTP2_ERR_CALLBACK_FAILURE
 192
 193         (``-902``)
 194         The user callback function failed.  This is a fatal error.
 195     .. macro:: NGHTTP2_ERR_BAD_CLIENT_MAGIC
 196
 197         (``-903``)
 198         Invalid client magic (see :macro:`NGHTTP2_CLIENT_MAGIC`) was
 199         received and further processing is not possible.
 200     .. macro:: NGHTTP2_ERR_FLOODED
 201
 202         (``-904``)
 203         Possible flooding by peer was detected in this HTTP/2 session.
 204         Flooding is measured by how many PING and SETTINGS frames with
 205         ACK flag set are queued for transmission.  These frames are
 206         response for the peer initiated frames, and peer can cause memory
 207         exhaustion on server side to send these frames forever and does
 208         not read network.
 209
 210 .. type:: nghttp2_nv_flag
 211
 212
 213     The flags for header field name/value pair.
 214
 215     .. macro:: NGHTTP2_NV_FLAG_NONE
 216
 217         (``0``)
 218         No flag set.
 219     .. macro:: NGHTTP2_NV_FLAG_NO_INDEX
 220
 221         (``0x01``)
 222         Indicates that this name/value pair must not be indexed ("Literal
 223         Header Field never Indexed" representation must be used in HPACK
 224         encoding).  Other implementation calls this bit as "sensitive".
 225     .. macro:: NGHTTP2_NV_FLAG_NO_COPY_NAME
 226
 227         (``0x02``)
 228         This flag is set solely by application.  If this flag is set, the
 229         library does not make a copy of header field name.  This could
 230         improve performance.
 231     .. macro:: NGHTTP2_NV_FLAG_NO_COPY_VALUE
 232
 233         (``0x04``)
 234         This flag is set solely by application.  If this flag is set, the
 235         library does not make a copy of header field value.  This could
 236         improve performance.
 237
 238 .. type:: nghttp2_frame_type
 239
 240
 241     The frame types in HTTP/2 specification.
 242
 243     .. macro:: NGHTTP2_DATA
 244
 245         (``0``)
 246         The DATA frame.
 247     .. macro:: NGHTTP2_HEADERS
 248
 249         (``0x01``)
 250         The HEADERS frame.
 251     .. macro:: NGHTTP2_PRIORITY
 252
 253         (``0x02``)
 254         The PRIORITY frame.
 255     .. macro:: NGHTTP2_RST_STREAM
 256
 257         (``0x03``)
 258         The RST_STREAM frame.
 259     .. macro:: NGHTTP2_SETTINGS
 260
 261         (``0x04``)
 262         The SETTINGS frame.
 263     .. macro:: NGHTTP2_PUSH_PROMISE
 264
 265         (``0x05``)
 266         The PUSH_PROMISE frame.
 267     .. macro:: NGHTTP2_PING
 268
 269         (``0x06``)
 270         The PING frame.
 271     .. macro:: NGHTTP2_GOAWAY
 272
 273         (``0x07``)
 274         The GOAWAY frame.
 275     .. macro:: NGHTTP2_WINDOW_UPDATE
 276
 277         (``0x08``)
 278         The WINDOW_UPDATE frame.
 279     .. macro:: NGHTTP2_CONTINUATION
 280
 281         (``0x09``)
 282         The CONTINUATION frame.  This frame type won't be passed to any
 283         callbacks because the library processes this frame type and its
 284         preceding HEADERS/PUSH_PROMISE as a single frame.
 285     .. macro:: NGHTTP2_ALTSVC
 286
 287         (``0x0a``)
 288         The ALTSVC frame, which is defined in `RFC 7383
 289         <https://tools.ietf.org/html/rfc7838#section-4>`_.
 290     .. macro:: NGHTTP2_ORIGIN
 291
 292         (``0x0c``)
 293         The ORIGIN frame, which is defined by `RFC 8336
 294         <https://tools.ietf.org/html/rfc8336>`_.
 295
 296 .. type:: nghttp2_flag
 297
 298
 299     The flags for HTTP/2 frames.  This enum defines all flags for all
 300     frames.
 301
 302     .. macro:: NGHTTP2_FLAG_NONE
 303
 304         (``0``)
 305         No flag set.
 306     .. macro:: NGHTTP2_FLAG_END_STREAM
 307
 308         (``0x01``)
 309         The END_STREAM flag.
 310     .. macro:: NGHTTP2_FLAG_END_HEADERS
 311
 312         (``0x04``)
 313         The END_HEADERS flag.
 314     .. macro:: NGHTTP2_FLAG_ACK
 315
 316         (``0x01``)
 317         The ACK flag.
 318     .. macro:: NGHTTP2_FLAG_PADDED
 319
 320         (``0x08``)
 321         The PADDED flag.
 322     .. macro:: NGHTTP2_FLAG_PRIORITY
 323
 324         (``0x20``)
 325         The PRIORITY flag.
 326
 327 .. type:: nghttp2_settings_id
 328
 329     The SETTINGS ID.
 330
 331     .. macro:: NGHTTP2_SETTINGS_HEADER_TABLE_SIZE
 332
 333         (``0x01``)
 334         SETTINGS_HEADER_TABLE_SIZE
 335     .. macro:: NGHTTP2_SETTINGS_ENABLE_PUSH
 336
 337         (``0x02``)
 338         SETTINGS_ENABLE_PUSH
 339     .. macro:: NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS
 340
 341         (``0x03``)
 342         SETTINGS_MAX_CONCURRENT_STREAMS
 343     .. macro:: NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE
 344
 345         (``0x04``)
 346         SETTINGS_INITIAL_WINDOW_SIZE
 347     .. macro:: NGHTTP2_SETTINGS_MAX_FRAME_SIZE
 348
 349         (``0x05``)
 350         SETTINGS_MAX_FRAME_SIZE
 351     .. macro:: NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE
 352
 353         (``0x06``)
 354         SETTINGS_MAX_HEADER_LIST_SIZE
 355     .. macro:: NGHTTP2_SETTINGS_ENABLE_CONNECT_PROTOCOL
 356
 357         (``0x08``)
 358         SETTINGS_ENABLE_CONNECT_PROTOCOL
 359         (`RFC 8441 <https://tools.ietf.org/html/rfc8441>`_)
 360
 361 .. type:: nghttp2_error_code
 362
 363     The status codes for the RST_STREAM and GOAWAY frames.
 364
 365     .. macro:: NGHTTP2_NO_ERROR
 366
 367         (``0x00``)
 368         No errors.
 369     .. macro:: NGHTTP2_PROTOCOL_ERROR
 370
 371         (``0x01``)
 372         PROTOCOL_ERROR
 373     .. macro:: NGHTTP2_INTERNAL_ERROR
 374
 375         (``0x02``)
 376         INTERNAL_ERROR
 377     .. macro:: NGHTTP2_FLOW_CONTROL_ERROR
 378
 379         (``0x03``)
 380         FLOW_CONTROL_ERROR
 381     .. macro:: NGHTTP2_SETTINGS_TIMEOUT
 382
 383         (``0x04``)
 384         SETTINGS_TIMEOUT
 385     .. macro:: NGHTTP2_STREAM_CLOSED
 386
 387         (``0x05``)
 388         STREAM_CLOSED
 389     .. macro:: NGHTTP2_FRAME_SIZE_ERROR
 390
 391         (``0x06``)
 392         FRAME_SIZE_ERROR
 393     .. macro:: NGHTTP2_REFUSED_STREAM
 394
 395         (``0x07``)
 396         REFUSED_STREAM
 397     .. macro:: NGHTTP2_CANCEL
 398
 399         (``0x08``)
 400         CANCEL
 401     .. macro:: NGHTTP2_COMPRESSION_ERROR
 402
 403         (``0x09``)
 404         COMPRESSION_ERROR
 405     .. macro:: NGHTTP2_CONNECT_ERROR
 406
 407         (``0x0a``)
 408         CONNECT_ERROR
 409     .. macro:: NGHTTP2_ENHANCE_YOUR_CALM
 410
 411         (``0x0b``)
 412         ENHANCE_YOUR_CALM
 413     .. macro:: NGHTTP2_INADEQUATE_SECURITY
 414
 415         (``0x0c``)
 416         INADEQUATE_SECURITY
 417     .. macro:: NGHTTP2_HTTP_1_1_REQUIRED
 418
 419         (``0x0d``)
 420         HTTP_1_1_REQUIRED
 421
 422 .. type:: nghttp2_data_flag
 423
 424
 425     The flags used to set in *data_flags* output parameter in
 426     :type:`nghttp2_data_source_read_callback`.
 427
 428     .. macro:: NGHTTP2_DATA_FLAG_NONE
 429
 430         (``0``)
 431         No flag set.
 432     .. macro:: NGHTTP2_DATA_FLAG_EOF
 433
 434         (``0x01``)
 435         Indicates EOF was sensed.
 436     .. macro:: NGHTTP2_DATA_FLAG_NO_END_STREAM
 437
 438         (``0x02``)
 439         Indicates that END_STREAM flag must not be set even if
 440         NGHTTP2_DATA_FLAG_EOF is set.  Usually this flag is used to send
 441         trailer fields with `nghttp2_submit_request()` or
 442         `nghttp2_submit_response()`.
 443     .. macro:: NGHTTP2_DATA_FLAG_NO_COPY
 444
 445         (``0x04``)
 446         Indicates that application will send complete DATA frame in
 447         :type:`nghttp2_send_data_callback`.
 448
 449 .. type:: nghttp2_headers_category
 450
 451
 452     The category of HEADERS, which indicates the role of the frame.  In
 453     HTTP/2 spec, request, response, push response and other arbitrary
 454     headers (e.g., trailer fields) are all called just HEADERS.  To
 455     give the application the role of incoming HEADERS frame, we define
 456     several categories.
 457
 458     .. macro:: NGHTTP2_HCAT_REQUEST
 459
 460         (``0``)
 461         The HEADERS frame is opening new stream, which is analogous to
 462         SYN_STREAM in SPDY.
 463     .. macro:: NGHTTP2_HCAT_RESPONSE
 464
 465         (``1``)
 466         The HEADERS frame is the first response headers, which is
 467         analogous to SYN_REPLY in SPDY.
 468     .. macro:: NGHTTP2_HCAT_PUSH_RESPONSE
 469
 470         (``2``)
 471         The HEADERS frame is the first headers sent against reserved
 472         stream.
 473     .. macro:: NGHTTP2_HCAT_HEADERS
 474
 475         (``3``)
 476         The HEADERS frame which does not apply for the above categories,
 477         which is analogous to HEADERS in SPDY.  If non-final response
 478         (e.g., status 1xx) is used, final response HEADERS frame will be
 479         categorized here.
 480
 481 .. type:: nghttp2_hd_inflate_flag
 482
 483
 484     The flags for header inflation.
 485
 486     .. macro:: NGHTTP2_HD_INFLATE_NONE
 487
 488         (``0``)
 489         No flag set.
 490     .. macro:: NGHTTP2_HD_INFLATE_FINAL
 491
 492         (``0x01``)
 493         Indicates all headers were inflated.
 494     .. macro:: NGHTTP2_HD_INFLATE_EMIT
 495
 496         (``0x02``)
 497         Indicates a header was emitted.
 498
 499 .. type:: nghttp2_stream_proto_state
 500
 501
 502     State of stream as described in RFC 7540.
 503
 504     .. macro:: NGHTTP2_STREAM_STATE_IDLE
 505
 506         (``1``)
 507         idle state.
 508     .. macro:: NGHTTP2_STREAM_STATE_OPEN,
 509
 510         open state.
 511     .. macro:: NGHTTP2_STREAM_STATE_RESERVED_LOCAL,
 512
 513         reserved (local) state.
 514     .. macro:: NGHTTP2_STREAM_STATE_RESERVED_REMOTE,
 515
 516         reserved (remote) state.
 517     .. macro:: NGHTTP2_STREAM_STATE_HALF_CLOSED_LOCAL,
 518
 519         half closed (local) state.
 520     .. macro:: NGHTTP2_STREAM_STATE_HALF_CLOSED_REMOTE,
 521
 522         half closed (remote) state.
 523     .. macro:: NGHTTP2_STREAM_STATE_CLOSED
 524
 525         closed state.
 526