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_FATAL
 174
 175         (``-900``)
 176         The errors < :macro:`NGHTTP2_ERR_FATAL` mean that the library is
 177         under unexpected condition and processing was terminated (e.g.,
 178         out of memory).  If application receives this error code, it must
 179         stop using that :type:`nghttp2_session` object and only allowed
 180         operation for that object is deallocate it using
 181         `nghttp2_session_del()`.
 182     .. macro:: NGHTTP2_ERR_NOMEM
 183
 184         (``-901``)
 185         Out of memory.  This is a fatal error.
 186     .. macro:: NGHTTP2_ERR_CALLBACK_FAILURE
 187
 188         (``-902``)
 189         The user callback function failed.  This is a fatal error.
 190     .. macro:: NGHTTP2_ERR_BAD_CLIENT_MAGIC
 191
 192         (``-903``)
 193         Invalid client magic (see :macro:`NGHTTP2_CLIENT_MAGIC`) was
 194         received and further processing is not possible.
 195     .. macro:: NGHTTP2_ERR_FLOODED
 196
 197         (``-904``)
 198         Possible flooding by peer was detected in this HTTP/2 session.
 199         Flooding is measured by how many PING and SETTINGS frames with
 200         ACK flag set are queued for transmission.  These frames are
 201         response for the peer initiated frames, and peer can cause memory
 202         exhaustion on server side to send these frames forever and does
 203         not read network.
 204
 205 .. type:: nghttp2_nv_flag
 206
 207
 208     The flags for header field name/value pair.
 209
 210     .. macro:: NGHTTP2_NV_FLAG_NONE
 211
 212         (``0``)
 213         No flag set.
 214     .. macro:: NGHTTP2_NV_FLAG_NO_INDEX
 215
 216         (``0x01``)
 217         Indicates that this name/value pair must not be indexed ("Literal
 218         Header Field never Indexed" representation must be used in HPACK
 219         encoding).  Other implementation calls this bit as "sensitive".
 220     .. macro:: NGHTTP2_NV_FLAG_NO_COPY_NAME
 221
 222         (``0x02``)
 223         This flag is set solely by application.  If this flag is set, the
 224         library does not make a copy of header field name.  This could
 225         improve performance.
 226     .. macro:: NGHTTP2_NV_FLAG_NO_COPY_VALUE
 227
 228         (``0x04``)
 229         This flag is set solely by application.  If this flag is set, the
 230         library does not make a copy of header field value.  This could
 231         improve performance.
 232
 233 .. type:: nghttp2_frame_type
 234
 235
 236     The frame types in HTTP/2 specification.
 237
 238     .. macro:: NGHTTP2_DATA
 239
 240         (``0``)
 241         The DATA frame.
 242     .. macro:: NGHTTP2_HEADERS
 243
 244         (``0x01``)
 245         The HEADERS frame.
 246     .. macro:: NGHTTP2_PRIORITY
 247
 248         (``0x02``)
 249         The PRIORITY frame.
 250     .. macro:: NGHTTP2_RST_STREAM
 251
 252         (``0x03``)
 253         The RST_STREAM frame.
 254     .. macro:: NGHTTP2_SETTINGS
 255
 256         (``0x04``)
 257         The SETTINGS frame.
 258     .. macro:: NGHTTP2_PUSH_PROMISE
 259
 260         (``0x05``)
 261         The PUSH_PROMISE frame.
 262     .. macro:: NGHTTP2_PING
 263
 264         (``0x06``)
 265         The PING frame.
 266     .. macro:: NGHTTP2_GOAWAY
 267
 268         (``0x07``)
 269         The GOAWAY frame.
 270     .. macro:: NGHTTP2_WINDOW_UPDATE
 271
 272         (``0x08``)
 273         The WINDOW_UPDATE frame.
 274     .. macro:: NGHTTP2_CONTINUATION
 275
 276         (``0x09``)
 277         The CONTINUATION frame.  This frame type won't be passed to any
 278         callbacks because the library processes this frame type and its
 279         preceding HEADERS/PUSH_PROMISE as a single frame.
 280     .. macro:: NGHTTP2_ALTSVC
 281
 282         (``0x0a``)
 283         The ALTSVC frame, which is defined in `RFC 7383
 284         <https://tools.ietf.org/html/rfc7838#section-4>`_.
 285     .. macro:: NGHTTP2_ORIGIN
 286
 287         (``0x0c``)
 288         The ORIGIN frame, which is defined by `RFC 8336
 289         <https://tools.ietf.org/html/rfc8336>`_.
 290
 291 .. type:: nghttp2_flag
 292
 293
 294     The flags for HTTP/2 frames.  This enum defines all flags for all
 295     frames.
 296
 297     .. macro:: NGHTTP2_FLAG_NONE
 298
 299         (``0``)
 300         No flag set.
 301     .. macro:: NGHTTP2_FLAG_END_STREAM
 302
 303         (``0x01``)
 304         The END_STREAM flag.
 305     .. macro:: NGHTTP2_FLAG_END_HEADERS
 306
 307         (``0x04``)
 308         The END_HEADERS flag.
 309     .. macro:: NGHTTP2_FLAG_ACK
 310
 311         (``0x01``)
 312         The ACK flag.
 313     .. macro:: NGHTTP2_FLAG_PADDED
 314
 315         (``0x08``)
 316         The PADDED flag.
 317     .. macro:: NGHTTP2_FLAG_PRIORITY
 318
 319         (``0x20``)
 320         The PRIORITY flag.
 321
 322 .. type:: nghttp2_settings_id
 323
 324     The SETTINGS ID.
 325
 326     .. macro:: NGHTTP2_SETTINGS_HEADER_TABLE_SIZE
 327
 328         (``0x01``)
 329         SETTINGS_HEADER_TABLE_SIZE
 330     .. macro:: NGHTTP2_SETTINGS_ENABLE_PUSH
 331
 332         (``0x02``)
 333         SETTINGS_ENABLE_PUSH
 334     .. macro:: NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS
 335
 336         (``0x03``)
 337         SETTINGS_MAX_CONCURRENT_STREAMS
 338     .. macro:: NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE
 339
 340         (``0x04``)
 341         SETTINGS_INITIAL_WINDOW_SIZE
 342     .. macro:: NGHTTP2_SETTINGS_MAX_FRAME_SIZE
 343
 344         (``0x05``)
 345         SETTINGS_MAX_FRAME_SIZE
 346     .. macro:: NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE
 347
 348         (``0x06``)
 349         SETTINGS_MAX_HEADER_LIST_SIZE
 350     .. macro:: NGHTTP2_SETTINGS_ENABLE_CONNECT_PROTOCOL
 351
 352         (``0x08``)
 353         SETTINGS_ENABLE_CONNECT_PROTOCOL
 354         (`RFC 8441 <https://tools.ietf.org/html/rfc8441>`_)
 355
 356 .. type:: nghttp2_error_code
 357
 358     The status codes for the RST_STREAM and GOAWAY frames.
 359
 360     .. macro:: NGHTTP2_NO_ERROR
 361
 362         (``0x00``)
 363         No errors.
 364     .. macro:: NGHTTP2_PROTOCOL_ERROR
 365
 366         (``0x01``)
 367         PROTOCOL_ERROR
 368     .. macro:: NGHTTP2_INTERNAL_ERROR
 369
 370         (``0x02``)
 371         INTERNAL_ERROR
 372     .. macro:: NGHTTP2_FLOW_CONTROL_ERROR
 373
 374         (``0x03``)
 375         FLOW_CONTROL_ERROR
 376     .. macro:: NGHTTP2_SETTINGS_TIMEOUT
 377
 378         (``0x04``)
 379         SETTINGS_TIMEOUT
 380     .. macro:: NGHTTP2_STREAM_CLOSED
 381
 382         (``0x05``)
 383         STREAM_CLOSED
 384     .. macro:: NGHTTP2_FRAME_SIZE_ERROR
 385
 386         (``0x06``)
 387         FRAME_SIZE_ERROR
 388     .. macro:: NGHTTP2_REFUSED_STREAM
 389
 390         (``0x07``)
 391         REFUSED_STREAM
 392     .. macro:: NGHTTP2_CANCEL
 393
 394         (``0x08``)
 395         CANCEL
 396     .. macro:: NGHTTP2_COMPRESSION_ERROR
 397
 398         (``0x09``)
 399         COMPRESSION_ERROR
 400     .. macro:: NGHTTP2_CONNECT_ERROR
 401
 402         (``0x0a``)
 403         CONNECT_ERROR
 404     .. macro:: NGHTTP2_ENHANCE_YOUR_CALM
 405
 406         (``0x0b``)
 407         ENHANCE_YOUR_CALM
 408     .. macro:: NGHTTP2_INADEQUATE_SECURITY
 409
 410         (``0x0c``)
 411         INADEQUATE_SECURITY
 412     .. macro:: NGHTTP2_HTTP_1_1_REQUIRED
 413
 414         (``0x0d``)
 415         HTTP_1_1_REQUIRED
 416
 417 .. type:: nghttp2_data_flag
 418
 419
 420     The flags used to set in *data_flags* output parameter in
 421     :type:`nghttp2_data_source_read_callback`.
 422
 423     .. macro:: NGHTTP2_DATA_FLAG_NONE
 424
 425         (``0``)
 426         No flag set.
 427     .. macro:: NGHTTP2_DATA_FLAG_EOF
 428
 429         (``0x01``)
 430         Indicates EOF was sensed.
 431     .. macro:: NGHTTP2_DATA_FLAG_NO_END_STREAM
 432
 433         (``0x02``)
 434         Indicates that END_STREAM flag must not be set even if
 435         NGHTTP2_DATA_FLAG_EOF is set.  Usually this flag is used to send
 436         trailer fields with `nghttp2_submit_request()` or
 437         `nghttp2_submit_response()`.
 438     .. macro:: NGHTTP2_DATA_FLAG_NO_COPY
 439
 440         (``0x04``)
 441         Indicates that application will send complete DATA frame in
 442         :type:`nghttp2_send_data_callback`.
 443
 444 .. type:: nghttp2_headers_category
 445
 446
 447     The category of HEADERS, which indicates the role of the frame.  In
 448     HTTP/2 spec, request, response, push response and other arbitrary
 449     headers (e.g., trailer fields) are all called just HEADERS.  To
 450     give the application the role of incoming HEADERS frame, we define
 451     several categories.
 452
 453     .. macro:: NGHTTP2_HCAT_REQUEST
 454
 455         (``0``)
 456         The HEADERS frame is opening new stream, which is analogous to
 457         SYN_STREAM in SPDY.
 458     .. macro:: NGHTTP2_HCAT_RESPONSE
 459
 460         (``1``)
 461         The HEADERS frame is the first response headers, which is
 462         analogous to SYN_REPLY in SPDY.
 463     .. macro:: NGHTTP2_HCAT_PUSH_RESPONSE
 464
 465         (``2``)
 466         The HEADERS frame is the first headers sent against reserved
 467         stream.
 468     .. macro:: NGHTTP2_HCAT_HEADERS
 469
 470         (``3``)
 471         The HEADERS frame which does not apply for the above categories,
 472         which is analogous to HEADERS in SPDY.  If non-final response
 473         (e.g., status 1xx) is used, final response HEADERS frame will be
 474         categorized here.
 475
 476 .. type:: nghttp2_hd_inflate_flag
 477
 478
 479     The flags for header inflation.
 480
 481     .. macro:: NGHTTP2_HD_INFLATE_NONE
 482
 483         (``0``)
 484         No flag set.
 485     .. macro:: NGHTTP2_HD_INFLATE_FINAL
 486
 487         (``0x01``)
 488         Indicates all headers were inflated.
 489     .. macro:: NGHTTP2_HD_INFLATE_EMIT
 490
 491         (``0x02``)
 492         Indicates a header was emitted.
 493
 494 .. type:: nghttp2_stream_proto_state
 495
 496
 497     State of stream as described in RFC 7540.
 498
 499     .. macro:: NGHTTP2_STREAM_STATE_IDLE
 500
 501         (``1``)
 502         idle state.
 503     .. macro:: NGHTTP2_STREAM_STATE_OPEN,
 504
 505         open state.
 506     .. macro:: NGHTTP2_STREAM_STATE_RESERVED_LOCAL,
 507
 508         reserved (local) state.
 509     .. macro:: NGHTTP2_STREAM_STATE_RESERVED_REMOTE,
 510
 511         reserved (remote) state.
 512     .. macro:: NGHTTP2_STREAM_STATE_HALF_CLOSED_LOCAL,
 513
 514         half closed (local) state.
 515     .. macro:: NGHTTP2_STREAM_STATE_HALF_CLOSED_REMOTE,
 516
 517         half closed (remote) state.
 518     .. macro:: NGHTTP2_STREAM_STATE_CLOSED
 519
 520         closed state.
 521