doc/nghttp2_session_create_idle_stream.rst

   1
   2 nghttp2_session_create_idle_stream
   3 ==================================
   4
   5 Synopsis
   6 --------
   7
   8 *#include <nghttp2/nghttp2.h>*
   9
  10 .. function:: int nghttp2_session_create_idle_stream(nghttp2_session *session, int32_t stream_id, const nghttp2_priority_spec *pri_spec)
  11
  12
  13     Creates idle stream with the given *stream_id*, and priority
  14     *pri_spec*.
  15
  16     The stream creation is done without sending PRIORITY frame, which
  17     means that peer does not know about the existence of this idle
  18     stream in the local endpoint.
  19
  20     RFC 7540 does not disallow the use of creation of idle stream with
  21     odd or even stream ID regardless of client or server.  So this
  22     function can create odd or even stream ID regardless of client or
  23     server.  But probably it is a bit safer to use the stream ID the
  24     local endpoint can initiate (in other words, use odd stream ID for
  25     client, and even stream ID for server), to avoid potential
  26     collision from peer's instruction.  Also we can use
  27     `nghttp2_session_set_next_stream_id()` to avoid to open created
  28     idle streams accidentally if we follow this recommendation.
  29
  30     If *session* is initialized as server, and ``pri_spec->stream_id``
  31     points to the idle stream, the idle stream is created if it does
  32     not exist.  The created idle stream will depend on root stream
  33     (stream 0) with weight 16.
  34
  35     Otherwise, if stream denoted by ``pri_spec->stream_id`` is not
  36     found, we use default priority instead of given *pri_spec*.  That
  37     is make stream depend on root stream with weight 16.
  38
  39     This function returns 0 if it succeeds, or one of the following
  40     negative error codes:
  41
  42     :macro:`nghttp2_error.NGHTTP2_ERR_NOMEM`
  43         Out of memory.
  44     :macro:`nghttp2_error.NGHTTP2_ERR_INVALID_ARGUMENT`
  45         Attempted to depend on itself; or stream denoted by *stream_id*
  46         already exists; or *stream_id* cannot be used to create idle
  47         stream (in other words, local endpoint has already opened
  48         stream ID greater than or equal to the given stream ID; or
  49         *stream_id* is 0