doc/types.rst

   1
   2 Types (structs, unions and typedefs)
   3 ====================================
   4 .. type:: nghttp2_session
   5
   6
   7     The primary structure to hold the resources needed for a HTTP/2
   8     session.  The details of this structure are intentionally hidden
   9     from the public API.
  10
  11
  12 .. type:: nghttp2_info
  13
  14
  15     This struct is what `nghttp2_version()` returns.  It holds
  16     information about the particular nghttp2 version.
  17
  18     .. member::   int age
  19
  20         Age of this struct.  This instance of nghttp2 sets it to
  21         :macro:`NGHTTP2_VERSION_AGE` but a future version may bump it and
  22         add more struct fields at the bottom
  23     .. member::   int version_num
  24
  25         the :macro:`NGHTTP2_VERSION_NUM` number (since age ==1)
  26     .. member::   const char *version_str
  27
  28         points to the :macro:`NGHTTP2_VERSION` string (since age ==1)
  29     .. member::   const char *proto_str
  30
  31         points to the :macro:`NGHTTP2_PROTO_VERSION_ID` string this
  32         instance implements (since age ==1)
  33
  34 .. type:: nghttp2_nv
  35
  36
  37     The name/value pair, which mainly used to represent header fields.
  38
  39     .. member::   uint8_t *name
  40
  41         The *name* byte string.  If this struct is presented from library
  42         (e.g., :type:`nghttp2_on_frame_recv_callback`), *name* is
  43         guaranteed to be NULL-terminated.  When application is
  44         constructing this struct, *name* is not required to be
  45         NULL-terminated.
  46     .. member::   uint8_t *value
  47
  48         The *value* byte string.  If this struct is presented from
  49         library (e.g., :type:`nghttp2_on_frame_recv_callback`), *value*
  50         is guaranteed to be NULL-terminated.  When application is
  51         constructing this struct, *value* is not required to be
  52         NULL-terminated.
  53     .. member::   size_t namelen
  54
  55         The length of the *name*, excluding terminating NULL.
  56     .. member::   size_t valuelen
  57
  58         The length of the *value*, excluding terminating NULL.
  59     .. member::   uint8_t flags
  60
  61         Bitwise OR of one or more of :type:`nghttp2_nv_flag`.
  62
  63 .. type:: nghttp2_frame_hd
  64
  65     The frame header.
  66
  67     .. member::   size_t length
  68
  69         The length field of this frame, excluding frame header.
  70     .. member::   int32_t stream_id
  71
  72         The stream identifier (aka, stream ID)
  73     .. member::   uint8_t type
  74
  75         The type of this frame.  See `nghttp2_frame_type`.
  76     .. member::   uint8_t flags
  77
  78         The flags.
  79     .. member::   uint8_t reserved
  80
  81         Reserved bit in frame header.  Currently, this is always set to 0
  82         and application should not expect something useful in here.
  83
  84 .. type:: nghttp2_data_source
  85
  86
  87     This union represents the some kind of data source passed to
  88     :type:`nghttp2_data_source_read_callback`.
  89
  90     .. member::   int fd
  91
  92         The integer field, suitable for a file descriptor.
  93     .. member::   void *ptr
  94
  95         The pointer to an arbitrary object.
  96
  97 .. type:: typedef ssize_t (*nghttp2_data_source_read_callback)( nghttp2_session *session, int32_t stream_id, uint8_t *buf, size_t length, uint32_t *data_flags, nghttp2_data_source *source, void *user_data)
  98
  99
 100     Callback function invoked when the library wants to read data from
 101     the *source*.  The read data is sent in the stream *stream_id*.
 102     The implementation of this function must read at most *length*
 103     bytes of data from *source* (or possibly other places) and store
 104     them in *buf* and return number of data stored in *buf*.  If EOF is
 105     reached, set :macro:`NGHTTP2_DATA_FLAG_EOF` flag in *\*data_flags*.
 106
 107     Sometime it is desirable to avoid copying data into *buf* and let
 108     application to send data directly.  To achieve this, set
 109     :macro:`NGHTTP2_DATA_FLAG_NO_COPY` to *\*data_flags* (and possibly
 110     other flags, just like when we do copy), and return the number of
 111     bytes to send without copying data into *buf*.  The library, seeing
 112     :macro:`NGHTTP2_DATA_FLAG_NO_COPY`, will invoke
 113     :type:`nghttp2_send_data_callback`.  The application must send
 114     complete DATA frame in that callback.
 115
 116     If this callback is set by `nghttp2_submit_request()`,
 117     `nghttp2_submit_response()` or `nghttp2_submit_headers()` and
 118     `nghttp2_submit_data()` with flag parameter
 119     :macro:`NGHTTP2_FLAG_END_STREAM` set, and
 120     :macro:`NGHTTP2_DATA_FLAG_EOF` flag is set to *\*data_flags*, DATA
 121     frame will have END_STREAM flag set.  Usually, this is expected
 122     behaviour and all are fine.  One exception is send trailer header
 123     fields.  You cannot send trailers after sending frame with
 124     END_STREAM set.  To avoid this problem, one can set
 125     :macro:`NGHTTP2_DATA_FLAG_NO_END_STREAM` along with
 126     :macro:`NGHTTP2_DATA_FLAG_EOF` to signal the library not to set
 127     END_STREAM in DATA frame.  Then application can use
 128     `nghttp2_submit_trailer()` to send trailers.
 129     `nghttp2_submit_trailer()` can be called inside this callback.
 130
 131     If the application wants to postpone DATA frames (e.g.,
 132     asynchronous I/O, or reading data blocks for long time), it is
 133     achieved by returning :macro:`NGHTTP2_ERR_DEFERRED` without reading
 134     any data in this invocation.  The library removes DATA frame from
 135     the outgoing queue temporarily.  To move back deferred DATA frame
 136     to outgoing queue, call `nghttp2_session_resume_data()`.  In case
 137     of error, there are 2 choices. Returning
 138     :macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close the stream
 139     by issuing RST_STREAM with :macro:`NGHTTP2_INTERNAL_ERROR`.  If a
 140     different error code is desirable, use
 141     `nghttp2_submit_rst_stream()` with a desired error code and then
 142     return :macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.  Returning
 143     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the entire session
 144     failure.
 145 .. type:: nghttp2_data_provider
 146
 147
 148     This struct represents the data source and the way to read a chunk
 149     of data from it.
 150
 151     .. member::   nghttp2_data_source source
 152
 153         The data source.
 154     .. member::   nghttp2_data_source_read_callback read_callback
 155
 156         The callback function to read a chunk of data from the *source*.
 157
 158 .. type:: nghttp2_data
 159
 160
 161     The DATA frame.  The received data is delivered via
 162     :type:`nghttp2_on_data_chunk_recv_callback`.
 163
 164     .. member::   size_t padlen
 165
 166         The length of the padding in this frame.  This includes PAD_HIGH
 167         and PAD_LOW.
 168
 169 .. type:: nghttp2_priority_spec
 170
 171
 172     The structure to specify stream dependency.
 173
 174     .. member::   int32_t stream_id
 175
 176         The stream ID of the stream to depend on.  Specifying 0 makes
 177         stream not depend any other stream.
 178     .. member::   int32_t weight
 179
 180         The weight of this dependency.
 181     .. member::   uint8_t exclusive
 182
 183         nonzero means exclusive dependency
 184
 185 .. type:: nghttp2_headers
 186
 187
 188     The HEADERS frame.  It has the following members:
 189
 190     .. member::   nghttp2_frame_hd hd
 191
 192         The frame header.
 193     .. member::   size_t padlen
 194
 195         The length of the padding in this frame.  This includes PAD_HIGH
 196         and PAD_LOW.
 197     .. member::   nghttp2_priority_spec pri_spec
 198
 199         The priority specification
 200     .. member::   nghttp2_nv *nva
 201
 202         The name/value pairs.
 203     .. member::   size_t nvlen
 204
 205         The number of name/value pairs in *nva*.
 206     .. member::   nghttp2_headers_category cat
 207
 208         The category of this HEADERS frame.
 209
 210 .. type:: nghttp2_priority
 211
 212
 213     The PRIORITY frame.  It has the following members:
 214
 215     .. member::   nghttp2_frame_hd hd
 216
 217         The frame header.
 218     .. member::   nghttp2_priority_spec pri_spec
 219
 220         The priority specification.
 221
 222 .. type:: nghttp2_rst_stream
 223
 224
 225     The RST_STREAM frame.  It has the following members:
 226
 227     .. member::   nghttp2_frame_hd hd
 228
 229         The frame header.
 230     .. member::   uint32_t error_code
 231
 232         The error code.  See :type:`nghttp2_error_code`.
 233
 234 .. type:: nghttp2_settings_entry
 235
 236
 237     The SETTINGS ID/Value pair.  It has the following members:
 238
 239     .. member::   int32_t settings_id
 240
 241         The SETTINGS ID.  See :type:`nghttp2_settings_id`.
 242     .. member::   uint32_t value
 243
 244         The value of this entry.
 245
 246 .. type:: nghttp2_settings
 247
 248
 249     The SETTINGS frame.  It has the following members:
 250
 251     .. member::   nghttp2_frame_hd hd
 252
 253         The frame header.
 254     .. member::   size_t niv
 255
 256         The number of SETTINGS ID/Value pairs in *iv*.
 257     .. member::   nghttp2_settings_entry *iv
 258
 259         The pointer to the array of SETTINGS ID/Value pair.
 260
 261 .. type:: nghttp2_push_promise
 262
 263
 264     The PUSH_PROMISE frame.  It has the following members:
 265
 266     .. member::   nghttp2_frame_hd hd
 267
 268         The frame header.
 269     .. member::   size_t padlen
 270
 271         The length of the padding in this frame.  This includes PAD_HIGH
 272         and PAD_LOW.
 273     .. member::   nghttp2_nv *nva
 274
 275         The name/value pairs.
 276     .. member::   size_t nvlen
 277
 278         The number of name/value pairs in *nva*.
 279     .. member::   int32_t promised_stream_id
 280
 281         The promised stream ID
 282     .. member::   uint8_t reserved
 283
 284         Reserved bit.  Currently this is always set to 0 and application
 285         should not expect something useful in here.
 286
 287 .. type:: nghttp2_ping
 288
 289
 290     The PING frame.  It has the following members:
 291
 292     .. member::   nghttp2_frame_hd hd
 293
 294         The frame header.
 295     .. member::   uint8_t opaque_data[8]
 296
 297         The opaque data
 298
 299 .. type:: nghttp2_goaway
 300
 301
 302     The GOAWAY frame.  It has the following members:
 303
 304     .. member::   nghttp2_frame_hd hd
 305
 306         The frame header.
 307     .. member::   int32_t last_stream_id
 308
 309         The last stream stream ID.
 310     .. member::   uint32_t error_code
 311
 312         The error code.  See :type:`nghttp2_error_code`.
 313     .. member::   uint8_t *opaque_data
 314
 315         The additional debug data
 316     .. member::   size_t opaque_data_len
 317
 318         The length of *opaque_data* member.
 319     .. member::   uint8_t reserved
 320
 321         Reserved bit.  Currently this is always set to 0 and application
 322         should not expect something useful in here.
 323
 324 .. type:: nghttp2_window_update
 325
 326
 327     The WINDOW_UPDATE frame.  It has the following members:
 328
 329     .. member::   nghttp2_frame_hd hd
 330
 331         The frame header.
 332     .. member::   int32_t window_size_increment
 333
 334         The window size increment.
 335     .. member::   uint8_t reserved
 336
 337         Reserved bit.  Currently this is always set to 0 and application
 338         should not expect something useful in here.
 339
 340 .. type:: nghttp2_extension
 341
 342
 343     The extension frame.  It has following members:
 344
 345     .. member::   nghttp2_frame_hd hd
 346
 347         The frame header.
 348     .. member::   void *payload
 349
 350         The pointer to extension payload.  The exact pointer type is
 351         determined by hd.type.
 352
 353         Currently, no extension is supported.  This is a place holder for
 354         the future extensions.
 355
 356 .. type:: nghttp2_frame
 357
 358
 359     This union includes all frames to pass them to various function
 360     calls as nghttp2_frame type.  The CONTINUATION frame is omitted
 361     from here because the library deals with it internally.
 362
 363     .. member::   nghttp2_frame_hd hd
 364
 365         The frame header, which is convenient to inspect frame header.
 366     .. member::   nghttp2_data data
 367
 368         The DATA frame.
 369     .. member::   nghttp2_headers headers
 370
 371         The HEADERS frame.
 372     .. member::   nghttp2_priority priority
 373
 374         The PRIORITY frame.
 375     .. member::   nghttp2_rst_stream rst_stream
 376
 377         The RST_STREAM frame.
 378     .. member::   nghttp2_settings settings
 379
 380         The SETTINGS frame.
 381     .. member::   nghttp2_push_promise push_promise
 382
 383         The PUSH_PROMISE frame.
 384     .. member::   nghttp2_ping ping
 385
 386         The PING frame.
 387     .. member::   nghttp2_goaway goaway
 388
 389         The GOAWAY frame.
 390     .. member::   nghttp2_window_update window_update
 391
 392         The WINDOW_UPDATE frame.
 393     .. member::   nghttp2_extension ext
 394
 395         The extension frame.
 396
 397 .. type:: typedef ssize_t (*nghttp2_send_callback)(nghttp2_session *session, const uint8_t *data, size_t length, int flags, void *user_data)
 398
 399
 400     Callback function invoked when *session* wants to send data to the
 401     remote peer.  The implementation of this function must send at most
 402     *length* bytes of data stored in *data*.  The *flags* is currently
 403     not used and always 0. It must return the number of bytes sent if
 404     it succeeds.  If it cannot send any single byte without blocking,
 405     it must return :macro:`NGHTTP2_ERR_WOULDBLOCK`.  For other errors,
 406     it must return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.  The
 407     *user_data* pointer is the third argument passed in to the call to
 408     `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
 409
 410     This callback is required if the application uses
 411     `nghttp2_session_send()` to send data to the remote endpoint.  If
 412     the application uses solely `nghttp2_session_mem_send()` instead,
 413     this callback function is unnecessary.
 414
 415     To set this callback to :type:`nghttp2_session_callbacks`, use
 416     `nghttp2_session_callbacks_set_send_callback()`.
 417 .. type:: typedef int (*nghttp2_send_data_callback)(nghttp2_session *session, nghttp2_frame *frame, const uint8_t *framehd, size_t length, nghttp2_data_source *source, void *user_data)
 418
 419
 420     Callback function invoked when :macro:`NGHTTP2_DATA_FLAG_NO_COPY` is
 421     used in :type:`nghttp2_data_source_read_callback` to send complete
 422     DATA frame.
 423
 424     The *frame* is a DATA frame to send.  The *framehd* is the
 425     serialized frame header (9 bytes). The *length* is the length of
 426     application data to send (this does not include padding).  The
 427     *source* is the same pointer passed to
 428     :type:`nghttp2_data_source_read_callback`.
 429
 430     The application first must send frame header *framehd* of length 9
 431     bytes.  If ``frame->padlen > 0``, send 1 byte of value
 432     ``frame->padlen - 1``.  Then send exactly *length* bytes of
 433     application data.  Finally, if ``frame->padlen > 0``, send
 434     ``frame->padlen - 1`` bytes of zero (they are padding).
 435
 436     The application has to send complete DATA frame in this callback.
 437     If all data were written successfully, return 0.
 438
 439     If it cannot send it all, just return
 440     :macro:`NGHTTP2_ERR_WOULDBLOCK`; the library will call this callback
 441     with the same parameters later (It is recommended to send complete
 442     DATA frame at once in this function to deal with error; if partial
 443     frame data has already sent, it is impossible to send another data
 444     in that state, and all we can do is tear down connection).  If
 445     application decided to reset this stream, return
 446     :macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`, then the library
 447     will send RST_STREAM with INTERNAL_ERROR as error code.  The
 448     application can also return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`,
 449     which will result in connection closure.  Returning any other value
 450     is treated as :macro:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned.
 451 .. type:: typedef ssize_t (*nghttp2_recv_callback)(nghttp2_session *session, uint8_t *buf, size_t length, int flags, void *user_data)
 452
 453
 454     Callback function invoked when *session* wants to receive data from
 455     the remote peer.  The implementation of this function must read at
 456     most *length* bytes of data and store it in *buf*.  The *flags* is
 457     currently not used and always 0.  It must return the number of
 458     bytes written in *buf* if it succeeds.  If it cannot read any
 459     single byte without blocking, it must return
 460     :macro:`NGHTTP2_ERR_WOULDBLOCK`.  If it gets EOF before it reads any
 461     single byte, it must return :macro:`NGHTTP2_ERR_EOF`.  For other
 462     errors, it must return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 463     Returning 0 is treated as :macro:`NGHTTP2_ERR_WOULDBLOCK`.  The
 464     *user_data* pointer is the third argument passed in to the call to
 465     `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
 466
 467     This callback is required if the application uses
 468     `nghttp2_session_recv()` to receive data from the remote endpoint.
 469     If the application uses solely `nghttp2_session_mem_recv()`
 470     instead, this callback function is unnecessary.
 471
 472     To set this callback to :type:`nghttp2_session_callbacks`, use
 473     `nghttp2_session_callbacks_set_recv_callback()`.
 474 .. type:: typedef int (*nghttp2_on_frame_recv_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)
 475
 476
 477     Callback function invoked by `nghttp2_session_recv()` and
 478     `nghttp2_session_mem_recv()` when a frame is received.  The
 479     *user_data* pointer is the third argument passed in to the call to
 480     `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
 481
 482     If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
 483     member of their data structure are always ``NULL`` and 0
 484     respectively.  The header name/value pairs are emitted via
 485     :type:`nghttp2_on_header_callback`.
 486
 487     For HEADERS, PUSH_PROMISE and DATA frames, this callback may be
 488     called after stream is closed (see
 489     :type:`nghttp2_on_stream_close_callback`).  The application should
 490     check that stream is still alive using its own stream management or
 491     :func:`nghttp2_session_get_stream_user_data()`.
 492
 493     Only HEADERS and DATA frame can signal the end of incoming data.
 494     If ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the
 495     *frame* is the last frame from the remote peer in this stream.
 496
 497     This callback won't be called for CONTINUATION frames.
 498     HEADERS/PUSH_PROMISE + CONTINUATIONs are treated as single frame.
 499
 500     The implementation of this function must return 0 if it succeeds.
 501     If nonzero value is returned, it is treated as fatal error and
 502     `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
 503     immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 504
 505     To set this callback to :type:`nghttp2_session_callbacks`, use
 506     `nghttp2_session_callbacks_set_on_frame_recv_callback()`.
 507 .. type:: typedef int (*nghttp2_on_invalid_frame_recv_callback)( nghttp2_session *session, const nghttp2_frame *frame, int lib_error_code, void *user_data)
 508
 509
 510     Callback function invoked by `nghttp2_session_recv()` and
 511     `nghttp2_session_mem_recv()` when an invalid non-DATA frame is
 512     received.  The error is indicated by the *lib_error_code*, which is
 513     one of the values defined in :type:`nghttp2_error`.  When this
 514     callback function is invoked, the library automatically submits
 515     either RST_STREAM or GOAWAY frame.  The *user_data* pointer is the
 516     third argument passed in to the call to
 517     `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
 518
 519     If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
 520     member of their data structure are always ``NULL`` and 0
 521     respectively.
 522
 523     The implementation of this function must return 0 if it succeeds.
 524     If nonzero is returned, it is treated as fatal error and
 525     `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
 526     immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 527
 528     To set this callback to :type:`nghttp2_session_callbacks`, use
 529     `nghttp2_session_callbacks_set_on_invalid_frame_recv_callback()`.
 530 .. type:: typedef int (*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)
 531
 532
 533     Callback function invoked when a chunk of data in DATA frame is
 534     received.  The *stream_id* is the stream ID this DATA frame belongs
 535     to.  The *flags* is the flags of DATA frame which this data chunk
 536     is contained.  ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not
 537     necessarily mean this chunk of data is the last one in the stream.
 538     You should use :type:`nghttp2_on_frame_recv_callback` to know all
 539     data frames are received.  The *user_data* pointer is the third
 540     argument passed in to the call to `nghttp2_session_client_new()` or
 541     `nghttp2_session_server_new()`.
 542
 543     If the application uses `nghttp2_session_mem_recv()`, it can return
 544     :macro:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
 545     return without processing further input bytes.  The memory by
 546     pointed by the *data* is retained until
 547     `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
 548     The application must retain the input bytes which was used to
 549     produce the *data* parameter, because it may refer to the memory
 550     region included in the input bytes.
 551
 552     The implementation of this function must return 0 if it succeeds.
 553     If nonzero is returned, it is treated as fatal error, and
 554     `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
 555     immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 556
 557     To set this callback to :type:`nghttp2_session_callbacks`, use
 558     `nghttp2_session_callbacks_set_on_data_chunk_recv_callback()`.
 559 .. type:: typedef int (*nghttp2_before_frame_send_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)
 560
 561
 562     Callback function invoked just before the non-DATA frame *frame* is
 563     sent.  The *user_data* pointer is the third argument passed in to
 564     the call to `nghttp2_session_client_new()` or
 565     `nghttp2_session_server_new()`.
 566
 567     The implementation of this function must return 0 if it succeeds.
 568     If nonzero is returned, it is treated as fatal error and
 569     `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
 570     immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 571
 572     To set this callback to :type:`nghttp2_session_callbacks`, use
 573     `nghttp2_session_callbacks_set_before_frame_send_callback()`.
 574 .. type:: typedef int (*nghttp2_on_frame_send_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)
 575
 576
 577     Callback function invoked after the frame *frame* is sent.  The
 578     *user_data* pointer is the third argument passed in to the call to
 579     `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
 580
 581     The implementation of this function must return 0 if it succeeds.
 582     If nonzero is returned, it is treated as fatal error and
 583     `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
 584     immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 585
 586     To set this callback to :type:`nghttp2_session_callbacks`, use
 587     `nghttp2_session_callbacks_set_on_frame_send_callback()`.
 588 .. type:: typedef int (*nghttp2_on_frame_not_send_callback)(nghttp2_session *session, const nghttp2_frame *frame, int lib_error_code, void *user_data)
 589
 590
 591     Callback function invoked after the non-DATA frame *frame* is not
 592     sent because of the error.  The error is indicated by the
 593     *lib_error_code*, which is one of the values defined in
 594     :type:`nghttp2_error`.  The *user_data* pointer is the third
 595     argument passed in to the call to `nghttp2_session_client_new()` or
 596     `nghttp2_session_server_new()`.
 597
 598     The implementation of this function must return 0 if it succeeds.
 599     If nonzero is returned, it is treated as fatal error and
 600     `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
 601     immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 602
 603     `nghttp2_session_get_stream_user_data()` can be used to get
 604     associated data.
 605
 606     To set this callback to :type:`nghttp2_session_callbacks`, use
 607     `nghttp2_session_callbacks_set_on_frame_not_send_callback()`.
 608 .. type:: typedef int (*nghttp2_on_stream_close_callback)(nghttp2_session *session, int32_t stream_id, uint32_t error_code, void *user_data)
 609
 610
 611     Callback function invoked when the stream *stream_id* is closed.
 612     The reason of closure is indicated by the *error_code*.  The
 613     *error_code* is usually one of :macro:`nghttp2_error_code`, but that
 614     is not guaranteed.  The stream_user_data, which was specified in
 615     `nghttp2_submit_request()` or `nghttp2_submit_headers()`, is still
 616     available in this function.  The *user_data* pointer is the third
 617     argument passed in to the call to `nghttp2_session_client_new()` or
 618     `nghttp2_session_server_new()`.
 619
 620     This function is also called for a stream in reserved state.
 621
 622     The implementation of this function must return 0 if it succeeds.
 623     If nonzero is returned, it is treated as fatal error and
 624     `nghttp2_session_recv()`, `nghttp2_session_mem_recv()`,
 625     `nghttp2_session_send()`, and `nghttp2_session_mem_send()`
 626     functions immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 627
 628     To set this callback to :type:`nghttp2_session_callbacks`, use
 629     `nghttp2_session_callbacks_set_on_stream_close_callback()`.
 630 .. type:: typedef int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)
 631
 632
 633     Callback function invoked when the reception of header block in
 634     HEADERS or PUSH_PROMISE is started.  Each header name/value pair
 635     will be emitted by :type:`nghttp2_on_header_callback`.
 636
 637     The ``frame->hd.flags`` may not have
 638     :macro:`NGHTTP2_FLAG_END_HEADERS` flag set, which indicates that one
 639     or more CONTINUATION frames are involved.  But the application does
 640     not need to care about that because the header name/value pairs are
 641     emitted transparently regardless of CONTINUATION frames.
 642
 643     The server applications probably create an object to store
 644     information about new stream if ``frame->hd.type ==
 645     NGHTTP2_HEADERS`` and ``frame->headers.cat ==
 646     NGHTTP2_HCAT_REQUEST``.  If *session* is configured as server side,
 647     ``frame->headers.cat`` is either ``NGHTTP2_HCAT_REQUEST``
 648     containing request headers or ``NGHTTP2_HCAT_HEADERS`` containing
 649     trailer headers and never get PUSH_PROMISE in this callback.
 650
 651     For the client applications, ``frame->hd.type`` is either
 652     ``NGHTTP2_HEADERS`` or ``NGHTTP2_PUSH_PROMISE``.  In case of
 653     ``NGHTTP2_HEADERS``, ``frame->headers.cat ==
 654     NGHTTP2_HCAT_RESPONSE`` means that it is the first response
 655     headers, but it may be non-final response which is indicated by 1xx
 656     status code.  In this case, there may be zero or more HEADERS frame
 657     with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS`` which has
 658     non-final response code and finally client gets exactly one HEADERS
 659     frame with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS``
 660     containing final response headers (non-1xx status code).  The
 661     trailer headers also has ``frame->headers.cat ==
 662     NGHTTP2_HCAT_HEADERS`` which does not contain any status code.
 663
 664     Returning :macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close
 665     the stream (promised stream if frame is PUSH_PROMISE) by issuing
 666     RST_STREAM with :macro:`NGHTTP2_INTERNAL_ERROR`.  In this case,
 667     :type:`nghttp2_on_header_callback` and
 668     :type:`nghttp2_on_frame_recv_callback` will not be invoked.  If a
 669     different error code is desirable, use
 670     `nghttp2_submit_rst_stream()` with a desired error code and then
 671     return :macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.  Again, use
 672     ``frame->push_promise.promised_stream_id`` as stream_id parameter
 673     in `nghttp2_submit_rst_stream()` if frame is PUSH_PROMISE.
 674
 675     The implementation of this function must return 0 if it succeeds.
 676     It can return :macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` to
 677     reset the stream (promised stream if frame is PUSH_PROMISE).  For
 678     critical errors, it must return
 679     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.  If the other value is
 680     returned, it is treated as if :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`
 681     is returned.  If :macro:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
 682     `nghttp2_session_mem_recv()` function will immediately return
 683     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 684
 685     To set this callback to :type:`nghttp2_session_callbacks`, use
 686     `nghttp2_session_callbacks_set_on_begin_headers_callback()`.
 687 .. type:: typedef int (*nghttp2_on_header_callback)(nghttp2_session *session, const nghttp2_frame *frame, const uint8_t *name, size_t namelen, const uint8_t *value, size_t valuelen, uint8_t flags, void *user_data)
 688
 689
 690     Callback function invoked when a header name/value pair is received
 691     for the *frame*.  The *name* of length *namelen* is header name.
 692     The *value* of length *valuelen* is header value.  The *flags* is
 693     bitwise OR of one or more of :type:`nghttp2_nv_flag`.
 694
 695     If :macro:`NGHTTP2_NV_FLAG_NO_INDEX` is set in *flags*, the receiver
 696     must not index this name/value pair when forwarding it to the next
 697     hop.  More specifically, "Literal Header Field never Indexed"
 698     representation must be used in HPACK encoding.
 699
 700     When this callback is invoked, ``frame->hd.type`` is either
 701     :macro:`NGHTTP2_HEADERS` or :macro:`NGHTTP2_PUSH_PROMISE`.  After all
 702     header name/value pairs are processed with this callback, and no
 703     error has been detected, :type:`nghttp2_on_frame_recv_callback`
 704     will be invoked.  If there is an error in decompression,
 705     :type:`nghttp2_on_frame_recv_callback` for the *frame* will not be
 706     invoked.
 707
 708     Both *name* and *value* are guaranteed to be NULL-terminated.  The
 709     *namelen* and *valuelen* do not include terminal NULL.  If
 710     `nghttp2_option_set_no_http_messaging()` is used with nonzero
 711     value, NULL character may be included in *name* or *value* before
 712     terminating NULL.
 713
 714     Please note that unless `nghttp2_option_set_no_http_messaging()` is
 715     used, nghttp2 library does perform validation against the *name*
 716     and the *value* using `nghttp2_check_header_name()` and
 717     `nghttp2_check_header_value()`.  In addition to this, nghttp2
 718     performs vaidation based on HTTP Messaging rule, which is briefly
 719     explained in :ref:`http-messaging` section.
 720
 721     If the application uses `nghttp2_session_mem_recv()`, it can return
 722     :macro:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
 723     return without processing further input bytes.  The memory pointed
 724     by *frame*, *name* and *value* parameters are retained until
 725     `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
 726     The application must retain the input bytes which was used to
 727     produce these parameters, because it may refer to the memory region
 728     included in the input bytes.
 729
 730     Returning :macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close
 731     the stream (promised stream if frame is PUSH_PROMISE) by issuing
 732     RST_STREAM with :macro:`NGHTTP2_INTERNAL_ERROR`.  In this case,
 733     :type:`nghttp2_on_header_callback` and
 734     :type:`nghttp2_on_frame_recv_callback` will not be invoked.  If a
 735     different error code is desirable, use
 736     `nghttp2_submit_rst_stream()` with a desired error code and then
 737     return :macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.  Again, use
 738     ``frame->push_promise.promised_stream_id`` as stream_id parameter
 739     in `nghttp2_submit_rst_stream()` if frame is PUSH_PROMISE.
 740
 741     The implementation of this function must return 0 if it succeeds.
 742     It may return :macro:`NGHTTP2_ERR_PAUSE` or
 743     :macro:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.  For other critical
 744     failures, it must return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.  If
 745     the other nonzero value is returned, it is treated as
 746     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.  If
 747     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
 748     `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
 749     immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 750
 751     To set this callback to :type:`nghttp2_session_callbacks`, use
 752     `nghttp2_session_callbacks_set_on_header_callback()`.
 753 .. type:: typedef ssize_t (*nghttp2_select_padding_callback)(nghttp2_session *session, const nghttp2_frame *frame, size_t max_payloadlen, void *user_data)
 754
 755
 756     Callback function invoked when the library asks application how
 757     many padding bytes are required for the transmission of the
 758     *frame*.  The application must choose the total length of payload
 759     including padded bytes in range [frame->hd.length, max_payloadlen],
 760     inclusive.  Choosing number not in this range will be treated as
 761     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.  Returning
 762     ``frame->hd.length`` means no padding is added.  Returning
 763     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE` will make
 764     `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
 765     immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 766
 767     To set this callback to :type:`nghttp2_session_callbacks`, use
 768     `nghttp2_session_callbacks_set_select_padding_callback()`.
 769 .. type:: typedef ssize_t (*nghttp2_data_source_read_length_callback)( nghttp2_session *session, uint8_t frame_type, int32_t stream_id, int32_t session_remote_window_size, int32_t stream_remote_window_size, uint32_t remote_max_frame_size, void *user_data)
 770
 771
 772     Callback function invoked when library wants to get max length of
 773     data to send data to the remote peer.  The implementation of this
 774     function should return a value in the following range.  [1,
 775     min(*session_remote_window_size*, *stream_remote_window_size*,
 776     *remote_max_frame_size*)].  If a value greater than this range is
 777     returned than the max allow value will be used.  Returning a value
 778     smaller than this range is treated as
 779     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.  The *frame_type* is provided
 780     for future extensibility and identifies the type of frame (see
 781     :type:`nghttp2_frame_type`) for which to get the length for.
 782     Currently supported frame types are: :macro:`NGHTTP2_DATA`.
 783
 784     This callback can be used to control the length in bytes for which
 785     :type:`nghttp2_data_source_read_callback` is allowed to send to the
 786     remote endpoint.  This callback is optional.  Returning
 787     :macro:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the entire session
 788     failure.
 789
 790     To set this callback to :type:`nghttp2_session_callbacks`, use
 791     `nghttp2_session_callbacks_set_data_source_read_length_callback()`.
 792 .. type:: typedef int (*nghttp2_on_begin_frame_callback)(nghttp2_session *session, const nghttp2_frame_hd *hd, void *user_data)
 793
 794
 795     Callback function invoked when a frame header is received.  The
 796     *hd* points to received frame header.
 797
 798     Unlike :type:`nghttp2_on_frame_recv_callback`, this callback will
 799     also be called when frame header of CONTINUATION frame is received.
 800
 801     If both :type:`nghttp2_on_begin_frame_callback` and
 802     :type:`nghttp2_on_begin_headers_callback` are set and HEADERS or
 803     PUSH_PROMISE is received, :type:`nghttp2_on_begin_frame_callback`
 804     will be called first.
 805
 806     The implementation of this function must return 0 if it succeeds.
 807     If nonzero value is returned, it is treated as fatal error and
 808     `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
 809     immediately return :macro:`NGHTTP2_ERR_CALLBACK_FAILURE`.
 810
 811     To set this callback to :type:`nghttp2_session_callbacks`, use
 812     `nghttp2_session_callbacks_set_on_begin_frame_callback()`.
 813 .. type:: nghttp2_session_callbacks
 814
 815
 816     Callback functions for :type:`nghttp2_session`.  The details of
 817     this structure are intentionally hidden from the public API.
 818
 819
 820 .. type:: typedef void *(*nghttp2_malloc)(size_t size, void *mem_user_data)
 821
 822
 823     Custom memory allocator to replace malloc().  The *mem_user_data*
 824     is the mem_user_data member of :type:`nghttp2_mem` structure.
 825 .. type:: typedef void (*nghttp2_free)(void *ptr, void *mem_user_data)
 826
 827
 828     Custom memory allocator to replace free().  The *mem_user_data* is
 829     the mem_user_data member of :type:`nghttp2_mem` structure.
 830 .. type:: typedef void *(*nghttp2_calloc)(size_t nmemb, size_t size, void *mem_user_data)
 831
 832
 833     Custom memory allocator to replace calloc().  The *mem_user_data*
 834     is the mem_user_data member of :type:`nghttp2_mem` structure.
 835 .. type:: typedef void *(*nghttp2_realloc)(void *ptr, size_t size, void *mem_user_data)
 836
 837
 838     Custom memory allocator to replace realloc().  The *mem_user_data*
 839     is the mem_user_data member of :type:`nghttp2_mem` structure.
 840 .. type:: nghttp2_mem
 841
 842
 843     Custom memory allocator functions and user defined pointer.  The
 844     *mem_user_data* member is passed to each allocator function.  This
 845     can be used, for example, to achieve per-session memory pool.
 846
 847     In the following example code, ``my_malloc``, ``my_free``,
 848     ``my_calloc`` and ``my_realloc`` are the replacement of the
 849     standard allocators ``malloc``, ``free``, ``calloc`` and
 850     ``realloc`` respectively::
 851
 852         void *my_malloc_cb(size_t size, void *mem_user_data) {
 853           return my_malloc(size);
 854         }
 855
 856         void my_free_cb(void *ptr, void *mem_user_data) { my_free(ptr); }
 857
 858         void *my_calloc_cb(size_t nmemb, size_t size, void *mem_user_data) {
 859           return my_calloc(nmemb, size);
 860         }
 861
 862         void *my_realloc_cb(void *ptr, size_t size, void *mem_user_data) {
 863           return my_realloc(ptr, size);
 864         }
 865
 866         void session_new() {
 867           nghttp2_session *session;
 868           nghttp2_session_callbacks *callbacks;
 869           nghttp2_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb,
 870                              my_realloc_cb};
 871
 872           ...
 873
 874           nghttp2_session_client_new3(&session, callbacks, NULL, NULL, &mem);
 875
 876           ...
 877         }
 878
 879     .. member::   void *mem_user_data
 880
 881         An arbitrary user supplied data.  This is passed to each
 882         allocator function.
 883     .. member::   nghttp2_malloc malloc
 884
 885         Custom allocator function to replace malloc().
 886     .. member::   nghttp2_free free
 887
 888         Custom allocator function to replace free().
 889     .. member::   nghttp2_calloc calloc
 890
 891         Custom allocator function to replace calloc().
 892     .. member::   nghttp2_realloc realloc
 893
 894         Custom allocator function to replace realloc().
 895
 896 .. type:: nghttp2_option
 897
 898
 899     Configuration options for :type:`nghttp2_session`.  The details of
 900     this structure are intentionally hidden from the public API.
 901
 902
 903 .. type:: nghttp2_hd_deflater
 904
 905
 906     HPACK deflater object.
 907
 908
 909 .. type:: nghttp2_hd_inflater
 910
 911
 912     HPACK inflater object.
 913
 914