Lines Matching +full:in +full:- +full:application
1 .\" -*- mode: troff; coding: utf-8 -*-
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
57 .IX Title "OSSL-GUIDE-QUIC-MULTI-STREAM 7ossl"
58 .TH OSSL-GUIDE-QUIC-MULTI-STREAM 7ossl 2025-09-30 3.5.4 OpenSSL
60 .\" way too many mistakes in technical documents.
64 ossl\-guide\-quic\-multi\-stream
65 \&\- OpenSSL Guide: Writing a simple multi\-stream QUIC client
69 QUIC multi-stream application. It assumes a basic understanding of QUIC and how
70 it is used in OpenSSL. See \fBossl\-guide\-quic\-introduction\fR\|(7) and
71 \&\fBossl\-guide\-quic\-client\-block\fR\|(7).
74 In a QUIC multi-stream application we separate out the concepts of a QUIC
77 negotiated and configured parameters. We use the \fBSSL\fR object for that in an
78 OpenSSL application (known as the connection \fBSSL\fR object). It is created by an
79 application calling \fBSSL_new\fR\|(3).
88 streams, e.g. if an application sends data on stream 1 first and then sends some
94 application calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) (see
98 (see \fBossl\-guide\-libraries\-introduction\fR\|(7)). In particular most OpenSSL
103 at the same time (without additional application level locking).
108 created and associated with the \fBSSL\fR object when the application calls
112 If a client application calls \fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) first then
113 (by default) the default stream will be a client-initiated bi-directional
114 stream. If a client application calls \fBSSL_read_ex\fR\|(3) or \fBSSL_read\fR\|(3)
116 stream (whether it is bi-directional or uni-directional).
121 It is recommended that new multi-stream applications should not use a default
128 creates a locally initiated stream. In order to do so you must pass the QUIC
130 bi-directional or a uni-directional stream.
135 The peer may also initiate streams. An application can use the function
137 the peer has initiated that are waiting for the application to handle. An
138 application can call \fBSSL_accept_stream\fR\|(3) to create a new \fBSSL\fR object for
140 will block until one is available if the connection object is in blocking mode
147 is not relevant if the default stream has been disabled as described in
150 Any stream may be bi-directional or uni-directional. If it is uni-directional
151 then the initiator can write to it but not read from it, and vice-versa for the
157 object if a default stream is in use) then you can send and receive data over it
169 application compared to a TLS application. In TLS it occurs when the connection
170 has been shutdown by the peer. In QUIC this only tells you that the current
173 received on it, however an application can still send data to the peer until
175 application calling \fBSSL_stream_conclude\fR\|(3). It is an error to attempt to
182 \&\fBSSL_free\fR\|(3). An application should not call \fBSSL_shutdown\fR\|(3) on it since
188 the connection via a call to \fBSSL_get0_connection\fR\|(3). Multi-threaded
190 object. Specifically, if you are handling each of your stream objects in a
195 \&\fBSSL_get_accept_stream_queue_len\fR\|(3) which are thread-safe).
203 .SH "SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE"
204 .IX Header "SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE"
206 a simple multi-stream QUIC client application which connects to a server, send
208 over QUIC is non-standard and will not be supported by real world servers. This
212 covered on the \fBossl\-guide\-quic\-client\-block\fR\|(7) page and we assume that you
214 blocking QUIC client and the multi-stream QUIC client. Although the example code
216 See \fBossl\-guide\-quic\-client\-non\-block\fR\|(7) for more information about writing a
219 The complete source code for this example multi-stream QUIC client is available
220 in the \f(CW\*(C`demos/guide\*(C'\fR directory of the OpenSSL source distribution in the file
221 \&\f(CW\*(C`quic\-multi\-stream.c\*(C'\fR. It is also available online at
222 <https://github.com/openssl/openssl/blob/master/demos/guide/quic\-multi\-stream.c>.
225 As discussed above in "THE DEFAULT STREAM" we will follow the recommendation
226 to disable the default stream for our multi-stream client. To do this we call
227 the \fBSSL_set_default_stream_mode\fR\|(3) function and pass in our connection \fBSSL\fR
244 first of these will be a bi-directional stream and the second one will be a
245 uni-directional one:
250 \& * bi\-directional, and the second will be uni\-directional.
261 Once the streams are successfully created we can start writing data to them. In
290 application would not need to do these writes sequentially or in any particular
308 In this example \fBstream1\fR is a bi-directional stream so, once we have sent the
325 \& * number of bytes that we read. The data could be non\-printable or
326 \& * have NUL characters in the middle of it. For this simple example
331 \& /* In case the response didn\*(Aqt finish with a newline we add one now */
335 In a blocking application like this one calls to \fBSSL_read_ex\fR\|(3) will either
342 function to find out more details. Since this is a blocking application this
355 \& * code we received from the SSL_read_ex() call. It must be 0 in order
356 \& * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. In
368 \& * reset \- or some failure occurred on the underlying connection.
395 Our \fBstream2\fR object that we created above was a uni-directional stream so it
396 cannot be used to receive data from the server. In this hypothetical example
399 blocking application this will wait indefinitely until the new stream has
400 arrived and is available for us to accept. In the event of an error it will
405 \& * In our hypothetical HTTP/1.0 over QUIC protocol that we are using we
407 \& * containing the data requested in our uni\-directional stream. This doesn\*(Aqt
408 \& * really make sense to do in a real protocol, but its just for
413 \& * the SSL_ACCEPT_STREAM_NO_BLOCK flag in the second argument below.
422 We can now read data from the stream in the same way that we did for \fBstream1\fR
429 we don't do that in this example because we assume that the HTTP application
443 \&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7),
444 \&\fBossl\-guide\-libssl\-introduction\fR\|(7) \fBossl\-guide\-quic\-introduction\fR\|(7),
445 \&\fBossl\-guide\-quic\-client\-block\fR\|(7)
451 this file except in compliance with the License. You can obtain a copy
452 in the file LICENSE in the source distribution or at