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 frame for a given stream has been already submitted and has
 139         not been fully processed yet.
 140     .. macro:: NGHTTP2_ERR_SESSION_CLOSING
 141
 142         (``-530``)
 143         The current session is closing due to a connection error or
 144         `nghttp2_session_terminate_session()` is called.
 145     .. macro:: NGHTTP2_ERR_HTTP_HEADER
 146
 147         (``-531``)
 148         Invalid HTTP header field was received and stream is going to be
 149         closed.
 150     .. macro:: NGHTTP2_ERR_HTTP_MESSAGING
 151
 152         (``-532``)
 153         Violation in HTTP messaging rule.
 154     .. macro:: NGHTTP2_ERR_REFUSED_STREAM
 155
 156         (``-533``)
 157         Stream was refused.
 158     .. macro:: NGHTTP2_ERR_INTERNAL
 159
 160         (``-534``)
 161         Unexpected internal error, but recovered.
 162     .. macro:: NGHTTP2_ERR_FATAL
 163
 164         (``-900``)
 165         The errors < :macro:`NGHTTP2_ERR_FATAL` mean that the library is
 166         under unexpected condition and processing was terminated (e.g.,
 167         out of memory).  If application receives this error code, it must
 168         stop using that :type:`nghttp2_session` object and only allowed
 169         operation for that object is deallocate it using
 170         `nghttp2_session_del()`.
 171     .. macro:: NGHTTP2_ERR_NOMEM
 172
 173         (``-901``)
 174         Out of memory.  This is a fatal error.
 175     .. macro:: NGHTTP2_ERR_CALLBACK_FAILURE
 176
 177         (``-902``)
 178         The user callback function failed.  This is a fatal error.
 179     .. macro:: NGHTTP2_ERR_BAD_CLIENT_MAGIC
 180
 181         (``-903``)
 182         Invalid client magic (see :macro:`NGHTTP2_CLIENT_MAGIC`) was
 183         received and further processing is not possible.
 184
 185 .. type:: nghttp2_nv_flag
 186
 187
 188     The flags for header field name/value pair.
 189
 190     .. macro:: NGHTTP2_NV_FLAG_NONE
 191
 192         (``0``)
 193         No flag set.
 194     .. macro:: NGHTTP2_NV_FLAG_NO_INDEX
 195
 196         (``0x01``)
 197         Indicates that this name/value pair must not be indexed ("Literal
 198         Header Field never Indexed" representation must be used in HPACK
 199         encoding).  Other implementation calls this bit as "sensitive".
 200
 201 .. type:: nghttp2_frame_type
 202
 203
 204     The frame types in HTTP/2 specification.
 205
 206     .. macro:: NGHTTP2_DATA
 207
 208         (``0``)
 209         The DATA frame.
 210     .. macro:: NGHTTP2_HEADERS
 211
 212         (``0x01``)
 213         The HEADERS frame.
 214     .. macro:: NGHTTP2_PRIORITY
 215
 216         (``0x02``)
 217         The PRIORITY frame.
 218     .. macro:: NGHTTP2_RST_STREAM
 219
 220         (``0x03``)
 221         The RST_STREAM frame.
 222     .. macro:: NGHTTP2_SETTINGS
 223
 224         (``0x04``)
 225         The SETTINGS frame.
 226     .. macro:: NGHTTP2_PUSH_PROMISE
 227
 228         (``0x05``)
 229         The PUSH_PROMISE frame.
 230     .. macro:: NGHTTP2_PING
 231
 232         (``0x06``)
 233         The PING frame.
 234     .. macro:: NGHTTP2_GOAWAY
 235
 236         (``0x07``)
 237         The GOAWAY frame.
 238     .. macro:: NGHTTP2_WINDOW_UPDATE
 239
 240         (``0x08``)
 241         The WINDOW_UPDATE frame.
 242     .. macro:: NGHTTP2_CONTINUATION
 243
 244         (``0x09``)
 245         The CONTINUATION frame.  This frame type won't be passed to any
 246         callbacks because the library processes this frame type and its
 247         preceding HEADERS/PUSH_PROMISE as a single frame.
 248
 249 .. type:: nghttp2_flag
 250
 251
 252     The flags for HTTP/2 frames.  This enum defines all flags for all
 253     frames.
 254
 255     .. macro:: NGHTTP2_FLAG_NONE
 256
 257         (``0``)
 258         No flag set.
 259     .. macro:: NGHTTP2_FLAG_END_STREAM
 260
 261         (``0x01``)
 262         The END_STREAM flag.
 263     .. macro:: NGHTTP2_FLAG_END_HEADERS
 264
 265         (``0x04``)
 266         The END_HEADERS flag.
 267     .. macro:: NGHTTP2_FLAG_ACK
 268
 269         (``0x01``)
 270         The ACK flag.
 271     .. macro:: NGHTTP2_FLAG_PADDED
 272
 273         (``0x08``)
 274         The PADDED flag.
 275     .. macro:: NGHTTP2_FLAG_PRIORITY
 276
 277         (``0x20``)
 278         The PRIORITY flag.
 279
 280 .. type:: nghttp2_settings_id
 281
 282     The SETTINGS ID.
 283
 284     .. macro:: NGHTTP2_SETTINGS_HEADER_TABLE_SIZE
 285
 286         (``0x01``)
 287         SETTINGS_HEADER_TABLE_SIZE
 288     .. macro:: NGHTTP2_SETTINGS_ENABLE_PUSH
 289
 290         (``0x02``)
 291         SETTINGS_ENABLE_PUSH
 292     .. macro:: NGHTTP2_SETTINGS_MAX_CONCURRENT_STREAMS
 293
 294         (``0x03``)
 295         SETTINGS_MAX_CONCURRENT_STREAMS
 296     .. macro:: NGHTTP2_SETTINGS_INITIAL_WINDOW_SIZE
 297
 298         (``0x04``)
 299         SETTINGS_INITIAL_WINDOW_SIZE
 300     .. macro:: NGHTTP2_SETTINGS_MAX_FRAME_SIZE
 301
 302         (``0x05``)
 303         SETTINGS_MAX_FRAME_SIZE
 304     .. macro:: NGHTTP2_SETTINGS_MAX_HEADER_LIST_SIZE
 305
 306         (``0x06``)
 307         SETTINGS_MAX_HEADER_LIST_SIZE
 308
 309 .. type:: nghttp2_error_code
 310
 311     The status codes for the RST_STREAM and GOAWAY frames.
 312
 313     .. macro:: NGHTTP2_NO_ERROR
 314
 315         (``0x00``)
 316         No errors.
 317     .. macro:: NGHTTP2_PROTOCOL_ERROR
 318
 319         (``0x01``)
 320         PROTOCOL_ERROR
 321     .. macro:: NGHTTP2_INTERNAL_ERROR
 322
 323         (``0x02``)
 324         INTERNAL_ERROR
 325     .. macro:: NGHTTP2_FLOW_CONTROL_ERROR
 326
 327         (``0x03``)
 328         FLOW_CONTROL_ERROR
 329     .. macro:: NGHTTP2_SETTINGS_TIMEOUT
 330
 331         (``0x04``)
 332         SETTINGS_TIMEOUT
 333     .. macro:: NGHTTP2_STREAM_CLOSED
 334
 335         (``0x05``)
 336         STREAM_CLOSED
 337     .. macro:: NGHTTP2_FRAME_SIZE_ERROR
 338
 339         (``0x06``)
 340         FRAME_SIZE_ERROR
 341     .. macro:: NGHTTP2_REFUSED_STREAM
 342
 343         (``0x07``)
 344         REFUSED_STREAM
 345     .. macro:: NGHTTP2_CANCEL
 346
 347         (``0x08``)
 348         CANCEL
 349     .. macro:: NGHTTP2_COMPRESSION_ERROR
 350
 351         (``0x09``)
 352         COMPRESSION_ERROR
 353     .. macro:: NGHTTP2_CONNECT_ERROR
 354
 355         (``0x0a``)
 356         CONNECT_ERROR
 357     .. macro:: NGHTTP2_ENHANCE_YOUR_CALM
 358
 359         (``0x0b``)
 360         ENHANCE_YOUR_CALM
 361     .. macro:: NGHTTP2_INADEQUATE_SECURITY
 362
 363         (``0x0c``)
 364         INADEQUATE_SECURITY
 365     .. macro:: NGHTTP2_HTTP_1_1_REQUIRED
 366
 367         (``0x0d``)
 368         HTTP_1_1_REQUIRED
 369
 370 .. type:: nghttp2_data_flag
 371
 372
 373     The flags used to set in *data_flags* output parameter in
 374     :type:`nghttp2_data_source_read_callback`.
 375
 376     .. macro:: NGHTTP2_DATA_FLAG_NONE
 377
 378         (``0``)
 379         No flag set.
 380     .. macro:: NGHTTP2_DATA_FLAG_EOF
 381
 382         (``0x01``)
 383         Indicates EOF was sensed.
 384     .. macro:: NGHTTP2_DATA_FLAG_NO_END_STREAM
 385
 386         (``0x02``)
 387         Indicates that END_STREAM flag must not be set even if
 388         NGHTTP2_DATA_FLAG_EOF is set.  Usually this flag is used to send
 389         trailer header fields with `nghttp2_submit_request()` or
 390         `nghttp2_submit_response()`.
 391     .. macro:: NGHTTP2_DATA_FLAG_NO_COPY
 392
 393         (``0x04``)
 394         Indicates that application will send complete DATA frame in
 395         :type:`nghttp2_send_data_callback`.
 396
 397 .. type:: nghttp2_headers_category
 398
 399
 400     The category of HEADERS, which indicates the role of the frame.  In
 401     HTTP/2 spec, request, response, push response and other arbitrary
 402     headers (e.g., trailers) are all called just HEADERS.  To give the
 403     application the role of incoming HEADERS frame, we define several
 404     categories.
 405
 406     .. macro:: NGHTTP2_HCAT_REQUEST
 407
 408         (``0``)
 409         The HEADERS frame is opening new stream, which is analogous to
 410         SYN_STREAM in SPDY.
 411     .. macro:: NGHTTP2_HCAT_RESPONSE
 412
 413         (``1``)
 414         The HEADERS frame is the first response headers, which is
 415         analogous to SYN_REPLY in SPDY.
 416     .. macro:: NGHTTP2_HCAT_PUSH_RESPONSE
 417
 418         (``2``)
 419         The HEADERS frame is the first headers sent against reserved
 420         stream.
 421     .. macro:: NGHTTP2_HCAT_HEADERS
 422
 423         (``3``)
 424         The HEADERS frame which does not apply for the above categories,
 425         which is analogous to HEADERS in SPDY.  If non-final response
 426         (e.g., status 1xx) is used, final response HEADERS frame will be
 427         categorized here.
 428
 429 .. type:: nghttp2_hd_inflate_flag
 430
 431
 432     The flags for header inflation.
 433
 434     .. macro:: NGHTTP2_HD_INFLATE_NONE
 435
 436         (``0``)
 437         No flag set.
 438     .. macro:: NGHTTP2_HD_INFLATE_FINAL
 439
 440         (``0x01``)
 441         Indicates all headers were inflated.
 442     .. macro:: NGHTTP2_HD_INFLATE_EMIT
 443
 444         (``0x02``)
 445         Indicates a header was emitted.
 446