.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SSL_GET_STREAM_READ_STATE 3ossl"
.TH SSL_GET_STREAM_READ_STATE 3ossl "2024-06-04" "3.3.1" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SSL_get_stream_read_state, SSL_get_stream_write_state,
SSL_get_stream_read_error_code, SSL_get_stream_write_error_code,
SSL_STREAM_STATE_NONE, SSL_STREAM_STATE_OK, SSL_STREAM_STATE_WRONG_DIR,
SSL_STREAM_STATE_FINISHED, SSL_STREAM_STATE_RESET_LOCAL,
SSL_STREAM_STATE_RESET_REMOTE, SSL_STREAM_STATE_CONN_CLOSED \- get QUIC stream
state
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& #define SSL_STREAM_STATE_NONE
\& #define SSL_STREAM_STATE_OK
\& #define SSL_STREAM_STATE_WRONG_DIR
\& #define SSL_STREAM_STATE_FINISHED
\& #define SSL_STREAM_STATE_RESET_LOCAL
\& #define SSL_STREAM_STATE_RESET_REMOTE
\& #define SSL_STREAM_STATE_CONN_CLOSED
\&
\& int SSL_get_stream_read_state(SSL *ssl);
\& int SSL_get_stream_write_state(SSL *ssl);
\&
\& int SSL_get_stream_read_error_code(SSL *ssl, uint64_t *app_error_code);
\& int SSL_get_stream_write_error_code(SSL *ssl, uint64_t *app_error_code);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fISSL_get_stream_read_state()\fR and \fISSL_get_stream_write_state()\fR retrieve the
overall state of the receiving and sending parts of a \s-1QUIC\s0 stream, respectively.
.PP
They both return one of the following values:
.IP "\fB\s-1SSL_STREAM_STATE_NONE\s0\fR" 4
.IX Item "SSL_STREAM_STATE_NONE"
This value is returned if called on a non-QUIC \s-1SSL\s0 object, or on a \s-1QUIC\s0
connection \s-1SSL\s0 object without a default stream attached.
.IP "\fB\s-1SSL_STREAM_STATE_OK\s0\fR" 4
.IX Item "SSL_STREAM_STATE_OK"
This value is returned on a stream which has not been concluded and remains
healthy.
.IP "\fB\s-1SSL_STREAM_STATE_WRONG_DIR\s0\fR" 4
.IX Item "SSL_STREAM_STATE_WRONG_DIR"
This value is returned if \fISSL_get_stream_read_state()\fR is called on a
locally-initiated (and thus send-only) unidirectional stream, or, conversely, if
\&\fISSL_get_stream_write_state()\fR is called on a remotely-initiated (and thus
receive-only) unidirectional stream.
.IP "\fB\s-1SSL_STREAM_STATE_FINISHED\s0\fR" 4
.IX Item "SSL_STREAM_STATE_FINISHED"
For \fISSL_get_stream_read_state()\fR, this value is returned when the remote peer has
signalled the end of the receiving part of the stream. Note that there may still
be residual data available to read via \fISSL_read\fR\|(3) when this state is
returned.
.Sp
For \fISSL_get_stream_write_state()\fR, this value is returned when the local
application has concluded the stream using \fISSL_stream_conclude\fR\|(3). Future
\&\fISSL_write\fR\|(3) calls will not succeed.
.IP "\fB\s-1SSL_STREAM_STATE_RESET_LOCAL\s0\fR" 4
.IX Item "SSL_STREAM_STATE_RESET_LOCAL"
This value is returned when the applicable stream part was reset by the local
application.
.Sp
For \fISSL_get_stream_read_state()\fR, this means that the receiving part of the
stream was aborted using a locally transmitted \s-1QUIC \s0\fB\s-1STOP_SENDING\s0\fR frame. It
may or may not still be possible to obtain any residual data which remains to be
read by calling \fISSL_read\fR\|(3).
.Sp
For \fISSL_get_stream_write_state()\fR, this means that the sending part of the stream
was aborted, for example because the application called \fISSL_stream_reset\fR\|(3),
or because a \s-1QUIC\s0 stream \s-1SSL\s0 object with an un-concluded sending part was freed
using \fISSL_free\fR\|(3). Calls to \fISSL_write\fR\|(3) will fail.
.Sp
When this value is returned, the application error code which was signalled can
be obtained by calling \fISSL_get_stream_read_error_code()\fR or
\&\fISSL_get_stream_write_error_code()\fR as appropriate.
.IP "\fB\s-1SSL_STREAM_STATE_RESET_REMOTE\s0\fR" 4
.IX Item "SSL_STREAM_STATE_RESET_REMOTE"
This value is returned when the applicable stream part was reset by the remote
peer.
.Sp
For \fISSL_get_stream_read_state()\fR, this means that the peer sent a \s-1QUIC
\&\s0\fB\s-1RESET_STREAM\s0\fR frame for the receiving part of the stream; the receiving part
of the stream was logically aborted by the peer.
.Sp
For \fISSL_get_stream_write_state()\fR, this means that the peer sent a \s-1QUIC
\&\s0\fB\s-1STOP_SENDING\s0\fR frame for the sending part of the stream; the peer has indicated
that it does not wish to receive further data on the sending part of the stream.
Calls to \fISSL_write\fR\|(3) will fail.
.Sp
When this value is returned, the application error code which was signalled can
be obtained by calling \fISSL_get_stream_read_error_code()\fR or
\&\fISSL_get_stream_write_error_code()\fR as appropriate.
.IP "\fB\s-1SSL_STREAM_STATE_CONN_CLOSED\s0\fR" 4
.IX Item "SSL_STREAM_STATE_CONN_CLOSED"
The \s-1QUIC\s0 connection to which the stream belongs was closed. You can obtain
information about the circumstances of this closure using
\&\fISSL_get_conn_close_info\fR\|(3). There may still be residual data available to
read via \fISSL_read\fR\|(3) when this state is returned. Calls to \fISSL_write\fR\|(3)
will fail. \fISSL_get_stream_read_state()\fR will return this state if and only if
\&\fISSL_get_stream_write_state()\fR will also return this state.
.PP
\&\fISSL_get_stream_read_error_code()\fR and \fISSL_get_stream_write_error_code()\fR provide
the application error code which was signalled during non-normal termination of
the receiving or sending parts of a stream, respectively. On success, the
application error code is written to \fI*app_error_code\fR.
.SH "NOTES"
.IX Header "NOTES"
If a \s-1QUIC\s0 connection is closed, the stream state for all streams transitions to
\&\fB\s-1SSL_STREAM_STATE_CONN_CLOSED\s0\fR, but no application error code can be retrieved
using \fISSL_get_stream_read_error_code()\fR or \fISSL_get_stream_write_error_code()\fR, as
the \s-1QUIC\s0 connection closure process does not cause an application error code to
be associated with each individual stream still existing at the time of
connection closure. However, you can obtain the overall error code associated
with the connection closure using \fISSL_get_conn_close_info\fR\|(3).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fISSL_get_stream_read_state()\fR and \fISSL_get_stream_write_state()\fR return one of the
\&\fB\s-1SSL_STREAM_STATE\s0\fR values. If called on a non-QUIC \s-1SSL\s0 object, or a \s-1QUIC\s0
connection \s-1SSL\s0 object without a default stream, \fB\s-1SSL_STREAM_STATE_NONE\s0\fR is
returned.
.PP
\&\fISSL_get_stream_read_error_code()\fR and \fISSL_get_stream_write_error_code()\fR return 1
on success and 0 if the stream was terminated normally. They return \-1 on error,
for example if the stream is still healthy, was still healthy at the time of
connection closure, if called on a stream for which the respective stream part
does not exist (e.g. on a unidirectional stream), or if called on a non-QUIC
object or a \s-1QUIC\s0 connection \s-1SSL\s0 object without a default stream attached.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fISSL_stream_conclude\fR\|(3), \fISSL_stream_reset\fR\|(3), \fISSL_new_stream\fR\|(3),
\&\fISSL_accept_stream\fR\|(3), \fISSL_get_conn_close_info\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
These functions were added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.