1=pod
2
3=head1 NAME
4
5SSL_get_stream_read_state, SSL_get_stream_write_state,
6SSL_get_stream_read_error_code, SSL_get_stream_write_error_code,
7SSL_STREAM_STATE_NONE, SSL_STREAM_STATE_OK, SSL_STREAM_STATE_WRONG_DIR,
8SSL_STREAM_STATE_FINISHED, SSL_STREAM_STATE_RESET_LOCAL,
9SSL_STREAM_STATE_RESET_REMOTE, SSL_STREAM_STATE_CONN_CLOSED - get QUIC stream
10state
11
12=head1 SYNOPSIS
13
14 #include <openssl/ssl.h>
15
16 #define SSL_STREAM_STATE_NONE
17 #define SSL_STREAM_STATE_OK
18 #define SSL_STREAM_STATE_WRONG_DIR
19 #define SSL_STREAM_STATE_FINISHED
20 #define SSL_STREAM_STATE_RESET_LOCAL
21 #define SSL_STREAM_STATE_RESET_REMOTE
22 #define SSL_STREAM_STATE_CONN_CLOSED
23
24 int SSL_get_stream_read_state(SSL *ssl);
25 int SSL_get_stream_write_state(SSL *ssl);
26
27 int SSL_get_stream_read_error_code(SSL *ssl, uint64_t *app_error_code);
28 int SSL_get_stream_write_error_code(SSL *ssl, uint64_t *app_error_code);
29
30=head1 DESCRIPTION
31
32SSL_get_stream_read_state() and SSL_get_stream_write_state() retrieve the
33overall state of the receiving and sending parts of a QUIC stream, respectively.
34
35They both return one of the following values:
36
37=over 4
38
39=item B<SSL_STREAM_STATE_NONE>
40
41This value is returned if called on a non-QUIC SSL object, or on a QUIC
42connection SSL object without a default stream attached.
43
44=item B<SSL_STREAM_STATE_OK>
45
46This value is returned on a stream which has not been concluded and remains
47healthy.
48
49=item B<SSL_STREAM_STATE_WRONG_DIR>
50
51This value is returned if SSL_get_stream_read_state() is called on a
52locally-initiated (and thus send-only) unidirectional stream, or, conversely, if
53SSL_get_stream_write_state() is called on a remotely-initiated (and thus
54receive-only) unidirectional stream.
55
56=item B<SSL_STREAM_STATE_FINISHED>
57
58For SSL_get_stream_read_state(), this value is returned when the remote peer has
59signalled the end of the receiving part of the stream. Note that there may still
60be residual data available to read via L<SSL_read(3)> when this state is
61returned.
62
63For SSL_get_stream_write_state(), this value is returned when the local
64application has concluded the stream using L<SSL_stream_conclude(3)>. Future
65L<SSL_write(3)> calls will not succeed.
66
67=item B<SSL_STREAM_STATE_RESET_LOCAL>
68
69This value is returned when the applicable stream part was reset by the local
70application.
71
72For SSL_get_stream_read_state(), this means that the receiving part of the
73stream was aborted using a locally transmitted QUIC B<STOP_SENDING> frame. It
74may or may not still be possible to obtain any residual data which remains to be
75read by calling L<SSL_read(3)>.
76
77For SSL_get_stream_write_state(), this means that the sending part of the stream
78was aborted, for example because the application called L<SSL_stream_reset(3)>,
79or because a QUIC stream SSL object with an un-concluded sending part was freed
80using L<SSL_free(3)>. Calls to L<SSL_write(3)> will fail.
81
82When this value is returned, the application error code which was signalled can
83be obtained by calling SSL_get_stream_read_error_code() or
84SSL_get_stream_write_error_code() as appropriate.
85
86=item B<SSL_STREAM_STATE_RESET_REMOTE>
87
88This value is returned when the applicable stream part was reset by the remote
89peer.
90
91For SSL_get_stream_read_state(), this means that the peer sent a QUIC
92B<RESET_STREAM> frame for the receiving part of the stream; the receiving part
93of the stream was logically aborted by the peer.
94
95For SSL_get_stream_write_state(), this means that the peer sent a QUIC
96B<STOP_SENDING> frame for the sending part of the stream; the peer has indicated
97that it does not wish to receive further data on the sending part of the stream.
98Calls to L<SSL_write(3)> will fail.
99
100When this value is returned, the application error code which was signalled can
101be obtained by calling SSL_get_stream_read_error_code() or
102SSL_get_stream_write_error_code() as appropriate.
103
104=item B<SSL_STREAM_STATE_CONN_CLOSED>
105
106The QUIC connection to which the stream belongs was closed. You can obtain
107information about the circumstances of this closure using
108L<SSL_get_conn_close_info(3)>. There may still be residual data available to
109read via L<SSL_read(3)> when this state is returned. Calls to L<SSL_write(3)>
110will fail. SSL_get_stream_read_state() will return this state if and only if
111SSL_get_stream_write_state() will also return this state.
112
113=back
114
115SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code() provide
116the application error code which was signalled during non-normal termination of
117the receiving or sending parts of a stream, respectively. On success, the
118application error code is written to I<*app_error_code>.
119
120=head1 NOTES
121
122If a QUIC connection is closed, the stream state for all streams transitions to
123B<SSL_STREAM_STATE_CONN_CLOSED>, but no application error code can be retrieved
124using SSL_get_stream_read_error_code() or SSL_get_stream_write_error_code(), as
125the QUIC connection closure process does not cause an application error code to
126be associated with each individual stream still existing at the time of
127connection closure. However, you can obtain the overall error code associated
128with the connection closure using L<SSL_get_conn_close_info(3)>.
129
130=head1 RETURN VALUES
131
132SSL_get_stream_read_state() and SSL_get_stream_write_state() return one of the
133B<SSL_STREAM_STATE> values. If called on a non-QUIC SSL object, or a QUIC
134connection SSL object without a default stream, B<SSL_STREAM_STATE_NONE> is
135returned.
136
137SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code() return 1
138on success and 0 if the stream was terminated normally. They return -1 on error,
139for example if the stream is still healthy, was still healthy at the time of
140connection closure, if called on a stream for which the respective stream part
141does not exist (e.g. on a unidirectional stream), or if called on a non-QUIC
142object or a QUIC connection SSL object without a default stream attached.
143
144=head1 SEE ALSO
145
146L<SSL_stream_conclude(3)>, L<SSL_stream_reset(3)>, L<SSL_new_stream(3)>,
147L<SSL_accept_stream(3)>, L<SSL_get_conn_close_info(3)>
148
149=head1 HISTORY
150
151These functions were added in OpenSSL 3.2.
152
153=head1 COPYRIGHT
154
155Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
156
157Licensed under the Apache License 2.0 (the "License").  You may not use
158this file except in compliance with the License.  You can obtain a copy
159in the file LICENSE in the source distribution or at
160L<https://www.openssl.org/source/license.html>.
161
162=cut
163