lib/nghttp2_session.h

   1 /*
   2  * nghttp2 - HTTP/2 C Library
   3  *
   4  * Copyright (c) 2012 Tatsuhiro Tsujikawa
   5  *
   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:
  13  *
  14  * The above copyright notice and this permission notice shall be
  15  * included in all copies or substantial portions of the Software.
  16  *
  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.
  24  */
  25 #ifndef NGHTTP2_SESSION_H
  26 #define NGHTTP2_SESSION_H
  27
  28 #ifdef HAVE_CONFIG_H
  29 #include <config.h>
  30 #endif /* HAVE_CONFIG_H */
  31
  32 #include <nghttp2/nghttp2.h>
  33 #include "nghttp2_pq.h"
  34 #include "nghttp2_map.h"
  35 #include "nghttp2_frame.h"
  36 #include "nghttp2_hd.h"
  37 #include "nghttp2_stream.h"
  38 #include "nghttp2_outbound_item.h"
  39 #include "nghttp2_int.h"
  40 #include "nghttp2_buf.h"
  41 #include "nghttp2_callbacks.h"
  42 #include "nghttp2_mem.h"
  43
  44 /*
  45  * Option flags.
  46  */
  47 typedef enum {
  48   NGHTTP2_OPTMASK_NO_AUTO_WINDOW_UPDATE = 1 << 0,
  49   NGHTTP2_OPTMASK_NO_RECV_CLIENT_MAGIC = 1 << 1,
  50   NGHTTP2_OPTMASK_NO_HTTP_MESSAGING = 1 << 2
  51 } nghttp2_optmask;
  52
  53 typedef enum {
  54   NGHTTP2_OB_POP_ITEM,
  55   NGHTTP2_OB_SEND_DATA,
  56   NGHTTP2_OB_SEND_NO_COPY,
  57   NGHTTP2_OB_SEND_CLIENT_MAGIC
  58 } nghttp2_outbound_state;
  59
  60 typedef struct {
  61   nghttp2_outbound_item *item;
  62   nghttp2_bufs framebufs;
  63   nghttp2_outbound_state state;
  64 } nghttp2_active_outbound_item;
  65
  66 /* Buffer length for inbound raw byte stream used in
  67    nghttp2_session_recv(). */
  68 #define NGHTTP2_INBOUND_BUFFER_LENGTH 16384
  69
  70 /* Internal state when receiving incoming frame */
  71 typedef enum {
  72   /* Receiving frame header */
  73   NGHTTP2_IB_READ_CLIENT_MAGIC,
  74   NGHTTP2_IB_READ_FIRST_SETTINGS,
  75   NGHTTP2_IB_READ_HEAD,
  76   NGHTTP2_IB_READ_NBYTE,
  77   NGHTTP2_IB_READ_HEADER_BLOCK,
  78   NGHTTP2_IB_IGN_HEADER_BLOCK,
  79   NGHTTP2_IB_IGN_PAYLOAD,
  80   NGHTTP2_IB_FRAME_SIZE_ERROR,
  81   NGHTTP2_IB_READ_SETTINGS,
  82   NGHTTP2_IB_READ_GOAWAY_DEBUG,
  83   NGHTTP2_IB_EXPECT_CONTINUATION,
  84   NGHTTP2_IB_IGN_CONTINUATION,
  85   NGHTTP2_IB_READ_PAD_DATA,
  86   NGHTTP2_IB_READ_DATA,
  87   NGHTTP2_IB_IGN_DATA,
  88   NGHTTP2_IB_IGN_ALL
  89 } nghttp2_inbound_state;
  90
  91 #define NGHTTP2_INBOUND_NUM_IV 7
  92
  93 typedef struct {
  94   nghttp2_frame frame;
  95   /* Storage for extension frame payload.  frame->ext.payload points
  96      to this structure to avoid frequent memory allocation. */
  97   nghttp2_ext_frame_payload ext_frame_payload;
  98   /* The received SETTINGS entry. The protocol says that we only cares
  99      about the defined settings ID. If unknown ID is received, it is
 100      ignored.  We use last entry to hold minimum header table size if
 101      same settings are multiple times. */
 102   nghttp2_settings_entry iv[NGHTTP2_INBOUND_NUM_IV];
 103   /* buffer pointers to small buffer, raw_sbuf */
 104   nghttp2_buf sbuf;
 105   /* buffer pointers to large buffer, raw_lbuf */
 106   nghttp2_buf lbuf;
 107   /* Large buffer, malloced on demand */
 108   uint8_t *raw_lbuf;
 109   /* The number of entry filled in |iv| */
 110   size_t niv;
 111   /* How many bytes we still need to receive for current frame */
 112   size_t payloadleft;
 113   /* padding length for the current frame */
 114   size_t padlen;
 115   nghttp2_inbound_state state;
 116   /* Small buffer.  Currently the largest contiguous chunk to buffer
 117      is frame header.  We buffer part of payload, but they are smaller
 118      than frame header. */
 119   uint8_t raw_sbuf[NGHTTP2_FRAME_HDLEN];
 120 } nghttp2_inbound_frame;
 121
 122 typedef struct {
 123   uint32_t header_table_size;
 124   uint32_t enable_push;
 125   uint32_t max_concurrent_streams;
 126   uint32_t initial_window_size;
 127   uint32_t max_frame_size;
 128   uint32_t max_header_list_size;
 129 } nghttp2_settings_storage;
 130
 131 typedef enum {
 132   NGHTTP2_GOAWAY_NONE = 0,
 133   /* Flag means that connection should be terminated after sending GOAWAY. */
 134   NGHTTP2_GOAWAY_TERM_ON_SEND = 0x1,
 135   /* Flag means GOAWAY to terminate session has been sent */
 136   NGHTTP2_GOAWAY_TERM_SENT = 0x2,
 137   /* Flag means GOAWAY was sent */
 138   NGHTTP2_GOAWAY_SENT = 0x4,
 139   /* Flag means GOAWAY was received */
 140   NGHTTP2_GOAWAY_RECV = 0x8
 141 } nghttp2_goaway_flag;
 142
 143 struct nghttp2_session {
 144   nghttp2_map /* <nghttp2_stream*> */ streams;
 145   nghttp2_stream_roots roots;
 146   /* Queue for outbound urgent frames (PING and SETTINGS) */
 147   nghttp2_outbound_queue ob_urgent;
 148   /* Queue for non-DATA frames */
 149   nghttp2_outbound_queue ob_reg;
 150   /* Queue for outbound stream-creating HEADERS (request or push
 151      response) frame, which are subject to
 152      SETTINGS_MAX_CONCURRENT_STREAMS limit. */
 153   nghttp2_outbound_queue ob_syn;
 154   /* Queue for DATA frame */
 155   nghttp2_pq /* <nghttp2_outbound_item*> */ ob_da_pq;
 156   nghttp2_active_outbound_item aob;
 157   nghttp2_inbound_frame iframe;
 158   nghttp2_hd_deflater hd_deflater;
 159   nghttp2_hd_inflater hd_inflater;
 160   nghttp2_session_callbacks callbacks;
 161   /* Memory allocator */
 162   nghttp2_mem mem;
 163   /* Base value when we schedule next DATA frame write.  This is
 164      updated when one frame was written. */
 165   uint64_t last_cycle;
 166   void *user_data;
 167   /* Points to the latest closed stream.  NULL if there is no closed
 168      stream.  Only used when session is initialized as server. */
 169   nghttp2_stream *closed_stream_head;
 170   /* Points to the oldest closed stream.  NULL if there is no closed
 171      stream.  Only used when session is initialized as server. */
 172   nghttp2_stream *closed_stream_tail;
 173   /* Points to the latest idle stream.  NULL if there is no idle
 174      stream.  Only used when session is initialized as server .*/
 175   nghttp2_stream *idle_stream_head;
 176   /* Points to the oldest idle stream.  NULL if there is no idle
 177      stream.  Only used when session is initialized as erver. */
 178   nghttp2_stream *idle_stream_tail;
 179   /* In-flight SETTINGS values. NULL does not necessarily mean there
 180      is no in-flight SETTINGS. */
 181   nghttp2_settings_entry *inflight_iv;
 182   /* The number of entries in |inflight_iv|. -1 if there is no
 183      in-flight SETTINGS. */
 184   ssize_t inflight_niv;
 185   /* The number of outgoing streams. This will be capped by
 186      remote_settings.max_concurrent_streams. */
 187   size_t num_outgoing_streams;
 188   /* The number of incoming streams. This will be capped by
 189      local_settings.max_concurrent_streams. */
 190   size_t num_incoming_streams;
 191   /* The number of closed streams still kept in |streams| hash.  The
 192      closed streams can be accessed through single linked list
 193      |closed_stream_head|.  The current implementation only keeps
 194      incoming streams and session is initialized as server. */
 195   size_t num_closed_streams;
 196   /* The number of idle streams kept in |streams| hash.  The idle
 197      streams can be accessed through doubly linked list
 198      |idle_stream_head|.  The current implementation only keeps idle
 199      streams if session is initialized as server. */
 200   size_t num_idle_streams;
 201   /* The number of bytes allocated for nvbuf */
 202   size_t nvbuflen;
 203   /* Next Stream ID. Made unsigned int to detect >= (1 << 31). */
 204   uint32_t next_stream_id;
 205   /* The largest stream ID received so far */
 206   int32_t last_recv_stream_id;
 207   /* The largest stream ID which has been processed in some way. This
 208      value will be used as last-stream-id when sending GOAWAY
 209      frame. */
 210   int32_t last_proc_stream_id;
 211   /* Counter of unique ID of PING. Wraps when it exceeds
 212      NGHTTP2_MAX_UNIQUE_ID */
 213   uint32_t next_unique_id;
 214   /* This is the last-stream-ID we have sent in GOAWAY */
 215   int32_t local_last_stream_id;
 216   /* This is the value in GOAWAY frame received from remote endpoint. */
 217   int32_t remote_last_stream_id;
 218   /* Current sender window size. This value is computed against the
 219      current initial window size of remote endpoint. */
 220   int32_t remote_window_size;
 221   /* Keep track of the number of bytes received without
 222      WINDOW_UPDATE. This could be negative after submitting negative
 223      value to WINDOW_UPDATE. */
 224   int32_t recv_window_size;
 225   /* The number of bytes consumed by the application and now is
 226      subject to WINDOW_UPDATE.  This is only used when auto
 227      WINDOW_UPDATE is turned off. */
 228   int32_t consumed_size;
 229   /* The amount of recv_window_size cut using submitting negative
 230      value to WINDOW_UPDATE */
 231   int32_t recv_reduction;
 232   /* window size for local flow control. It is initially set to
 233      NGHTTP2_INITIAL_CONNECTION_WINDOW_SIZE and could be
 234      increased/decreased by submitting WINDOW_UPDATE. See
 235      nghttp2_submit_window_update(). */
 236   int32_t local_window_size;
 237   /* Settings value received from the remote endpoint. We just use ID
 238      as index. The index = 0 is unused. */
 239   nghttp2_settings_storage remote_settings;
 240   /* Settings value of the local endpoint. */
 241   nghttp2_settings_storage local_settings;
 242   /* Option flags. This is bitwise-OR of 0 or more of nghttp2_optmask. */
 243   uint32_t opt_flags;
 244   /* Unacked local SETTINGS_MAX_CONCURRENT_STREAMS value. We use this
 245      to refuse the incoming stream if it exceeds this value. */
 246   uint32_t pending_local_max_concurrent_stream;
 247   /* Unacked local ENABLE_PUSH value.  We use this to refuse
 248      PUSH_PROMISE before SETTINGS ACK is received. */
 249   uint8_t pending_enable_push;
 250   /* Nonzero if the session is server side. */
 251   uint8_t server;
 252   /* Flags indicating GOAWAY is sent and/or recieved. The flags are
 253      composed by bitwise OR-ing nghttp2_goaway_flag. */
 254   uint8_t goaway_flags;
 255 };
 256
 257 /* Struct used when updating initial window size of each active
 258    stream. */
 259 typedef struct {
 260   nghttp2_session *session;
 261   int32_t new_window_size, old_window_size;
 262 } nghttp2_update_window_size_arg;
 263
 264 typedef struct {
 265   nghttp2_session *session;
 266   /* linked list of streams to close */
 267   nghttp2_stream *head;
 268   int32_t last_stream_id;
 269   /* nonzero if GOAWAY is sent to peer, which means we are going to
 270      close incoming streams.  zero if GOAWAY is received from peer and
 271      we are going to close outgoing streams. */
 272   int incoming;
 273 } nghttp2_close_stream_on_goaway_arg;
 274
 275 /* TODO stream timeout etc */
 276
 277 /*
 278  * Returns nonzero value if |stream_id| is initiated by local
 279  * endpoint.
 280  */
 281 int nghttp2_session_is_my_stream_id(nghttp2_session *session,
 282                                     int32_t stream_id);
 283
 284 /*
 285  * Adds |item| to the outbound queue in |session|.  When this function
 286  * succeeds, it takes ownership of |item|. So caller must not free it
 287  * on success.
 288  *
 289  * This function returns 0 if it succeeds, or one of the following
 290  * negative error codes:
 291  *
 292  * NGHTTP2_ERR_NOMEM
 293  *     Out of memory.
 294  * NGHTTP2_ERR_STREAM_CLOSED
 295  *     Stream already closed (DATA frame only)
 296  */
 297 int nghttp2_session_add_item(nghttp2_session *session,
 298                              nghttp2_outbound_item *item);
 299
 300 /*
 301  * Adds RST_STREAM frame for the stream |stream_id| with the error
 302  * code |error_code|. This is a convenient function built on top of
 303  * nghttp2_session_add_frame() to add RST_STREAM easily.
 304  *
 305  * This function simply returns 0 without adding RST_STREAM frame if
 306  * given stream is in NGHTTP2_STREAM_CLOSING state, because multiple
 307  * RST_STREAM for a stream is redundant.
 308  *
 309  * This function returns 0 if it succeeds, or one of the following
 310  * negative error codes:
 311  *
 312  * NGHTTP2_ERR_NOMEM
 313  *     Out of memory.
 314  */
 315 int nghttp2_session_add_rst_stream(nghttp2_session *session, int32_t stream_id,
 316                                    uint32_t error_code);
 317
 318 /*
 319  * Adds PING frame. This is a convenient functin built on top of
 320  * nghttp2_session_add_frame() to add PING easily.
 321  *
 322  * If the |opaque_data| is not NULL, it must point to 8 bytes memory
 323  * region of data. The data pointed by |opaque_data| is copied. It can
 324  * be NULL. In this case, 8 bytes NULL is used.
 325  *
 326  * This function returns 0 if it succeeds, or one of the following
 327  * negative error codes:
 328  *
 329  * NGHTTP2_ERR_NOMEM
 330  *     Out of memory.
 331  */
 332 int nghttp2_session_add_ping(nghttp2_session *session, uint8_t flags,
 333                              const uint8_t *opaque_data);
 334
 335 /*
 336  * Adds GOAWAY frame with the last-stream-ID |last_stream_id| and the
 337  * error code |error_code|. This is a convenient function built on top
 338  * of nghttp2_session_add_frame() to add GOAWAY easily.  The
 339  * |aux_flags| are bitwise-OR of one or more of
 340  * nghttp2_goaway_aux_flag.
 341  *
 342  * This function returns 0 if it succeeds, or one of the following
 343  * negative error codes:
 344  *
 345  * NGHTTP2_ERR_NOMEM
 346  *     Out of memory.
 347  * NGHTTP2_ERR_INVALID_ARGUMENT
 348  *     The |opaque_data_len| is too large.
 349  */
 350 int nghttp2_session_add_goaway(nghttp2_session *session, int32_t last_stream_id,
 351                                uint32_t error_code, const uint8_t *opaque_data,
 352                                size_t opaque_data_len, uint8_t aux_flags);
 353
 354 /*
 355  * Adds WINDOW_UPDATE frame with stream ID |stream_id| and
 356  * window-size-increment |window_size_increment|. This is a convenient
 357  * function built on top of nghttp2_session_add_frame() to add
 358  * WINDOW_UPDATE easily.
 359  *
 360  * This function returns 0 if it succeeds, or one of the following
 361  * negative error codes:
 362  *
 363  * NGHTTP2_ERR_NOMEM
 364  *     Out of memory.
 365  */
 366 int nghttp2_session_add_window_update(nghttp2_session *session, uint8_t flags,
 367                                       int32_t stream_id,
 368                                       int32_t window_size_increment);
 369
 370 /*
 371  * Adds SETTINGS frame.
 372  *
 373  * This function returns 0 if it succeeds, or one of the following
 374  * negative error codes:
 375  *
 376  * NGHTTP2_ERR_NOMEM
 377  *     Out of memory.
 378  */
 379 int nghttp2_session_add_settings(nghttp2_session *session, uint8_t flags,
 380                                  const nghttp2_settings_entry *iv, size_t niv);
 381
 382 /*
 383  * Creates new stream in |session| with stream ID |stream_id|,
 384  * priority |pri_spec| and flags |flags|.  The |flags| is bitwise OR
 385  * of nghttp2_stream_flag.  Since this function is called when initial
 386  * HEADERS is sent or received, these flags are taken from it.  The
 387  * state of stream is set to |initial_state|. The |stream_user_data|
 388  * is a pointer to the arbitrary user supplied data to be associated
 389  * to this stream.
 390  *
 391  * If |initial_state| is NGHTTP2_STREAM_RESERVED, this function sets
 392  * NGHTTP2_STREAM_FLAG_PUSH flag set.
 393  *
 394  * This function returns a pointer to created new stream object, or
 395  * NULL.
 396  */
 397 nghttp2_stream *nghttp2_session_open_stream(nghttp2_session *session,
 398                                             int32_t stream_id, uint8_t flags,
 399                                             nghttp2_priority_spec *pri_spec,
 400                                             nghttp2_stream_state initial_state,
 401                                             void *stream_user_data);
 402
 403 /*
 404  * Closes stream whose stream ID is |stream_id|. The reason of closure
 405  * is indicated by the |error_code|. When closing the stream,
 406  * on_stream_close_callback will be called.
 407  *
 408  * If the session is initialized as server and |stream| is incoming
 409  * stream, stream is just marked closed and this function calls
 410  * nghttp2_session_keep_closed_stream() with |stream|.  Otherwise,
 411  * |stream| will be deleted from memory.
 412  *
 413  * This function returns 0 if it succeeds, or one the following
 414  * negative error codes:
 415  *
 416  * NGHTTP2_ERR_NOMEM
 417  *     Out of memory
 418  * NGHTTP2_ERR_INVALID_ARGUMENT
 419  *     The specified stream does not exist.
 420  * NGHTTP2_ERR_CALLBACK_FAILURE
 421  *     The callback function failed.
 422  */
 423 int nghttp2_session_close_stream(nghttp2_session *session, int32_t stream_id,
 424                                  uint32_t error_code);
 425
 426 /*
 427  * Deletes |stream| from memory.  After this function returns, stream
 428  * cannot be accessed.
 429  *
 430  */
 431 void nghttp2_session_destroy_stream(nghttp2_session *session,
 432                                     nghttp2_stream *stream);
 433
 434 /*
 435  * Tries to keep incoming closed stream |stream|.  Due to the
 436  * limitation of maximum number of streams in memory, |stream| is not
 437  * closed and just deleted from memory (see
 438  * nghttp2_session_destroy_stream).
 439  */
 440 void nghttp2_session_keep_closed_stream(nghttp2_session *session,
 441                                         nghttp2_stream *stream);
 442
 443 /*
 444  * Appends |stream| to linked list |session->idle_stream_head|.  We
 445  * apply fixed limit for list size.  To fit into that limit, one or
 446  * more oldest streams are removed from list as necessary.
 447  */
 448 void nghttp2_session_keep_idle_stream(nghttp2_session *session,
 449                                       nghttp2_stream *stream);
 450
 451 /*
 452  * Detaches |stream| from idle streams linked list.
 453  */
 454 void nghttp2_session_detach_idle_stream(nghttp2_session *session,
 455                                         nghttp2_stream *stream);
 456
 457 /*
 458  * Deletes closed stream to ensure that number of incoming streams
 459  * including active and closed is in the maximum number of allowed
 460  * stream.  If |offset| is nonzero, it is decreased from the maximum
 461  * number of allowed stream when comparing number of active and closed
 462  * stream and the maximum number.
 463  */
 464 void nghttp2_session_adjust_closed_stream(nghttp2_session *session,
 465                                           ssize_t offset);
 466
 467 /*
 468  * Deletes idle stream to ensure that number of idle streams is in
 469  * certain limit.
 470  */
 471 void nghttp2_session_adjust_idle_stream(nghttp2_session *session);
 472
 473 /*
 474  * If further receptions and transmissions over the stream |stream_id|
 475  * are disallowed, close the stream with error code NGHTTP2_NO_ERROR.
 476  *
 477  * This function returns 0 if it
 478  * succeeds, or one of the following negative error codes:
 479  *
 480  * NGHTTP2_ERR_INVALID_ARGUMENT
 481  *     The specified stream does not exist.
 482  */
 483 int nghttp2_session_close_stream_if_shut_rdwr(nghttp2_session *session,
 484                                               nghttp2_stream *stream);
 485
 486 int nghttp2_session_end_request_headers_received(nghttp2_session *session,
 487                                                  nghttp2_frame *frame,
 488                                                  nghttp2_stream *stream);
 489
 490 int nghttp2_session_end_response_headers_received(nghttp2_session *session,
 491                                                   nghttp2_frame *frame,
 492                                                   nghttp2_stream *stream);
 493
 494 int nghttp2_session_end_headers_received(nghttp2_session *session,
 495                                          nghttp2_frame *frame,
 496                                          nghttp2_stream *stream);
 497
 498 int nghttp2_session_on_request_headers_received(nghttp2_session *session,
 499                                                 nghttp2_frame *frame);
 500
 501 int nghttp2_session_on_response_headers_received(nghttp2_session *session,
 502                                                  nghttp2_frame *frame,
 503                                                  nghttp2_stream *stream);
 504
 505 int nghttp2_session_on_push_response_headers_received(nghttp2_session *session,
 506                                                       nghttp2_frame *frame,
 507                                                       nghttp2_stream *stream);
 508
 509 /*
 510  * Called when HEADERS is received, assuming |frame| is properly
 511  * initialized.  This function does first validate received frame and
 512  * then open stream and call callback functions.
 513  *
 514  * This function returns 0 if it succeeds, or one of the following
 515  * negative error codes:
 516  *
 517  * NGHTTP2_ERR_NOMEM
 518  *     Out of memory.
 519  * NGHTTP2_ERR_IGN_HEADER_BLOCK
 520  *     Frame was rejected and header block must be decoded but
 521  *     result must be ignored.
 522  * NGHTTP2_ERR_CALLBACK_FAILURE
 523  *     The read_callback failed
 524  */
 525 int nghttp2_session_on_headers_received(nghttp2_session *session,
 526                                         nghttp2_frame *frame,
 527                                         nghttp2_stream *stream);
 528
 529 /*
 530  * Called when PRIORITY is received, assuming |frame| is properly
 531  * initialized.
 532  *
 533  * This function returns 0 if it succeeds, or one of the following
 534  * negative error codes:
 535  *
 536  * NGHTTP2_ERR_NOMEM
 537  *     Out of memory.
 538  * NGHTTP2_ERR_CALLBACK_FAILURE
 539  *     The read_callback failed
 540  */
 541 int nghttp2_session_on_priority_received(nghttp2_session *session,
 542                                          nghttp2_frame *frame);
 543
 544 /*
 545  * Called when RST_STREAM is received, assuming |frame| is properly
 546  * initialized.
 547  *
 548  * This function returns 0 if it succeeds, or one the following
 549  * negative error codes:
 550  *
 551  * NGHTTP2_ERR_NOMEM
 552  *     Out of memory
 553  * NGHTTP2_ERR_CALLBACK_FAILURE
 554  *     The read_callback failed
 555  */
 556 int nghttp2_session_on_rst_stream_received(nghttp2_session *session,
 557                                            nghttp2_frame *frame);
 558
 559 /*
 560  * Called when SETTINGS is received, assuming |frame| is properly
 561  * initialized. If |noack| is non-zero, SETTINGS with ACK will not be
 562  * submitted. If |frame| has NGHTTP2_FLAG_ACK flag set, no SETTINGS
 563  * with ACK will not be submitted regardless of |noack|.
 564  *
 565  * This function returns 0 if it succeeds, or one the following
 566  * negative error codes:
 567  *
 568  * NGHTTP2_ERR_NOMEM
 569  *     Out of memory
 570  * NGHTTP2_ERR_CALLBACK_FAILURE
 571  *     The read_callback failed
 572  */
 573 int nghttp2_session_on_settings_received(nghttp2_session *session,
 574                                          nghttp2_frame *frame, int noack);
 575
 576 /*
 577  * Called when PUSH_PROMISE is received, assuming |frame| is properly
 578  * initialized.
 579  *
 580  * This function returns 0 if it succeeds, or one of the following
 581  * negative error codes:
 582  *
 583  * NGHTTP2_ERR_NOMEM
 584  *     Out of memory.
 585  * NGHTTP2_ERR_IGN_HEADER_BLOCK
 586  *     Frame was rejected and header block must be decoded but
 587  *     result must be ignored.
 588  * NGHTTP2_ERR_CALLBACK_FAILURE
 589  *     The read_callback failed
 590  */
 591 int nghttp2_session_on_push_promise_received(nghttp2_session *session,
 592                                              nghttp2_frame *frame);
 593
 594 /*
 595  * Called when PING is received, assuming |frame| is properly
 596  * initialized.
 597  *
 598  * This function returns 0 if it succeeds, or one of the following
 599  * negative error codes:
 600  *
 601  * NGHTTP2_ERR_NOMEM
 602  *     Out of memory.
 603  * NGHTTP2_ERR_CALLBACK_FAILURE
 604  *   The callback function failed.
 605  */
 606 int nghttp2_session_on_ping_received(nghttp2_session *session,
 607                                      nghttp2_frame *frame);
 608
 609 /*
 610  * Called when GOAWAY is received, assuming |frame| is properly
 611  * initialized.
 612  *
 613  * This function returns 0 if it succeeds, or one of the following
 614  * negative error codes:
 615  *
 616  * NGHTTP2_ERR_NOMEM
 617  *     Out of memory.
 618  * NGHTTP2_ERR_CALLBACK_FAILURE
 619  *   The callback function failed.
 620  */
 621 int nghttp2_session_on_goaway_received(nghttp2_session *session,
 622                                        nghttp2_frame *frame);
 623
 624 /*
 625  * Called when WINDOW_UPDATE is recieved, assuming |frame| is properly
 626  * initialized.
 627  *
 628  * This function returns 0 if it succeeds, or one of the following
 629  * negative error codes:
 630  *
 631  * NGHTTP2_ERR_NOMEM
 632  *     Out of memory.
 633  * NGHTTP2_ERR_CALLBACK_FAILURE
 634  *   The callback function failed.
 635  */
 636 int nghttp2_session_on_window_update_received(nghttp2_session *session,
 637                                               nghttp2_frame *frame);
 638
 639 /*
 640  * Called when DATA is received, assuming |frame| is properly
 641  * initialized.
 642  *
 643  * This function returns 0 if it succeeds, or one of the following
 644  * negative error codes:
 645  *
 646  * NGHTTP2_ERR_NOMEM
 647  *     Out of memory.
 648  * NGHTTP2_ERR_CALLBACK_FAILURE
 649  *   The callback function failed.
 650  */
 651 int nghttp2_session_on_data_received(nghttp2_session *session,
 652                                      nghttp2_frame *frame);
 653
 654 /*
 655  * Returns nghttp2_stream* object whose stream ID is |stream_id|.  It
 656  * could be NULL if such stream does not exist.  This function returns
 657  * NULL if stream is marked as closed.
 658  */
 659 nghttp2_stream *nghttp2_session_get_stream(nghttp2_session *session,
 660                                            int32_t stream_id);
 661
 662 /*
 663  * This function behaves like nghttp2_session_get_stream(), but it
 664  * returns stream object even if it is marked as closed or in
 665  * NGHTTP2_STREAM_IDLE state.
 666  */
 667 nghttp2_stream *nghttp2_session_get_stream_raw(nghttp2_session *session,
 668                                                int32_t stream_id);
 669
 670 /*
 671  * Packs DATA frame |frame| in wire frame format and stores it in
 672  * |bufs|.  Payload will be read using |aux_data->data_prd|.  The
 673  * length of payload is at most |datamax| bytes.
 674  *
 675  * This function returns 0 if it succeeds, or one of the following
 676  * negative error codes:
 677  *
 678  * NGHTTP2_ERR_DEFERRED
 679  *     The DATA frame is postponed.
 680  * NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE
 681  *     The read_callback failed (stream error).
 682  * NGHTTP2_ERR_NOMEM
 683  *     Out of memory.
 684  * NGHTTP2_ERR_CALLBACK_FAILURE
 685  *     The read_callback failed (session error).
 686  */
 687 int nghttp2_session_pack_data(nghttp2_session *session, nghttp2_bufs *bufs,
 688                               size_t datamax, nghttp2_frame *frame,
 689                               nghttp2_data_aux_data *aux_data,
 690                               nghttp2_stream *stream);
 691
 692 /*
 693  * Pops and returns next item to send. If there is no such item,
 694  * returns NULL.  This function takes into account max concurrent
 695  * streams. That means if session->ob_pq is empty but
 696  * session->ob_ss_pq has item and max concurrent streams is reached,
 697  * then this function returns NULL.
 698  */
 699 nghttp2_outbound_item *
 700 nghttp2_session_pop_next_ob_item(nghttp2_session *session);
 701
 702 /*
 703  * Returns next item to send. If there is no such item, this function
 704  * returns NULL.  This function takes into account max concurrent
 705  * streams. That means if session->ob_pq is empty but
 706  * session->ob_ss_pq has item and max concurrent streams is reached,
 707  * then this function returns NULL.
 708  */
 709 nghttp2_outbound_item *
 710 nghttp2_session_get_next_ob_item(nghttp2_session *session);
 711
 712 /*
 713  * Updates local settings with the |iv|. The number of elements in the
 714  * array pointed by the |iv| is given by the |niv|.  This function
 715  * assumes that the all settings_id member in |iv| are in range 1 to
 716  * NGHTTP2_SETTINGS_MAX, inclusive.
 717  *
 718  * While updating individual stream's local window size, if the window
 719  * size becomes strictly larger than NGHTTP2_MAX_WINDOW_SIZE,
 720  * RST_STREAM is issued against such a stream.
 721  *
 722  * This function returns 0 if it succeeds, or one of the following
 723  * negative error codes:
 724  *
 725  * NGHTTP2_ERR_NOMEM
 726  *     Out of memory
 727  */
 728 int nghttp2_session_update_local_settings(nghttp2_session *session,
 729                                           nghttp2_settings_entry *iv,
 730                                           size_t niv);
 731
 732 /*
 733  * Re-prioritize |stream|. The new priority specification is
 734  * |pri_spec|.
 735  *
 736  * This function returns 0 if it succeeds, or one of the following
 737  * negative error codes:
 738  *
 739  * NGHTTP2_ERR_NOMEM
 740  *     Out of memory
 741  */
 742 int nghttp2_session_reprioritize_stream(nghttp2_session *session,
 743                                         nghttp2_stream *stream,
 744                                         const nghttp2_priority_spec *pri_spec);
 745
 746 /*
 747  * Terminates current |session| with the |error_code|.  The |reason|
 748  * is NULL-terminated debug string.
 749  *
 750  * This function returns 0 if it succeeds, or one of the following
 751  * negative error codes:
 752  *
 753  * NGHTTP2_ERR_NOMEM
 754  *     Out of memory.
 755  * NGHTTP2_ERR_INVALID_ARGUMENT
 756  *     The |reason| is too long.
 757  */
 758 int nghttp2_session_terminate_session_with_reason(nghttp2_session *session,
 759                                                   uint32_t error_code,
 760                                                   const char *reason);
 761
 762 #endif /* NGHTTP2_SESSION_H */