2 Types (structs, unions and typedefs)
3 ====================================
4 .. type:: nghttp2_session
7 The primary structure to hold the resources needed for a HTTP/2
8 session. The details of this structure are intentionally hidden
12 .. type:: nghttp2_info
15 This struct is what `nghttp2_version()` returns. It holds
16 information about the particular nghttp2 version.
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
25 the :macro:`NGHTTP2_VERSION_NUM` number (since age ==1)
26 .. member:: const char *version_str
28 points to the :macro:`NGHTTP2_VERSION` string (since age ==1)
29 .. member:: const char *proto_str
31 points to the :macro:`NGHTTP2_PROTO_VERSION_ID` string this
32 instance implements (since age ==1)
37 The object representing single contiguous buffer.
39 .. member:: uint8_t *base
41 The pointer to the buffer.
42 .. member:: size_t len
44 The length of the buffer.
46 .. type:: nghttp2_rcbuf
49 The object representing reference counted buffer. The details of
50 this structure are intentionally hidden from the public API.
56 The name/value pair, which mainly used to represent header fields.
58 .. member:: uint8_t *name
60 The *name* byte string. If this struct is presented from library
61 (e.g., :type:`nghttp2_on_frame_recv_callback`), *name* is
62 guaranteed to be NULL-terminated. For some callbacks
63 (:type:`nghttp2_before_frame_send_callback`,
64 :type:`nghttp2_on_frame_send_callback`, and
65 :type:`nghttp2_on_frame_not_send_callback`), it may not be
66 NULL-terminated if header field is passed from application with
67 the flag :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_NAME`).
68 When application is constructing this struct, *name* is not
69 required to be NULL-terminated.
70 .. member:: uint8_t *value
72 The *value* byte string. If this struct is presented from
73 library (e.g., :type:`nghttp2_on_frame_recv_callback`), *value*
74 is guaranteed to be NULL-terminated. For some callbacks
75 (:type:`nghttp2_before_frame_send_callback`,
76 :type:`nghttp2_on_frame_send_callback`, and
77 :type:`nghttp2_on_frame_not_send_callback`), it may not be
78 NULL-terminated if header field is passed from application with
79 the flag :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_COPY_VALUE`).
80 When application is constructing this struct, *value* is not
81 required to be NULL-terminated.
82 .. member:: size_t namelen
84 The length of the *name*, excluding terminating NULL.
85 .. member:: size_t valuelen
87 The length of the *value*, excluding terminating NULL.
88 .. member:: uint8_t flags
90 Bitwise OR of one or more of :type:`nghttp2_nv_flag`.
92 .. type:: nghttp2_frame_hd
96 .. member:: size_t length
98 The length field of this frame, excluding frame header.
99 .. member:: int32_t stream_id
101 The stream identifier (aka, stream ID)
102 .. member:: uint8_t type
104 The type of this frame. See `nghttp2_frame_type`.
105 .. member:: uint8_t flags
108 .. member:: uint8_t reserved
110 Reserved bit in frame header. Currently, this is always set to 0
111 and application should not expect something useful in here.
113 .. type:: nghttp2_data_source
116 This union represents the some kind of data source passed to
117 :type:`nghttp2_data_source_read_callback`.
121 The integer field, suitable for a file descriptor.
122 .. member:: void *ptr
124 The pointer to an arbitrary object.
126 .. type:: 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)
129 Callback function invoked when the library wants to read data from
130 the *source*. The read data is sent in the stream *stream_id*.
131 The implementation of this function must read at most *length*
132 bytes of data from *source* (or possibly other places) and store
133 them in *buf* and return number of data stored in *buf*. If EOF is
134 reached, set :macro:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` flag
137 Sometime it is desirable to avoid copying data into *buf* and let
138 application to send data directly. To achieve this, set
139 :macro:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY` to
140 *\*data_flags* (and possibly other flags, just like when we do
141 copy), and return the number of bytes to send without copying data
142 into *buf*. The library, seeing
143 :macro:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY`, will invoke
144 :type:`nghttp2_send_data_callback`. The application must send
145 complete DATA frame in that callback.
147 If this callback is set by `nghttp2_submit_request()`,
148 `nghttp2_submit_response()` or `nghttp2_submit_headers()` and
149 `nghttp2_submit_data()` with flag parameter
150 :macro:`nghttp2_flag.NGHTTP2_FLAG_END_STREAM` set, and
151 :macro:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` flag is set to
152 *\*data_flags*, DATA frame will have END_STREAM flag set. Usually,
153 this is expected behaviour and all are fine. One exception is send
154 trailer fields. You cannot send trailer fields after sending frame
155 with END_STREAM set. To avoid this problem, one can set
156 :macro:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_END_STREAM` along
157 with :macro:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_EOF` to signal the
158 library not to set END_STREAM in DATA frame. Then application can
159 use `nghttp2_submit_trailer()` to send trailer fields.
160 `nghttp2_submit_trailer()` can be called inside this callback.
162 If the application wants to postpone DATA frames (e.g.,
163 asynchronous I/O, or reading data blocks for long time), it is
164 achieved by returning :macro:`nghttp2_error.NGHTTP2_ERR_DEFERRED`
165 without reading any data in this invocation. The library removes
166 DATA frame from the outgoing queue temporarily. To move back
167 deferred DATA frame to outgoing queue, call
168 `nghttp2_session_resume_data()`.
170 By default, *length* is limited to 16KiB at maximum. If peer
171 allows larger frames, application can enlarge transmission buffer
172 size. See :type:`nghttp2_data_source_read_length_callback` for
175 If the application just wants to return from
176 `nghttp2_session_send()` or `nghttp2_session_mem_send()` without
177 sending anything, return :macro:`nghttp2_error.NGHTTP2_ERR_PAUSE`.
179 In case of error, there are 2 choices. Returning
180 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will
181 close the stream by issuing RST_STREAM with
182 :macro:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. If a different
183 error code is desirable, use `nghttp2_submit_rst_stream()` with a
184 desired error code and then return
185 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
186 Returning :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will
187 signal the entire session failure.
188 .. type:: nghttp2_data_provider
191 This struct represents the data source and the way to read a chunk
194 .. member:: nghttp2_data_source source
197 .. member:: nghttp2_data_source_read_callback read_callback
199 The callback function to read a chunk of data from the *source*.
201 .. type:: nghttp2_data
204 The DATA frame. The received data is delivered via
205 :type:`nghttp2_on_data_chunk_recv_callback`.
207 .. member:: size_t padlen
209 The length of the padding in this frame. This includes PAD_HIGH
212 .. type:: nghttp2_priority_spec
215 The structure to specify stream dependency.
217 .. member:: int32_t stream_id
219 The stream ID of the stream to depend on. Specifying 0 makes
220 stream not depend any other stream.
221 .. member:: int32_t weight
223 The weight of this dependency.
224 .. member:: uint8_t exclusive
226 nonzero means exclusive dependency
228 .. type:: nghttp2_headers
231 The HEADERS frame. It has the following members:
233 .. member:: nghttp2_frame_hd hd
236 .. member:: size_t padlen
238 The length of the padding in this frame. This includes PAD_HIGH
240 .. member:: nghttp2_priority_spec pri_spec
242 The priority specification
243 .. member:: nghttp2_nv *nva
245 The name/value pairs.
246 .. member:: size_t nvlen
248 The number of name/value pairs in *nva*.
249 .. member:: nghttp2_headers_category cat
251 The category of this HEADERS frame.
253 .. type:: nghttp2_priority
256 The PRIORITY frame. It has the following members:
258 .. member:: nghttp2_frame_hd hd
261 .. member:: nghttp2_priority_spec pri_spec
263 The priority specification.
265 .. type:: nghttp2_rst_stream
268 The RST_STREAM frame. It has the following members:
270 .. member:: nghttp2_frame_hd hd
273 .. member:: uint32_t error_code
275 The error code. See :type:`nghttp2_error_code`.
277 .. type:: nghttp2_settings_entry
280 The SETTINGS ID/Value pair. It has the following members:
282 .. member:: int32_t settings_id
284 The SETTINGS ID. See :type:`nghttp2_settings_id`.
285 .. member:: uint32_t value
287 The value of this entry.
289 .. type:: nghttp2_settings
292 The SETTINGS frame. It has the following members:
294 .. member:: nghttp2_frame_hd hd
297 .. member:: size_t niv
299 The number of SETTINGS ID/Value pairs in *iv*.
300 .. member:: nghttp2_settings_entry *iv
302 The pointer to the array of SETTINGS ID/Value pair.
304 .. type:: nghttp2_push_promise
307 The PUSH_PROMISE frame. It has the following members:
309 .. member:: nghttp2_frame_hd hd
312 .. member:: size_t padlen
314 The length of the padding in this frame. This includes PAD_HIGH
316 .. member:: nghttp2_nv *nva
318 The name/value pairs.
319 .. member:: size_t nvlen
321 The number of name/value pairs in *nva*.
322 .. member:: int32_t promised_stream_id
324 The promised stream ID
325 .. member:: uint8_t reserved
327 Reserved bit. Currently this is always set to 0 and application
328 should not expect something useful in here.
330 .. type:: nghttp2_ping
333 The PING frame. It has the following members:
335 .. member:: nghttp2_frame_hd hd
338 .. member:: uint8_t opaque_data[8]
342 .. type:: nghttp2_goaway
345 The GOAWAY frame. It has the following members:
347 .. member:: nghttp2_frame_hd hd
350 .. member:: int32_t last_stream_id
352 The last stream stream ID.
353 .. member:: uint32_t error_code
355 The error code. See :type:`nghttp2_error_code`.
356 .. member:: uint8_t *opaque_data
358 The additional debug data
359 .. member:: size_t opaque_data_len
361 The length of *opaque_data* member.
362 .. member:: uint8_t reserved
364 Reserved bit. Currently this is always set to 0 and application
365 should not expect something useful in here.
367 .. type:: nghttp2_window_update
370 The WINDOW_UPDATE frame. It has the following members:
372 .. member:: nghttp2_frame_hd hd
375 .. member:: int32_t window_size_increment
377 The window size increment.
378 .. member:: uint8_t reserved
380 Reserved bit. Currently this is always set to 0 and application
381 should not expect something useful in here.
383 .. type:: nghttp2_extension
386 The extension frame. It has following members:
388 .. member:: nghttp2_frame_hd hd
391 .. member:: void *payload
393 The pointer to extension payload. The exact pointer type is
394 determined by hd.type.
396 Currently, no extension is supported. This is a place holder for
397 the future extensions.
399 .. type:: nghttp2_frame
402 This union includes all frames to pass them to various function
403 calls as nghttp2_frame type. The CONTINUATION frame is omitted
404 from here because the library deals with it internally.
406 .. member:: nghttp2_frame_hd hd
408 The frame header, which is convenient to inspect frame header.
409 .. member:: nghttp2_data data
412 .. member:: nghttp2_headers headers
415 .. member:: nghttp2_priority priority
418 .. member:: nghttp2_rst_stream rst_stream
420 The RST_STREAM frame.
421 .. member:: nghttp2_settings settings
424 .. member:: nghttp2_push_promise push_promise
426 The PUSH_PROMISE frame.
427 .. member:: nghttp2_ping ping
430 .. member:: nghttp2_goaway goaway
433 .. member:: nghttp2_window_update window_update
435 The WINDOW_UPDATE frame.
436 .. member:: nghttp2_extension ext
440 .. type:: ssize_t (*nghttp2_send_callback)(nghttp2_session *session, const uint8_t *data, size_t length, int flags, void *user_data)
443 Callback function invoked when *session* wants to send data to the
444 remote peer. The implementation of this function must send at most
445 *length* bytes of data stored in *data*. The *flags* is currently
446 not used and always 0. It must return the number of bytes sent if
447 it succeeds. If it cannot send any single byte without blocking,
448 it must return :macro:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. For
449 other errors, it must return
450 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. The
451 *user_data* pointer is the third argument passed in to the call to
452 `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
454 This callback is required if the application uses
455 `nghttp2_session_send()` to send data to the remote endpoint. If
456 the application uses solely `nghttp2_session_mem_send()` instead,
457 this callback function is unnecessary.
459 To set this callback to :type:`nghttp2_session_callbacks`, use
460 `nghttp2_session_callbacks_set_send_callback()`.
464 The *length* may be very small. If that is the case, and
465 application disables Nagle algorithm (``TCP_NODELAY``), then just
466 writing *data* to the network stack leads to very small packet,
467 and it is very inefficient. An application should be responsible
468 to buffer up small chunks of data as necessary to avoid this
470 .. type:: 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)
473 Callback function invoked when
474 :macro:`nghttp2_data_flag.NGHTTP2_DATA_FLAG_NO_COPY` is used in
475 :type:`nghttp2_data_source_read_callback` to send complete DATA
478 The *frame* is a DATA frame to send. The *framehd* is the
479 serialized frame header (9 bytes). The *length* is the length of
480 application data to send (this does not include padding). The
481 *source* is the same pointer passed to
482 :type:`nghttp2_data_source_read_callback`.
484 The application first must send frame header *framehd* of length 9
485 bytes. If ``frame->data.padlen > 0``, send 1 byte of value
486 ``frame->data.padlen - 1``. Then send exactly *length* bytes of
487 application data. Finally, if ``frame->data.padlen > 1``, send
488 ``frame->data.padlen - 1`` bytes of zero as padding.
490 The application has to send complete DATA frame in this callback.
491 If all data were written successfully, return 0.
493 If it cannot send any data at all, just return
494 :macro:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`; the library will call
495 this callback with the same parameters later (It is recommended to
496 send complete DATA frame at once in this function to deal with
497 error; if partial frame data has already sent, it is impossible to
498 send another data in that state, and all we can do is tear down
499 connection). When data is fully processed, but application wants
500 to make `nghttp2_session_mem_send()` or `nghttp2_session_send()`
501 return immediately without processing next frames, return
502 :macro:`nghttp2_error.NGHTTP2_ERR_PAUSE`. If application decided to
503 reset this stream, return
504 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`, then
505 the library will send RST_STREAM with INTERNAL_ERROR as error code.
506 The application can also return
507 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, which will
508 result in connection closure. Returning any other value is treated
509 as :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned.
510 .. type:: ssize_t (*nghttp2_recv_callback)(nghttp2_session *session, uint8_t *buf, size_t length, int flags, void *user_data)
513 Callback function invoked when *session* wants to receive data from
514 the remote peer. The implementation of this function must read at
515 most *length* bytes of data and store it in *buf*. The *flags* is
516 currently not used and always 0. It must return the number of
517 bytes written in *buf* if it succeeds. If it cannot read any
518 single byte without blocking, it must return
519 :macro:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. If it gets EOF
520 before it reads any single byte, it must return
521 :macro:`nghttp2_error.NGHTTP2_ERR_EOF`. For other errors, it must
522 return :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
523 Returning 0 is treated as
524 :macro:`nghttp2_error.NGHTTP2_ERR_WOULDBLOCK`. The *user_data*
525 pointer is the third argument passed in to the call to
526 `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
528 This callback is required if the application uses
529 `nghttp2_session_recv()` to receive data from the remote endpoint.
530 If the application uses solely `nghttp2_session_mem_recv()`
531 instead, this callback function is unnecessary.
533 To set this callback to :type:`nghttp2_session_callbacks`, use
534 `nghttp2_session_callbacks_set_recv_callback()`.
535 .. type:: int (*nghttp2_on_frame_recv_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)
538 Callback function invoked by `nghttp2_session_recv()` and
539 `nghttp2_session_mem_recv()` when a frame is received. The
540 *user_data* pointer is the third argument passed in to the call to
541 `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
543 If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
544 member of their data structure are always ``NULL`` and 0
545 respectively. The header name/value pairs are emitted via
546 :type:`nghttp2_on_header_callback`.
548 For HEADERS, PUSH_PROMISE and DATA frames, this callback may be
549 called after stream is closed (see
550 :type:`nghttp2_on_stream_close_callback`). The application should
551 check that stream is still alive using its own stream management or
552 :func:`nghttp2_session_get_stream_user_data()`.
554 Only HEADERS and DATA frame can signal the end of incoming data.
555 If ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the
556 *frame* is the last frame from the remote peer in this stream.
558 This callback won't be called for CONTINUATION frames.
559 HEADERS/PUSH_PROMISE + CONTINUATIONs are treated as single frame.
561 The implementation of this function must return 0 if it succeeds.
562 If nonzero value is returned, it is treated as fatal error and
563 `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
565 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
567 To set this callback to :type:`nghttp2_session_callbacks`, use
568 `nghttp2_session_callbacks_set_on_frame_recv_callback()`.
569 .. type:: int (*nghttp2_on_invalid_frame_recv_callback)( nghttp2_session *session, const nghttp2_frame *frame, int lib_error_code, void *user_data)
572 Callback function invoked by `nghttp2_session_recv()` and
573 `nghttp2_session_mem_recv()` when an invalid non-DATA frame is
574 received. The error is indicated by the *lib_error_code*, which is
575 one of the values defined in :type:`nghttp2_error`. When this
576 callback function is invoked, the library automatically submits
577 either RST_STREAM or GOAWAY frame. The *user_data* pointer is the
578 third argument passed in to the call to
579 `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
581 If frame is HEADERS or PUSH_PROMISE, the ``nva`` and ``nvlen``
582 member of their data structure are always ``NULL`` and 0
585 The implementation of this function must return 0 if it succeeds.
586 If nonzero is returned, it is treated as fatal error and
587 `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
589 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
591 To set this callback to :type:`nghttp2_session_callbacks`, use
592 `nghttp2_session_callbacks_set_on_invalid_frame_recv_callback()`.
593 .. type:: 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)
596 Callback function invoked when a chunk of data in DATA frame is
597 received. The *stream_id* is the stream ID this DATA frame belongs
598 to. The *flags* is the flags of DATA frame which this data chunk
599 is contained. ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not
600 necessarily mean this chunk of data is the last one in the stream.
601 You should use :type:`nghttp2_on_frame_recv_callback` to know all
602 data frames are received. The *user_data* pointer is the third
603 argument passed in to the call to `nghttp2_session_client_new()` or
604 `nghttp2_session_server_new()`.
606 If the application uses `nghttp2_session_mem_recv()`, it can return
607 :macro:`nghttp2_error.NGHTTP2_ERR_PAUSE` to make
608 `nghttp2_session_mem_recv()` return without processing further
609 input bytes. The memory by pointed by the *data* is retained until
610 `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
611 The application must retain the input bytes which was used to
612 produce the *data* parameter, because it may refer to the memory
613 region included in the input bytes.
615 The implementation of this function must return 0 if it succeeds.
616 If nonzero is returned, it is treated as fatal error, and
617 `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
619 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
621 To set this callback to :type:`nghttp2_session_callbacks`, use
622 `nghttp2_session_callbacks_set_on_data_chunk_recv_callback()`.
623 .. type:: int (*nghttp2_before_frame_send_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)
626 Callback function invoked just before the non-DATA frame *frame* is
627 sent. The *user_data* pointer is the third argument passed in to
628 the call to `nghttp2_session_client_new()` or
629 `nghttp2_session_server_new()`.
631 The implementation of this function must return 0 if it succeeds.
632 It can also return :macro:`nghttp2_error.NGHTTP2_ERR_CANCEL` to
633 cancel the transmission of the given frame.
635 If there is a fatal error while executing this callback, the
636 implementation should return
637 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, which makes
638 `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
640 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
642 If the other value is returned, it is treated as if
643 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned.
644 But the implementation should not rely on this since the library
645 may define new return value to extend its capability.
647 To set this callback to :type:`nghttp2_session_callbacks`, use
648 `nghttp2_session_callbacks_set_before_frame_send_callback()`.
649 .. type:: int (*nghttp2_on_frame_send_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)
652 Callback function invoked after the frame *frame* is sent. The
653 *user_data* pointer is the third argument passed in to the call to
654 `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
656 The implementation of this function must return 0 if it succeeds.
657 If nonzero is returned, it is treated as fatal error and
658 `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
660 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
662 To set this callback to :type:`nghttp2_session_callbacks`, use
663 `nghttp2_session_callbacks_set_on_frame_send_callback()`.
664 .. type:: int (*nghttp2_on_frame_not_send_callback)(nghttp2_session *session, const nghttp2_frame *frame, int lib_error_code, void *user_data)
667 Callback function invoked after the non-DATA frame *frame* is not
668 sent because of the error. The error is indicated by the
669 *lib_error_code*, which is one of the values defined in
670 :type:`nghttp2_error`. The *user_data* pointer is the third
671 argument passed in to the call to `nghttp2_session_client_new()` or
672 `nghttp2_session_server_new()`.
674 The implementation of this function must return 0 if it succeeds.
675 If nonzero is returned, it is treated as fatal error and
676 `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
678 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
680 `nghttp2_session_get_stream_user_data()` can be used to get
683 To set this callback to :type:`nghttp2_session_callbacks`, use
684 `nghttp2_session_callbacks_set_on_frame_not_send_callback()`.
685 .. type:: int (*nghttp2_on_stream_close_callback)(nghttp2_session *session, int32_t stream_id, uint32_t error_code, void *user_data)
688 Callback function invoked when the stream *stream_id* is closed.
689 The reason of closure is indicated by the *error_code*. The
690 *error_code* is usually one of :macro:`nghttp2_error_code`, but that
691 is not guaranteed. The stream_user_data, which was specified in
692 `nghttp2_submit_request()` or `nghttp2_submit_headers()`, is still
693 available in this function. The *user_data* pointer is the third
694 argument passed in to the call to `nghttp2_session_client_new()` or
695 `nghttp2_session_server_new()`.
697 This function is also called for a stream in reserved state.
699 The implementation of this function must return 0 if it succeeds.
700 If nonzero is returned, it is treated as fatal error and
701 `nghttp2_session_recv()`, `nghttp2_session_mem_recv()`,
702 `nghttp2_session_send()`, and `nghttp2_session_mem_send()`
703 functions immediately return
704 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
706 To set this callback to :type:`nghttp2_session_callbacks`, use
707 `nghttp2_session_callbacks_set_on_stream_close_callback()`.
708 .. type:: int (*nghttp2_on_begin_headers_callback)(nghttp2_session *session, const nghttp2_frame *frame, void *user_data)
711 Callback function invoked when the reception of header block in
712 HEADERS or PUSH_PROMISE is started. Each header name/value pair
713 will be emitted by :type:`nghttp2_on_header_callback`.
715 The ``frame->hd.flags`` may not have
716 :macro:`nghttp2_flag.NGHTTP2_FLAG_END_HEADERS` flag set, which
717 indicates that one or more CONTINUATION frames are involved. But
718 the application does not need to care about that because the header
719 name/value pairs are emitted transparently regardless of
722 The server applications probably create an object to store
723 information about new stream if ``frame->hd.type ==
724 NGHTTP2_HEADERS`` and ``frame->headers.cat ==
725 NGHTTP2_HCAT_REQUEST``. If *session* is configured as server side,
726 ``frame->headers.cat`` is either ``NGHTTP2_HCAT_REQUEST``
727 containing request headers or ``NGHTTP2_HCAT_HEADERS`` containing
728 trailer fields and never get PUSH_PROMISE in this callback.
730 For the client applications, ``frame->hd.type`` is either
731 ``NGHTTP2_HEADERS`` or ``NGHTTP2_PUSH_PROMISE``. In case of
732 ``NGHTTP2_HEADERS``, ``frame->headers.cat ==
733 NGHTTP2_HCAT_RESPONSE`` means that it is the first response
734 headers, but it may be non-final response which is indicated by 1xx
735 status code. In this case, there may be zero or more HEADERS frame
736 with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS`` which has
737 non-final response code and finally client gets exactly one HEADERS
738 frame with ``frame->headers.cat == NGHTTP2_HCAT_HEADERS``
739 containing final response headers (non-1xx status code). The
740 trailer fields also has ``frame->headers.cat ==
741 NGHTTP2_HCAT_HEADERS`` which does not contain any status code.
744 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will
745 close the stream (promised stream if frame is PUSH_PROMISE) by
746 issuing RST_STREAM with
747 :macro:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. In this case,
748 :type:`nghttp2_on_header_callback` and
749 :type:`nghttp2_on_frame_recv_callback` will not be invoked. If a
750 different error code is desirable, use
751 `nghttp2_submit_rst_stream()` with a desired error code and then
752 return :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
753 Again, use ``frame->push_promise.promised_stream_id`` as stream_id
754 parameter in `nghttp2_submit_rst_stream()` if frame is
757 The implementation of this function must return 0 if it succeeds.
759 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` to
760 reset the stream (promised stream if frame is PUSH_PROMISE). For
761 critical errors, it must return
762 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
763 value is returned, it is treated as if
764 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned. If
765 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
766 `nghttp2_session_mem_recv()` function will immediately return
767 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
769 To set this callback to :type:`nghttp2_session_callbacks`, use
770 `nghttp2_session_callbacks_set_on_begin_headers_callback()`.
771 .. type:: 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)
774 Callback function invoked when a header name/value pair is received
775 for the *frame*. The *name* of length *namelen* is header name.
776 The *value* of length *valuelen* is header value. The *flags* is
777 bitwise OR of one or more of :type:`nghttp2_nv_flag`.
779 If :macro:`nghttp2_nv_flag.NGHTTP2_NV_FLAG_NO_INDEX` is set in
780 *flags*, the receiver must not index this name/value pair when
781 forwarding it to the next hop. More specifically, "Literal Header
782 Field never Indexed" representation must be used in HPACK encoding.
784 When this callback is invoked, ``frame->hd.type`` is either
785 :macro:`nghttp2_frame_type.NGHTTP2_HEADERS` or
786 :macro:`nghttp2_frame_type.NGHTTP2_PUSH_PROMISE`. After all header
787 name/value pairs are processed with this callback, and no error has
788 been detected, :type:`nghttp2_on_frame_recv_callback` will be
789 invoked. If there is an error in decompression,
790 :type:`nghttp2_on_frame_recv_callback` for the *frame* will not be
793 Both *name* and *value* are guaranteed to be NULL-terminated. The
794 *namelen* and *valuelen* do not include terminal NULL. If
795 `nghttp2_option_set_no_http_messaging()` is used with nonzero
796 value, NULL character may be included in *name* or *value* before
799 Please note that unless `nghttp2_option_set_no_http_messaging()` is
800 used, nghttp2 library does perform validation against the *name*
801 and the *value* using `nghttp2_check_header_name()` and
802 `nghttp2_check_header_value()`. In addition to this, nghttp2
803 performs validation based on HTTP Messaging rule, which is briefly
804 explained in :ref:`http-messaging` section.
806 If the application uses `nghttp2_session_mem_recv()`, it can return
807 :macro:`nghttp2_error.NGHTTP2_ERR_PAUSE` to make
808 `nghttp2_session_mem_recv()` return without processing further
809 input bytes. The memory pointed by *frame*, *name* and *value*
810 parameters are retained until `nghttp2_session_mem_recv()` or
811 `nghttp2_session_recv()` is called. The application must retain
812 the input bytes which was used to produce these parameters, because
813 it may refer to the memory region included in the input bytes.
816 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will
817 close the stream (promised stream if frame is PUSH_PROMISE) by
818 issuing RST_STREAM with
819 :macro:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. In this case,
820 :type:`nghttp2_on_header_callback` and
821 :type:`nghttp2_on_frame_recv_callback` will not be invoked. If a
822 different error code is desirable, use
823 `nghttp2_submit_rst_stream()` with a desired error code and then
824 return :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
825 Again, use ``frame->push_promise.promised_stream_id`` as stream_id
826 parameter in `nghttp2_submit_rst_stream()` if frame is
829 The implementation of this function must return 0 if it succeeds.
830 It may return :macro:`nghttp2_error.NGHTTP2_ERR_PAUSE` or
831 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. For
832 other critical failures, it must return
833 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
834 nonzero value is returned, it is treated as
835 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If
836 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` is returned,
837 `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
839 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
841 To set this callback to :type:`nghttp2_session_callbacks`, use
842 `nghttp2_session_callbacks_set_on_header_callback()`.
846 Application should properly limit the total buffer size to store
847 incoming header fields. Without it, peer may send large number
848 of header fields or large header fields to cause out of memory in
849 local endpoint. Due to how HPACK works, peer can do this
850 effectively without using much memory on their own.
851 .. type:: int (*nghttp2_on_header_callback2)(nghttp2_session *session, const nghttp2_frame *frame, nghttp2_rcbuf *name, nghttp2_rcbuf *value, uint8_t flags, void *user_data)
854 Callback function invoked when a header name/value pair is received
855 for the *frame*. The *name* is header name. The *value* is header
856 value. The *flags* is bitwise OR of one or more of
857 :type:`nghttp2_nv_flag`.
859 This callback behaves like :type:`nghttp2_on_header_callback`,
860 except that *name* and *value* are stored in reference counted
861 buffer. If application wishes to keep these references without
862 copying them, use `nghttp2_rcbuf_incref()` to increment their
863 reference count. It is the application's responsibility to call
864 `nghttp2_rcbuf_decref()` if they called `nghttp2_rcbuf_incref()` so
865 as not to leak memory. If the *session* is created by
866 `nghttp2_session_server_new3()` or `nghttp2_session_client_new3()`,
867 the function to free memory is the one belongs to the mem
868 parameter. As long as this free function alives, *name* and
869 *value* can live after *session* was destroyed.
870 .. type:: int (*nghttp2_on_invalid_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)
873 Callback function invoked when a invalid header name/value pair is
874 received for the *frame*.
876 The parameter and behaviour are similar to
877 :type:`nghttp2_on_header_callback`. The difference is that this
878 callback is only invoked when a invalid header name/value pair is
879 received which is treated as stream error if this callback is not
880 set. Only invalid regular header field are passed to this
881 callback. In other words, invalid pseudo header field is not
882 passed to this callback. Also header fields which includes upper
883 cased latter are also treated as error without passing them to this
886 This callback is only considered if HTTP messaging validation is
887 turned on (which is on by default, see
888 `nghttp2_option_set_no_http_messaging()`).
890 With this callback, application inspects the incoming invalid
891 field, and it also can reset stream from this callback by returning
892 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. By
893 default, the error code is
894 :macro:`nghttp2_error_code.NGHTTP2_PROTOCOL_ERROR`. To change the
895 error code, call `nghttp2_submit_rst_stream()` with the error code
896 of choice in addition to returning
897 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
899 If 0 is returned, the header field is ignored, and the stream is
901 .. type:: int (*nghttp2_on_invalid_header_callback2)( nghttp2_session *session, const nghttp2_frame *frame, nghttp2_rcbuf *name, nghttp2_rcbuf *value, uint8_t flags, void *user_data)
904 Callback function invoked when a invalid header name/value pair is
905 received for the *frame*.
907 The parameter and behaviour are similar to
908 :type:`nghttp2_on_header_callback2`. The difference is that this
909 callback is only invoked when a invalid header name/value pair is
910 received which is silently ignored if this callback is not set.
911 Only invalid regular header field are passed to this callback. In
912 other words, invalid pseudo header field is not passed to this
913 callback. Also header fields which includes upper cased latter are
914 also treated as error without passing them to this callback.
916 This callback is only considered if HTTP messaging validation is
917 turned on (which is on by default, see
918 `nghttp2_option_set_no_http_messaging()`).
920 With this callback, application inspects the incoming invalid
921 field, and it also can reset stream from this callback by returning
922 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`. By
923 default, the error code is
924 :macro:`nghttp2_error_code.NGHTTP2_INTERNAL_ERROR`. To change the
925 error code, call `nghttp2_submit_rst_stream()` with the error code
926 of choice in addition to returning
927 :macro:`nghttp2_error.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.
928 .. type:: ssize_t (*nghttp2_select_padding_callback)(nghttp2_session *session, const nghttp2_frame *frame, size_t max_payloadlen, void *user_data)
931 Callback function invoked when the library asks application how
932 many padding bytes are required for the transmission of the
933 *frame*. The application must choose the total length of payload
934 including padded bytes in range [frame->hd.length, max_payloadlen],
935 inclusive. Choosing number not in this range will be treated as
936 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Returning
937 ``frame->hd.length`` means no padding is added. Returning
938 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will make
939 `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
941 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
943 To set this callback to :type:`nghttp2_session_callbacks`, use
944 `nghttp2_session_callbacks_set_select_padding_callback()`.
945 .. type:: 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)
948 Callback function invoked when library wants to get max length of
949 data to send data to the remote peer. The implementation of this
950 function should return a value in the following range. [1,
951 min(*session_remote_window_size*, *stream_remote_window_size*,
952 *remote_max_frame_size*)]. If a value greater than this range is
953 returned than the max allow value will be used. Returning a value
954 smaller than this range is treated as
955 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. The
956 *frame_type* is provided for future extensibility and identifies
957 the type of frame (see :type:`nghttp2_frame_type`) for which to get
958 the length for. Currently supported frame types are:
959 :macro:`nghttp2_frame_type.NGHTTP2_DATA`.
961 This callback can be used to control the length in bytes for which
962 :type:`nghttp2_data_source_read_callback` is allowed to send to the
963 remote endpoint. This callback is optional. Returning
964 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE` will signal the
965 entire session failure.
967 To set this callback to :type:`nghttp2_session_callbacks`, use
968 `nghttp2_session_callbacks_set_data_source_read_length_callback()`.
969 .. type:: int (*nghttp2_on_begin_frame_callback)(nghttp2_session *session, const nghttp2_frame_hd *hd, void *user_data)
972 Callback function invoked when a frame header is received. The
973 *hd* points to received frame header.
975 Unlike :type:`nghttp2_on_frame_recv_callback`, this callback will
976 also be called when frame header of CONTINUATION frame is received.
978 If both :type:`nghttp2_on_begin_frame_callback` and
979 :type:`nghttp2_on_begin_headers_callback` are set and HEADERS or
980 PUSH_PROMISE is received, :type:`nghttp2_on_begin_frame_callback`
981 will be called first.
983 The implementation of this function must return 0 if it succeeds.
984 If nonzero value is returned, it is treated as fatal error and
985 `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
987 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
989 To set this callback to :type:`nghttp2_session_callbacks`, use
990 `nghttp2_session_callbacks_set_on_begin_frame_callback()`.
991 .. type:: int (*nghttp2_on_extension_chunk_recv_callback)( nghttp2_session *session, const nghttp2_frame_hd *hd, const uint8_t *data, size_t len, void *user_data)
994 Callback function invoked when chunk of extension frame payload is
995 received. The *hd* points to frame header. The received
996 chunk is *data* of length *len*.
998 The implementation of this function must return 0 if it succeeds.
1000 To abort processing this extension frame, return
1001 :macro:`nghttp2_error.NGHTTP2_ERR_CANCEL`.
1003 If fatal error occurred, application should return
1004 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
1005 `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1007 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
1008 values are returned, currently they are treated as
1009 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
1010 .. type:: int (*nghttp2_unpack_extension_callback)(nghttp2_session *session, void **payload, const nghttp2_frame_hd *hd, void *user_data)
1013 Callback function invoked when library asks the application to
1014 unpack extension payload from its wire format. The extension
1015 payload has been passed to the application using
1016 :type:`nghttp2_on_extension_chunk_recv_callback`. The frame header
1017 is already unpacked by the library and provided as *hd*.
1019 To receive extension frames, the application must tell desired
1020 extension frame type to the library using
1021 `nghttp2_option_set_user_recv_extension_type()`.
1023 The implementation of this function may store the pointer to the
1024 created object as a result of unpacking in *\*payload*, and returns
1025 0. The pointer stored in *\*payload* is opaque to the library, and
1026 the library does not own its pointer. *\*payload* is initialized as
1027 ``NULL``. The *\*payload* is available as ``frame->ext.payload`` in
1028 :type:`nghttp2_on_frame_recv_callback`. Therefore if application
1029 can free that memory inside :type:`nghttp2_on_frame_recv_callback`
1030 callback. Of course, application has a liberty not ot use
1031 *\*payload*, and do its own mechanism to process extension frames.
1033 To abort processing this extension frame, return
1034 :macro:`nghttp2_error.NGHTTP2_ERR_CANCEL`.
1036 If fatal error occurred, application should return
1037 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
1038 `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
1040 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
1041 values are returned, currently they are treated as
1042 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
1043 .. type:: ssize_t (*nghttp2_pack_extension_callback)(nghttp2_session *session, uint8_t *buf, size_t len, const nghttp2_frame *frame, void *user_data)
1046 Callback function invoked when library asks the application to pack
1047 extension payload in its wire format. The frame header will be
1048 packed by library. Application must pack payload only.
1049 ``frame->ext.payload`` is the object passed to
1050 `nghttp2_submit_extension()` as payload parameter. Application
1051 must pack extension payload to the *buf* of its capacity *len*
1052 bytes. The *len* is at least 16KiB.
1054 The implementation of this function should return the number of
1055 bytes written into *buf* when it succeeds.
1057 To abort processing this extension frame, return
1058 :macro:`nghttp2_error.NGHTTP2_ERR_CANCEL`, and
1059 :type:`nghttp2_on_frame_not_send_callback` will be invoked.
1061 If fatal error occurred, application should return
1062 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. In this case,
1063 `nghttp2_session_send()` and `nghttp2_session_mem_send()` functions
1065 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the other
1066 values are returned, currently they are treated as
1067 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. If the return
1068 value is strictly larger than *len*, it is treated as
1069 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
1070 .. type:: int (*nghttp2_error_callback)(nghttp2_session *session, const char *msg, size_t len, void *user_data)
1073 Callback function invoked when library provides the error message
1074 intended for human consumption. This callback is solely for
1075 debugging purpose. The *msg* is typically NULL-terminated string
1076 of length *len*. *len* does not include the sentinel NULL
1079 This function is deprecated. The new application should use
1080 :type:`nghttp2_error_callback2`.
1082 The format of error message may change between nghttp2 library
1083 versions. The application should not depend on the particular
1086 Normally, application should return 0 from this callback. If fatal
1087 error occurred while doing something in this callback, application
1088 should return :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
1089 In this case, library will return immediately with return value
1090 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Currently, if
1091 nonzero value is returned from this callback, they are treated as
1092 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, but application
1093 should not rely on this details.
1094 .. type:: int (*nghttp2_error_callback2)(nghttp2_session *session, int lib_error_code, const char *msg, size_t len, void *user_data)
1097 Callback function invoked when library provides the error code, and
1098 message. This callback is solely for debugging purpose.
1099 *lib_error_code* is one of error code defined in
1100 :macro:`nghttp2_error`. The *msg* is typically NULL-terminated
1101 string of length *len*, and intended for human consumption. *len*
1102 does not include the sentinel NULL character.
1104 The format of error message may change between nghttp2 library
1105 versions. The application should not depend on the particular
1108 Normally, application should return 0 from this callback. If fatal
1109 error occurred while doing something in this callback, application
1110 should return :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`.
1111 In this case, library will return immediately with return value
1112 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`. Currently, if
1113 nonzero value is returned from this callback, they are treated as
1114 :macro:`nghttp2_error.NGHTTP2_ERR_CALLBACK_FAILURE`, but application
1115 should not rely on this details.
1116 .. type:: nghttp2_session_callbacks
1119 Callback functions for :type:`nghttp2_session`. The details of
1120 this structure are intentionally hidden from the public API.
1123 .. type:: void *(*nghttp2_malloc)(size_t size, void *mem_user_data)
1126 Custom memory allocator to replace malloc(). The *mem_user_data*
1127 is the mem_user_data member of :type:`nghttp2_mem` structure.
1128 .. type:: void (*nghttp2_free)(void *ptr, void *mem_user_data)
1131 Custom memory allocator to replace free(). The *mem_user_data* is
1132 the mem_user_data member of :type:`nghttp2_mem` structure.
1133 .. type:: void *(*nghttp2_calloc)(size_t nmemb, size_t size, void *mem_user_data)
1136 Custom memory allocator to replace calloc(). The *mem_user_data*
1137 is the mem_user_data member of :type:`nghttp2_mem` structure.
1138 .. type:: void *(*nghttp2_realloc)(void *ptr, size_t size, void *mem_user_data)
1141 Custom memory allocator to replace realloc(). The *mem_user_data*
1142 is the mem_user_data member of :type:`nghttp2_mem` structure.
1143 .. type:: nghttp2_mem
1146 Custom memory allocator functions and user defined pointer. The
1147 *mem_user_data* member is passed to each allocator function. This
1148 can be used, for example, to achieve per-session memory pool.
1150 In the following example code, ``my_malloc``, ``my_free``,
1151 ``my_calloc`` and ``my_realloc`` are the replacement of the
1152 standard allocators ``malloc``, ``free``, ``calloc`` and
1153 ``realloc`` respectively::
1155 void *my_malloc_cb(size_t size, void *mem_user_data) {
1156 return my_malloc(size);
1159 void my_free_cb(void *ptr, void *mem_user_data) { my_free(ptr); }
1161 void *my_calloc_cb(size_t nmemb, size_t size, void *mem_user_data) {
1162 return my_calloc(nmemb, size);
1165 void *my_realloc_cb(void *ptr, size_t size, void *mem_user_data) {
1166 return my_realloc(ptr, size);
1169 void session_new() {
1170 nghttp2_session *session;
1171 nghttp2_session_callbacks *callbacks;
1172 nghttp2_mem mem = {NULL, my_malloc_cb, my_free_cb, my_calloc_cb,
1177 nghttp2_session_client_new3(&session, callbacks, NULL, NULL, &mem);
1182 .. member:: void *mem_user_data
1184 An arbitrary user supplied data. This is passed to each
1186 .. member:: nghttp2_malloc malloc
1188 Custom allocator function to replace malloc().
1189 .. member:: nghttp2_free free
1191 Custom allocator function to replace free().
1192 .. member:: nghttp2_calloc calloc
1194 Custom allocator function to replace calloc().
1195 .. member:: nghttp2_realloc realloc
1197 Custom allocator function to replace realloc().
1199 .. type:: nghttp2_option
1202 Configuration options for :type:`nghttp2_session`. The details of
1203 this structure are intentionally hidden from the public API.
1206 .. type:: nghttp2_ext_altsvc
1209 The payload of ALTSVC frame. ALTSVC frame is a non-critical
1210 extension to HTTP/2. If this frame is received, and
1211 `nghttp2_option_set_user_recv_extension_type()` is not set, and
1212 `nghttp2_option_set_builtin_recv_extension_type()` is set for
1213 :macro:`nghttp2_frame_type.NGHTTP2_ALTSVC`,
1214 ``nghttp2_extension.payload`` will point to this struct.
1216 It has the following members:
1218 .. member:: uint8_t *origin
1220 The pointer to origin which this alternative service is
1221 associated with. This is not necessarily NULL-terminated.
1222 .. member:: size_t origin_len
1224 The length of the *origin*.
1225 .. member:: uint8_t *field_value
1227 The pointer to Alt-Svc field value contained in ALTSVC frame.
1228 This is not necessarily NULL-terminated.
1229 .. member:: size_t field_value_len
1231 The length of the *field_value*.
1233 .. type:: nghttp2_origin_entry
1236 The single entry of an origin.
1238 .. member:: uint8_t *origin
1240 The pointer to origin. No validation is made against this field
1241 by the library. This is not necessarily NULL-terminated.
1242 .. member:: size_t origin_len
1244 The length of the *origin*.
1246 .. type:: nghttp2_ext_origin
1249 The payload of ORIGIN frame. ORIGIN frame is a non-critical
1250 extension to HTTP/2 and defined by `RFC 8336
1251 <https://tools.ietf.org/html/rfc8336>`_.
1253 If this frame is received, and
1254 `nghttp2_option_set_user_recv_extension_type()` is not set, and
1255 `nghttp2_option_set_builtin_recv_extension_type()` is set for
1256 :macro:`nghttp2_frame_type.NGHTTP2_ORIGIN`,
1257 ``nghttp2_extension.payload`` will point to this struct.
1259 It has the following members:
1261 .. member:: size_t nov
1263 The number of origins contained in *ov*.
1264 .. member:: nghttp2_origin_entry *ov
1266 The pointer to the array of origins contained in ORIGIN frame.
1268 .. type:: nghttp2_hd_deflater
1271 HPACK deflater object.
1274 .. type:: nghttp2_hd_inflater
1277 HPACK inflater object.
1280 .. type:: nghttp2_stream
1283 The structure to represent HTTP/2 stream. The details of this
1284 structure are intentionally hidden from the public API.
1287 .. type:: void (*nghttp2_debug_vprintf_callback)(const char *format, va_list args)
1290 Callback function invoked when the library outputs debug logging.
1291 The function is called with arguments suitable for ``vfprintf(3)``
1293 The debug output is only enabled if the library is built with
1294 ``DEBUGBUILD`` macro defined.