QUIC MSST: Add documentation for new APIs

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20765)

1 files changed, 74 insertions, 0 deletions

diff --git a/doc/man3/SSL_accept_stream.pod b/doc/man3/SSL_accept_stream.pod
new file mode 100644
index 0000000000..55c1868323
--- /dev/null
+++ b/doc/man3/SSL_accept_stream.pod
@@ -0,0 +1,74 @@
+=pod
+
+=head1 NAME
+
+SSL_accept_stream, SSL_get_accept_stream_queue_len, SSL_ACCEPT_STREAM_NO_BLOCK -
+accept an incoming QUIC stream from a QUIC peer
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ #define SSL_ACCEPT_STREAM_NO_BLOCK
+
+ SSL *SSL_accept_stream(SSL *ssl, uint64_t flags);
+
+ size_t SSL_get_accept_stream_queue_len(SSL *ssl);
+
+=head1 DESCRIPTION
+
+The SSL_accept_stream() function attempts to dequeue an incoming stream from the
+given QUIC connection SSL object and returns the newly allocated QUIC stream SSL
+object.
+
+If the queue of incoming streams is empty, this function returns NULL (in
+nonblocking mode) or waits for an incoming stream (in blocking mode). This
+function may still return NULL in blocking mode, for example if the underlying
+connection is terminated.
+
+The caller is responsible for managing the lifetime of the returned QUIC stream
+SSL object. The lifespan of the parent QUIC connection SSL object must exceed
+that of the QUIC stream SSL object; that is, the stream object must be freed
+first, using L<SSL_free(3)>.
+
+This function will block if the QUIC connection SSL object is configured in
+blocking mode (see L<SSL_set_blocking_mode(3)>), but this may be bypassed by
+passing the flag B<SSL_ACCEPT_STREAM_NO_BLOCK> in B<flags>. If this flag is set,
+this function never blocks.
+
+SSL_accept_stream_queue_len() returns the number of incoming streams currently
+waiting in the accept queue. It is intended for informational use only, as this
+number may change between a call to it and a subsequent call to
+SSL_accept_stream(), due to SSL_accept_stream() calls by other threads.
+
+Depending on whether default stream functionality is being used, it may be
+necessary to explicitly configure the incoming stream rejection policy before
+streams can be accepted; see L<SSL_set_incoming_stream_reject_policy(3)>.
+
+=head1 RETURN VALUES
+
+SSL_accept_stream() returns a newly allocated QUIC stream SSL object, or NULL if
+no new incoming streams are available, or if the connection has been terminated.
+
+SSL_get_accept_stream_queue_len() returns the number of incoming streams
+currently waiting in the accept queue.
+
+=head1 SEE ALSO
+
+L<SSL_new_stream(3)>, L<SSL_set_blocking_mode(3)>, L<SSL_free(3)>
+
+=head1 HISTORY
+
+SSL_accept_stream() and SSL_get_accept_stream_queue_len() were added in OpenSSL
+3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut