1=pod 2 3=head1 NAME 4 5SSL_new_stream, SSL_STREAM_FLAG_UNI, SSL_STREAM_FLAG_NO_BLOCK, 6SSL_STREAM_FLAG_ADVANCE - create a new locally-initiated QUIC stream 7 8=head1 SYNOPSIS 9 10 #include <openssl/ssl.h> 11 12 #define SSL_STREAM_FLAG_UNI (1U << 0) 13 #define SSL_STREAM_FLAG_NO_BLOCK (1U << 1) 14 #define SSL_STREAM_FLAG_ADVANCE (1U << 2) 15 SSL *SSL_new_stream(SSL *ssl, uint64_t flags); 16 17=head1 DESCRIPTION 18 19The SSL_new_stream() function, when passed a QUIC connection SSL object, creates 20a new locally-initiated bidirectional or unidirectional QUIC stream and returns 21the newly created QUIC stream SSL object. 22 23If the B<SSL_STREAM_FLAG_UNI> flag is passed, a unidirectional stream is 24created; else a bidirectional stream is created. 25 26To retrieve the stream ID of the newly created stream, use 27L<SSL_get_stream_id(3)>. 28 29It is the caller's responsibility to free the QUIC stream SSL object using 30L<SSL_free(3)>. The lifetime of the QUIC connection SSL object must exceed that 31of the QUIC stream SSL object; in other words, the QUIC stream SSL object must 32be freed first. 33 34Once a stream has been created using SSL_new_stream(), it may be used in the 35normal way using L<SSL_read(3)> and L<SSL_write(3)>. 36 37This function can only be used to create stream objects for locally-initiated 38streams. To accept incoming streams initiated by a peer, use 39L<SSL_accept_stream(3)>. 40 41Calling SSL_new_stream() if there is no default stream already present 42inhibits the future creation of a default stream. See L<openssl-quic(7)>. 43 44The creation of new streams is subject to flow control by the QUIC protocol. If 45it is currently not possible to create a new locally initiated stream of the 46specified type, a call to SSL_new_stream() will either block (if the connection 47is configured in blocking mode) until a new stream can be created, or otherwise 48return NULL. 49 50This function operates in blocking mode if the QUIC connection SSL object is 51configured in blocking mode (see L<SSL_set_blocking_mode(3)>). It may also be 52used in nonblocking mode on a connection configured in blocking mode by passing 53the flag B<SSL_STREAM_FLAG_NO_BLOCK>. 54 55The flag B<SSL_STREAM_FLAG_ADVANCE> may be used to create a QUIC stream SSL 56object even if a new QUIC stream cannot yet be opened due to flow control. The 57caller may begin to use the new stream and fill the write buffer of the stream 58by calling L<SSL_write(3)>. However, no actual stream data (or QUIC frames 59regarding the stream) will be sent until QUIC flow control allows it. Any queued 60data will be sent as soon as a peer permits it. There is no guarantee the stream 61will be eventually created; for example, the connection could fail, or a peer 62might simply decide never to increase the number of allowed streams for the 63remainder of the connection lifetime. 64 65=head1 RETURN VALUES 66 67SSL_new_stream() returns a new stream object, or NULL on error. 68 69This function fails if called on a QUIC stream SSL object or on a non-QUIC SSL 70object. 71 72=head1 SEE ALSO 73 74L<SSL_accept_stream(3)>, L<SSL_free(3)> 75 76=head1 HISTORY 77 78SSL_new_stream() was added in OpenSSL 3.2. 79 80=head1 COPYRIGHT 81 82Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved. 83 84Licensed under the Apache License 2.0 (the "License"). You may not use 85this file except in compliance with the License. You can obtain a copy 86in the file LICENSE in the source distribution or at 87L<https://www.openssl.org/source/license.html>. 88 89=cut 90
