2 * nghttp2 - HTTP/2 C Library
4 * Copyright (c) 2012 Tatsuhiro Tsujikawa
6 * Permission is hereby granted, free of charge, to any person obtaining
7 * a copy of this software and associated documentation files (the
8 * "Software"), to deal in the Software without restriction, including
9 * without limitation the rights to use, copy, modify, merge, publish,
10 * distribute, sublicense, and/or sell copies of the Software, and to
11 * permit persons to whom the Software is furnished to do so, subject to
12 * the following conditions:
14 * The above copyright notice and this permission notice shall be
15 * included in all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25 #ifndef NGHTTP2_SESSION_H
26 #define NGHTTP2_SESSION_H
30 #endif /* HAVE_CONFIG_H */
32 #include <nghttp2/nghttp2.h>
33 #include "nghttp2_map.h"
34 #include "nghttp2_frame.h"
35 #include "nghttp2_hd.h"
36 #include "nghttp2_stream.h"
37 #include "nghttp2_outbound_item.h"
38 #include "nghttp2_int.h"
39 #include "nghttp2_buf.h"
40 #include "nghttp2_callbacks.h"
41 #include "nghttp2_mem.h"
43 /* The global variable for tests where we want to disable strict
45 extern int nghttp2_enable_strict_preface;
51 NGHTTP2_OPTMASK_NO_AUTO_WINDOW_UPDATE = 1 << 0,
52 NGHTTP2_OPTMASK_NO_RECV_CLIENT_MAGIC = 1 << 1,
53 NGHTTP2_OPTMASK_NO_HTTP_MESSAGING = 1 << 2,
54 NGHTTP2_OPTMASK_NO_AUTO_PING_ACK = 1 << 3
58 * bitmask for built-in type to enable the default handling for that
62 NGHTTP2_TYPEMASK_NONE = 0,
63 NGHTTP2_TYPEMASK_ALTSVC = 1 << 0
69 NGHTTP2_OB_SEND_NO_COPY,
70 NGHTTP2_OB_SEND_CLIENT_MAGIC
71 } nghttp2_outbound_state;
74 nghttp2_outbound_item *item;
75 nghttp2_bufs framebufs;
76 nghttp2_outbound_state state;
77 } nghttp2_active_outbound_item;
79 /* Buffer length for inbound raw byte stream used in
80 nghttp2_session_recv(). */
81 #define NGHTTP2_INBOUND_BUFFER_LENGTH 3072//16384--LiuHan/08.12
83 /* The default maximum number of incoming reserved streams */
84 #define NGHTTP2_MAX_INCOMING_RESERVED_STREAMS 200
86 /* Even if we have less SETTINGS_MAX_CONCURRENT_STREAMS than this
87 number, we keep NGHTTP2_MIN_IDLE_STREAMS streams in idle state */
88 #define NGHTTP2_MIN_IDLE_STREAMS 16
90 /* The maximum number of items in outbound queue, which is considered
91 as flooding caused by peer. All frames are not considered here.
92 We only consider PING + ACK and SETTINGS + ACK. This is because
93 they both are response to the frame initiated by peer and peer can
94 send as many of them as they want. If peer does not read network,
95 response frames are stacked up, which leads to memory exhaustion.
96 The value selected here is arbitrary, but safe value and if we have
97 these frames in this number, it is considered suspicious. */
98 #define NGHTTP2_MAX_OBQ_FLOOD_ITEM 10000
100 /* The default value of maximum number of concurrent streams. */
101 #define NGHTTP2_DEFAULT_MAX_CONCURRENT_STREAMS 0xffffffffu
103 /* Internal state when receiving incoming frame */
105 /* Receiving frame header */
106 NGHTTP2_IB_READ_CLIENT_MAGIC,
107 NGHTTP2_IB_READ_FIRST_SETTINGS,
108 NGHTTP2_IB_READ_HEAD,
109 NGHTTP2_IB_READ_NBYTE,
110 NGHTTP2_IB_READ_HEADER_BLOCK,
111 NGHTTP2_IB_IGN_HEADER_BLOCK,
112 NGHTTP2_IB_IGN_PAYLOAD,
113 NGHTTP2_IB_FRAME_SIZE_ERROR,
114 NGHTTP2_IB_READ_SETTINGS,
115 NGHTTP2_IB_READ_GOAWAY_DEBUG,
116 NGHTTP2_IB_EXPECT_CONTINUATION,
117 NGHTTP2_IB_IGN_CONTINUATION,
118 NGHTTP2_IB_READ_PAD_DATA,
119 NGHTTP2_IB_READ_DATA,
122 NGHTTP2_IB_READ_ALTSVC_PAYLOAD,
123 NGHTTP2_IB_READ_EXTENSION_PAYLOAD
124 } nghttp2_inbound_state;
128 /* Storage for extension frame payload. frame->ext.payload points
129 to this structure to avoid frequent memory allocation. */
130 nghttp2_ext_frame_payload ext_frame_payload;
131 /* The received SETTINGS entry. For the standard settings entries,
132 we only keep the last seen value. For
133 SETTINGS_HEADER_TABLE_SIZE, we also keep minimum value in the
135 nghttp2_settings_entry *iv;
136 /* buffer pointers to small buffer, raw_sbuf */
138 /* buffer pointers to large buffer, raw_lbuf */
140 /* Large buffer, malloced on demand */
142 /* The number of entry filled in |iv| */
144 /* The number of entries |iv| can store. */
146 /* How many bytes we still need to receive for current frame */
148 /* padding length for the current frame */
150 nghttp2_inbound_state state;
151 /* Small buffer. Currently the largest contiguous chunk to buffer
152 is frame header. We buffer part of payload, but they are smaller
153 than frame header. */
154 uint8_t raw_sbuf[NGHTTP2_FRAME_HDLEN];
155 } nghttp2_inbound_frame;
158 uint32_t header_table_size;
159 uint32_t enable_push;
160 uint32_t max_concurrent_streams;
161 uint32_t initial_window_size;
162 uint32_t max_frame_size;
163 uint32_t max_header_list_size;
164 } nghttp2_settings_storage;
167 NGHTTP2_GOAWAY_NONE = 0,
168 /* Flag means that connection should be terminated after sending GOAWAY. */
169 NGHTTP2_GOAWAY_TERM_ON_SEND = 0x1,
170 /* Flag means GOAWAY to terminate session has been sent */
171 NGHTTP2_GOAWAY_TERM_SENT = 0x2,
172 /* Flag means GOAWAY was sent */
173 NGHTTP2_GOAWAY_SENT = 0x4,
174 /* Flag means GOAWAY was received */
175 NGHTTP2_GOAWAY_RECV = 0x8
176 } nghttp2_goaway_flag;
178 /* nghttp2_inflight_settings stores the SETTINGS entries which local
179 endpoint has sent to the remote endpoint, and has not received ACK
181 struct nghttp2_inflight_settings {
182 struct nghttp2_inflight_settings *next;
183 nghttp2_settings_entry *iv;
187 typedef struct nghttp2_inflight_settings nghttp2_inflight_settings;
189 struct nghttp2_session {
190 nghttp2_map /* <nghttp2_stream*> */ streams;
191 /* root of dependency tree*/
193 /* Queue for outbound urgent frames (PING and SETTINGS) */
194 nghttp2_outbound_queue ob_urgent;
195 /* Queue for non-DATA frames */
196 nghttp2_outbound_queue ob_reg;
197 /* Queue for outbound stream-creating HEADERS (request or push
198 response) frame, which are subject to
199 SETTINGS_MAX_CONCURRENT_STREAMS limit. */
200 nghttp2_outbound_queue ob_syn;
201 nghttp2_active_outbound_item aob;
202 nghttp2_inbound_frame iframe;
203 nghttp2_hd_deflater hd_deflater;
204 nghttp2_hd_inflater hd_inflater;
205 nghttp2_session_callbacks callbacks;
206 /* Memory allocator */
208 /* Base value when we schedule next DATA frame write. This is
209 updated when one frame was written. */
212 /* Points to the latest incoming closed stream. NULL if there is no
213 closed stream. Only used when session is initialized as
215 nghttp2_stream *closed_stream_head;
216 /* Points to the oldest incoming closed stream. NULL if there is no
217 closed stream. Only used when session is initialized as
219 nghttp2_stream *closed_stream_tail;
220 /* Points to the latest idle stream. NULL if there is no idle
221 stream. Only used when session is initialized as server .*/
222 nghttp2_stream *idle_stream_head;
223 /* Points to the oldest idle stream. NULL if there is no idle
224 stream. Only used when session is initialized as erver. */
225 nghttp2_stream *idle_stream_tail;
226 /* Queue of In-flight SETTINGS values. SETTINGS bearing ACK is not
227 considered as in-flight. */
228 nghttp2_inflight_settings *inflight_settings_head;
229 /* The number of outgoing streams. This will be capped by
230 remote_settings.max_concurrent_streams. */
231 size_t num_outgoing_streams;
232 /* The number of incoming streams. This will be capped by
233 local_settings.max_concurrent_streams. */
234 size_t num_incoming_streams;
235 /* The number of incoming reserved streams. This is the number of
236 streams in reserved (remote) state. RFC 7540 does not limit this
237 number. nghttp2 offers
238 nghttp2_option_set_max_reserved_remote_streams() to achieve this.
239 If it is used, num_incoming_streams is capped by
240 max_incoming_reserved_streams. Client application should
241 consider to set this because without that server can send
242 arbitrary number of PUSH_PROMISE, and exhaust client's memory. */
243 size_t num_incoming_reserved_streams;
244 /* The maximum number of incoming reserved streams (reserved
245 (remote) state). RST_STREAM will be sent for the pushed stream
246 which exceeds this limit. */
247 size_t max_incoming_reserved_streams;
248 /* The number of closed streams still kept in |streams| hash. The
249 closed streams can be accessed through single linked list
250 |closed_stream_head|. The current implementation only keeps
251 incoming streams and session is initialized as server. */
252 size_t num_closed_streams;
253 /* The number of idle streams kept in |streams| hash. The idle
254 streams can be accessed through doubly linked list
255 |idle_stream_head|. The current implementation only keeps idle
256 streams if session is initialized as server. */
257 size_t num_idle_streams;
258 /* The number of bytes allocated for nvbuf */
260 /* Counter for detecting flooding in outbound queue */
261 size_t obq_flood_counter_;
262 /* The maximum length of header block to send. Calculated by the
263 same way as nghttp2_hd_deflate_bound() does. */
264 size_t max_send_header_block_length;
265 /* Next Stream ID. Made unsigned int to detect >= (1 << 31). */
266 uint32_t next_stream_id;
267 /* The last stream ID this session initiated. For client session,
268 this is the last stream ID it has sent. For server session, it
269 is the last promised stream ID sent in PUSH_PROMISE. */
270 int32_t last_sent_stream_id;
271 /* The largest stream ID received so far */
272 int32_t last_recv_stream_id;
273 /* The largest stream ID which has been processed in some way. This
274 value will be used as last-stream-id when sending GOAWAY
276 int32_t last_proc_stream_id;
277 /* Counter of unique ID of PING. Wraps when it exceeds
278 NGHTTP2_MAX_UNIQUE_ID */
279 uint32_t next_unique_id;
280 /* This is the last-stream-ID we have sent in GOAWAY */
281 int32_t local_last_stream_id;
282 /* This is the value in GOAWAY frame received from remote endpoint. */
283 int32_t remote_last_stream_id;
284 /* Current sender window size. This value is computed against the
285 current initial window size of remote endpoint. */
286 int32_t remote_window_size;
287 /* Keep track of the number of bytes received without
288 WINDOW_UPDATE. This could be negative after submitting negative
289 value to WINDOW_UPDATE. */
290 int32_t recv_window_size;
291 /* The number of bytes consumed by the application and now is
292 subject to WINDOW_UPDATE. This is only used when auto
293 WINDOW_UPDATE is turned off. */
294 int32_t consumed_size;
295 /* The amount of recv_window_size cut using submitting negative
296 value to WINDOW_UPDATE */
297 int32_t recv_reduction;
298 /* window size for local flow control. It is initially set to
299 NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE and could be
300 increased/decreased by submitting WINDOW_UPDATE. See
301 nghttp2_submit_window_update(). */
302 int32_t local_window_size;
303 /* Settings value received from the remote endpoint. We just use ID
304 as index. The index = 0 is unused. */
305 nghttp2_settings_storage remote_settings;
306 /* Settings value of the local endpoint. */
307 nghttp2_settings_storage local_settings;
308 /* Option flags. This is bitwise-OR of 0 or more of nghttp2_optmask. */
310 /* Unacked local SETTINGS_MAX_CONCURRENT_STREAMS value. We use this
311 to refuse the incoming stream if it exceeds this value. */
312 uint32_t pending_local_max_concurrent_stream;
313 /* The bitwose OR of zero or more of nghttp2_typemask to indicate
314 that the default handling of extension frame is enabled. */
315 uint32_t builtin_recv_ext_types;
316 /* Unacked local ENABLE_PUSH value. We use this to refuse
317 PUSH_PROMISE before SETTINGS ACK is received. */
318 uint8_t pending_enable_push;
319 /* Nonzero if the session is server side. */
321 /* Flags indicating GOAWAY is sent and/or recieved. The flags are
322 composed by bitwise OR-ing nghttp2_goaway_flag. */
323 uint8_t goaway_flags;
324 /* This flag is used to reduce excessive queuing of WINDOW_UPDATE to
325 this session. The nonzero does not necessarily mean
326 WINDOW_UPDATE is not queued. */
327 uint8_t window_update_queued;
328 /* Bitfield of extension frame types that application is willing to
329 receive. To designate the bit of given frame type i, use
330 user_recv_ext_types[i / 8] & (1 << (i & 0x7)). First 10 frame
331 types are standard frame types and not used in this bitfield. If
332 bit is set, it indicates that incoming frame with that type is
333 passed to user defined callbacks, otherwise they are ignored. */
334 uint8_t user_recv_ext_types[32];
337 /* Struct used when updating initial window size of each active
340 nghttp2_session *session;
341 int32_t new_window_size, old_window_size;
342 } nghttp2_update_window_size_arg;
345 nghttp2_session *session;
346 /* linked list of streams to close */
347 nghttp2_stream *head;
348 int32_t last_stream_id;
349 /* nonzero if GOAWAY is sent to peer, which means we are going to
350 close incoming streams. zero if GOAWAY is received from peer and
351 we are going to close outgoing streams. */
353 } nghttp2_close_stream_on_goaway_arg;
355 /* TODO stream timeout etc */
358 * Returns nonzero value if |stream_id| is initiated by local
361 int nghttp2_session_is_my_stream_id(nghttp2_session *session,
365 * Adds |item| to the outbound queue in |session|. When this function
366 * succeeds, it takes ownership of |item|. So caller must not free it
369 * This function returns 0 if it succeeds, or one of the following
370 * negative error codes:
374 * NGHTTP2_ERR_STREAM_CLOSED
375 * Stream already closed (DATA and PUSH_PROMISE frame only)
377 int nghttp2_session_add_item(nghttp2_session *session,
378 nghttp2_outbound_item *item);
381 * Adds RST_STREAM frame for the stream |stream_id| with the error
382 * code |error_code|. This is a convenient function built on top of
383 * nghttp2_session_add_frame() to add RST_STREAM easily.
385 * This function simply returns 0 without adding RST_STREAM frame if
386 * given stream is in NGHTTP2_STREAM_CLOSING state, because multiple
387 * RST_STREAM for a stream is redundant.
389 * This function returns 0 if it succeeds, or one of the following
390 * negative error codes:
395 int nghttp2_session_add_rst_stream(nghttp2_session *session, int32_t stream_id,
396 uint32_t error_code);
399 * Adds PING frame. This is a convenient functin built on top of
400 * nghttp2_session_add_frame() to add PING easily.
402 * If the |opaque_data| is not NULL, it must point to 8 bytes memory
403 * region of data. The data pointed by |opaque_data| is copied. It can
404 * be NULL. In this case, 8 bytes NULL is used.
406 * This function returns 0 if it succeeds, or one of the following
407 * negative error codes:
411 * NGHTTP2_ERR_FLOODED
412 * There are too many items in outbound queue; this only happens
413 * if NGHTTP2_FLAG_ACK is set in |flags|
415 int nghttp2_session_add_ping(nghttp2_session *session, uint8_t flags,
416 const uint8_t *opaque_data);
419 * Adds GOAWAY frame with the last-stream-ID |last_stream_id| and the
420 * error code |error_code|. This is a convenient function built on top
421 * of nghttp2_session_add_frame() to add GOAWAY easily. The
422 * |aux_flags| are bitwise-OR of one or more of
423 * nghttp2_goaway_aux_flag.
425 * This function returns 0 if it succeeds, or one of the following
426 * negative error codes:
430 * NGHTTP2_ERR_INVALID_ARGUMENT
431 * The |opaque_data_len| is too large.
433 int nghttp2_session_add_goaway(nghttp2_session *session, int32_t last_stream_id,
434 uint32_t error_code, const uint8_t *opaque_data,
435 size_t opaque_data_len, uint8_t aux_flags);
438 * Adds WINDOW_UPDATE frame with stream ID |stream_id| and
439 * window-size-increment |window_size_increment|. This is a convenient
440 * function built on top of nghttp2_session_add_frame() to add
441 * WINDOW_UPDATE easily.
443 * This function returns 0 if it succeeds, or one of the following
444 * negative error codes:
449 int nghttp2_session_add_window_update(nghttp2_session *session, uint8_t flags,
451 int32_t window_size_increment);
454 * Adds SETTINGS frame.
456 * This function returns 0 if it succeeds, or one of the following
457 * negative error codes:
461 * NGHTTP2_ERR_FLOODED
462 * There are too many items in outbound queue; this only happens
463 * if NGHTTP2_FLAG_ACK is set in |flags|
465 int nghttp2_session_add_settings(nghttp2_session *session, uint8_t flags,
466 const nghttp2_settings_entry *iv, size_t niv);
469 * Creates new stream in |session| with stream ID |stream_id|,
470 * priority |pri_spec| and flags |flags|. The |flags| is bitwise OR
471 * of nghttp2_stream_flag. Since this function is called when initial
472 * HEADERS is sent or received, these flags are taken from it. The
473 * state of stream is set to |initial_state|. The |stream_user_data|
474 * is a pointer to the arbitrary user supplied data to be associated
477 * If |initial_state| is NGHTTP2_STREAM_RESERVED, this function sets
478 * NGHTTP2_STREAM_FLAG_PUSH flag set.
480 * This function returns a pointer to created new stream object, or
483 * This function adjusts neither the number of closed streams or idle
484 * streams. The caller should manually call
485 * nghttp2_session_adjust_closed_stream() or
486 * nghttp2_session_adjust_idle_stream() respectively.
488 nghttp2_stream *nghttp2_session_open_stream(nghttp2_session *session,
489 int32_t stream_id, uint8_t flags,
490 nghttp2_priority_spec *pri_spec,
491 nghttp2_stream_state initial_state,
492 void *stream_user_data);
495 * Closes stream whose stream ID is |stream_id|. The reason of closure
496 * is indicated by the |error_code|. When closing the stream,
497 * on_stream_close_callback will be called.
499 * If the session is initialized as server and |stream| is incoming
500 * stream, stream is just marked closed and this function calls
501 * nghttp2_session_keep_closed_stream() with |stream|. Otherwise,
502 * |stream| will be deleted from memory.
504 * This function returns 0 if it succeeds, or one the following
505 * negative error codes:
509 * NGHTTP2_ERR_INVALID_ARGUMENT
510 * The specified stream does not exist.
511 * NGHTTP2_ERR_CALLBACK_FAILURE
512 * The callback function failed.
514 int nghttp2_session_close_stream(nghttp2_session *session, int32_t stream_id,
515 uint32_t error_code);
518 * Deletes |stream| from memory. After this function returns, stream
519 * cannot be accessed.
521 * This function returns 0 if it succeeds, or one the following
522 * negative error codes:
527 int nghttp2_session_destroy_stream(nghttp2_session *session,
528 nghttp2_stream *stream);
531 * Tries to keep incoming closed stream |stream|. Due to the
532 * limitation of maximum number of streams in memory, |stream| is not
533 * closed and just deleted from memory (see
534 * nghttp2_session_destroy_stream).
536 void nghttp2_session_keep_closed_stream(nghttp2_session *session,
537 nghttp2_stream *stream);
540 * Appends |stream| to linked list |session->idle_stream_head|. We
541 * apply fixed limit for list size. To fit into that limit, one or
542 * more oldest streams are removed from list as necessary.
544 void nghttp2_session_keep_idle_stream(nghttp2_session *session,
545 nghttp2_stream *stream);
548 * Detaches |stream| from idle streams linked list.
550 void nghttp2_session_detach_idle_stream(nghttp2_session *session,
551 nghttp2_stream *stream);
554 * Deletes closed stream to ensure that number of incoming streams
555 * including active and closed is in the maximum number of allowed
558 * This function returns 0 if it succeeds, or one the following
559 * negative error codes:
564 int nghttp2_session_adjust_closed_stream(nghttp2_session *session);
567 * Deletes idle stream to ensure that number of idle streams is in
570 * This function returns 0 if it succeeds, or one the following
571 * negative error codes:
576 int nghttp2_session_adjust_idle_stream(nghttp2_session *session);
579 * If further receptions and transmissions over the stream |stream_id|
580 * are disallowed, close the stream with error code NGHTTP2_NO_ERROR.
582 * This function returns 0 if it
583 * succeeds, or one of the following negative error codes:
585 * NGHTTP2_ERR_INVALID_ARGUMENT
586 * The specified stream does not exist.
588 int nghttp2_session_close_stream_if_shut_rdwr(nghttp2_session *session,
589 nghttp2_stream *stream);
591 int nghttp2_session_on_request_headers_received(nghttp2_session *session,
592 nghttp2_frame *frame);
594 int nghttp2_session_on_response_headers_received(nghttp2_session *session,
595 nghttp2_frame *frame,
596 nghttp2_stream *stream);
598 int nghttp2_session_on_push_response_headers_received(nghttp2_session *session,
599 nghttp2_frame *frame,
600 nghttp2_stream *stream);
603 * Called when HEADERS is received, assuming |frame| is properly
604 * initialized. This function does first validate received frame and
605 * then open stream and call callback functions.
607 * This function returns 0 if it succeeds, or one of the following
608 * negative error codes:
612 * NGHTTP2_ERR_IGN_HEADER_BLOCK
613 * Frame was rejected and header block must be decoded but
614 * result must be ignored.
615 * NGHTTP2_ERR_CALLBACK_FAILURE
616 * The read_callback failed
618 int nghttp2_session_on_headers_received(nghttp2_session *session,
619 nghttp2_frame *frame,
620 nghttp2_stream *stream);
623 * Called when PRIORITY is received, assuming |frame| is properly
626 * This function returns 0 if it succeeds, or one of the following
627 * negative error codes:
631 * NGHTTP2_ERR_CALLBACK_FAILURE
632 * The read_callback failed
634 int nghttp2_session_on_priority_received(nghttp2_session *session,
635 nghttp2_frame *frame);
638 * Called when RST_STREAM is received, assuming |frame| is properly
641 * This function returns 0 if it succeeds, or one the following
642 * negative error codes:
646 * NGHTTP2_ERR_CALLBACK_FAILURE
647 * The read_callback failed
649 int nghttp2_session_on_rst_stream_received(nghttp2_session *session,
650 nghttp2_frame *frame);
653 * Called when SETTINGS is received, assuming |frame| is properly
654 * initialized. If |noack| is non-zero, SETTINGS with ACK will not be
655 * submitted. If |frame| has NGHTTP2_FLAG_ACK flag set, no SETTINGS
656 * with ACK will not be submitted regardless of |noack|.
658 * This function returns 0 if it succeeds, or one the following
659 * negative error codes:
663 * NGHTTP2_ERR_CALLBACK_FAILURE
664 * The read_callback failed
665 * NGHTTP2_ERR_FLOODED
666 * There are too many items in outbound queue, and this is most
667 * likely caused by misbehaviour of peer.
669 int nghttp2_session_on_settings_received(nghttp2_session *session,
670 nghttp2_frame *frame, int noack);
673 * Called when PUSH_PROMISE is received, assuming |frame| is properly
676 * This function returns 0 if it succeeds, or one of the following
677 * negative error codes:
681 * NGHTTP2_ERR_IGN_HEADER_BLOCK
682 * Frame was rejected and header block must be decoded but
683 * result must be ignored.
684 * NGHTTP2_ERR_CALLBACK_FAILURE
685 * The read_callback failed
687 int nghttp2_session_on_push_promise_received(nghttp2_session *session,
688 nghttp2_frame *frame);
691 * Called when PING is received, assuming |frame| is properly
694 * This function returns 0 if it succeeds, or one of the following
695 * negative error codes:
699 * NGHTTP2_ERR_CALLBACK_FAILURE
700 * The callback function failed.
701 * NGHTTP2_ERR_FLOODED
702 * There are too many items in outbound queue, and this is most
703 * likely caused by misbehaviour of peer.
705 int nghttp2_session_on_ping_received(nghttp2_session *session,
706 nghttp2_frame *frame);
709 * Called when GOAWAY is received, assuming |frame| is properly
712 * This function returns 0 if it succeeds, or one of the following
713 * negative error codes:
717 * NGHTTP2_ERR_CALLBACK_FAILURE
718 * The callback function failed.
720 int nghttp2_session_on_goaway_received(nghttp2_session *session,
721 nghttp2_frame *frame);
724 * Called when WINDOW_UPDATE is recieved, assuming |frame| is properly
727 * This function returns 0 if it succeeds, or one of the following
728 * negative error codes:
732 * NGHTTP2_ERR_CALLBACK_FAILURE
733 * The callback function failed.
735 int nghttp2_session_on_window_update_received(nghttp2_session *session,
736 nghttp2_frame *frame);
739 * Called when ALTSVC is recieved, assuming |frame| is properly
742 * This function returns 0 if it succeeds, or one of the following
743 * negative error codes:
745 * NGHTTP2_ERR_CALLBACK_FAILURE
746 * The callback function failed.
748 int nghttp2_session_on_altsvc_received(nghttp2_session *session,
749 nghttp2_frame *frame);
752 * Called when DATA is received, assuming |frame| is properly
755 * This function returns 0 if it succeeds, or one of the following
756 * negative error codes:
760 * NGHTTP2_ERR_CALLBACK_FAILURE
761 * The callback function failed.
763 int nghttp2_session_on_data_received(nghttp2_session *session,
764 nghttp2_frame *frame);
767 * Returns nghttp2_stream* object whose stream ID is |stream_id|. It
768 * could be NULL if such stream does not exist. This function returns
769 * NULL if stream is marked as closed.
771 nghttp2_stream *nghttp2_session_get_stream(nghttp2_session *session,
775 * This function behaves like nghttp2_session_get_stream(), but it
776 * returns stream object even if it is marked as closed or in
777 * NGHTTP2_STREAM_IDLE state.
779 nghttp2_stream *nghttp2_session_get_stream_raw(nghttp2_session *session,
783 * Packs DATA frame |frame| in wire frame format and stores it in
784 * |bufs|. Payload will be read using |aux_data->data_prd|. The
785 * length of payload is at most |datamax| bytes.
787 * This function returns 0 if it succeeds, or one of the following
788 * negative error codes:
790 * NGHTTP2_ERR_DEFERRED
791 * The DATA frame is postponed.
792 * NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE
793 * The read_callback failed (stream error).
796 * NGHTTP2_ERR_CALLBACK_FAILURE
797 * The read_callback failed (session error).
799 int nghttp2_session_pack_data(nghttp2_session *session, nghttp2_bufs *bufs,
800 size_t datamax, nghttp2_frame *frame,
801 nghttp2_data_aux_data *aux_data,
802 nghttp2_stream *stream);
805 * Pops and returns next item to send. If there is no such item,
806 * returns NULL. This function takes into account max concurrent
807 * streams. That means if session->ob_syn has item and max concurrent
808 * streams is reached, the even if other queues contain items, then
809 * this function returns NULL.
811 nghttp2_outbound_item *
812 nghttp2_session_pop_next_ob_item(nghttp2_session *session);
815 * Returns next item to send. If there is no such item, this function
816 * returns NULL. This function takes into account max concurrent
817 * streams. That means if session->ob_syn has item and max concurrent
818 * streams is reached, the even if other queues contain items, then
819 * this function returns NULL.
821 nghttp2_outbound_item *
822 nghttp2_session_get_next_ob_item(nghttp2_session *session);
825 * Updates local settings with the |iv|. The number of elements in the
826 * array pointed by the |iv| is given by the |niv|. This function
827 * assumes that the all settings_id member in |iv| are in range 1 to
828 * NGHTTP2_SETTINGS_MAX, inclusive.
830 * While updating individual stream's local window size, if the window
831 * size becomes strictly larger than NGHTTP2_MAX_WINDOW_SIZE,
832 * RST_STREAM is issued against such a stream.
834 * This function returns 0 if it succeeds, or one of the following
835 * negative error codes:
840 int nghttp2_session_update_local_settings(nghttp2_session *session,
841 nghttp2_settings_entry *iv,
845 * Re-prioritize |stream|. The new priority specification is
846 * |pri_spec|. Caller must ensure that stream->hd.stream_id !=
847 * pri_spec->stream_id.
849 * This function does not adjust the number of idle streams. The
850 * caller should call nghttp2_session_adjust_idle_stream() later.
852 * This function returns 0 if it succeeds, or one of the following
853 * negative error codes:
858 int nghttp2_session_reprioritize_stream(nghttp2_session *session,
859 nghttp2_stream *stream,
860 const nghttp2_priority_spec *pri_spec);
863 * Terminates current |session| with the |error_code|. The |reason|
864 * is NULL-terminated debug string.
866 * This function returns 0 if it succeeds, or one of the following
867 * negative error codes:
871 * NGHTTP2_ERR_INVALID_ARGUMENT
872 * The |reason| is too long.
874 int nghttp2_session_terminate_session_with_reason(nghttp2_session *session,
878 #endif /* NGHTTP2_SESSION_H */