Lines Matching full:stream
57 .IX Title "OSSL-GUIDE-QUIC-MULTI-STREAM 7ossl"
58 .TH OSSL-GUIDE-QUIC-MULTI-STREAM 7ossl 2025-09-16 3.5.3 OpenSSL
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
74 In a QUIC multi-stream application we separate out the concepts of a QUIC
75 "connection" and a QUIC "stream". A connection object represents the overarching
83 normally you would have at least one). A stream is used to send and receive
84 data between the two peers. Each stream is also represented by an \fBSSL\fR
85 object. A stream is logically independent of all the other streams associated
86 with the same connection. Data sent on a stream is guaranteed to be delivered
87 in the order that it was sent within that stream. The same is not true across
88 streams, e.g. if an application sends data on stream 1 first and then sends some
89 more data on stream 2 second, then the remote peer may receive the data sent on
90 stream 2 before it receives the data sent on stream 1.
93 \&\fBSSL_connect\fR\|(3) has returned 1), stream \fBSSL\fR objects are created by the
100 use an \fBSSL\fR object representing one stream at the same time as another thread
101 is using a different \fBSSL\fR object for a different stream on the same
104 .SH "THE DEFAULT STREAM"
105 .IX Header "THE DEFAULT STREAM"
106 A connection \fBSSL\fR object may also (optionally) be associated with a stream.
107 This stream is known as the default stream. The default stream is automatically
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)
115 first then the first stream initiated by the server will be used as the default
116 stream (whether it is bi-directional or uni-directional).
118 This behaviour can be controlled via the default stream mode. See
121 It is recommended that new multi-stream applications should not use a default
122 stream at all and instead should use a separate stream \fBSSL\fR object for each
123 stream that is used. This requires calling \fBSSL_set_default_stream_mode\fR\|(3)
127 An endpoint can create a new stream by calling \fBSSL_new_stream\fR\|(3). This
128 creates a locally initiated stream. In order to do so you must pass the QUIC
130 bi-directional or a uni-directional stream.
132 The function returns a new QUIC stream \fBSSL\fR object for sending and receiving
133 data on that stream.
139 a remotely initiated stream. If the peer has not initiated any then this call
143 When using a default stream OpenSSL will prevent new streams from being
147 is not relevant if the default stream has been disabled as described in
148 "THE DEFAULT STREAM" above.
150 Any stream may be bi-directional or uni-directional. If it is uni-directional
152 peer. You can determine what type of stream an \fBSSL\fR object represents by
154 .SH "USING A STREAM TO SEND AND RECEIVE DATA"
155 .IX Header "USING A STREAM TO SEND AND RECEIVE DATA"
156 Once you have a stream \fBSSL\fR object (which includes the connection \fBSSL\fR
157 object if a default stream is in use) then you can send and receive data over it
165 when attempting to read data from a stream and the peer has indicated that the
166 stream is concluded (i.e. "FIN" has been signalled on the stream). This means
167 that the peer will send no more data on that stream. Note that the
171 stream has been concluded by the peer. It tells you nothing about the underlying
172 connection. If the peer has concluded the stream then no more data will be
174 the send side of the stream has also been concluded. This can happen by the
176 send more data on a stream after \fBSSL_stream_conclude\fR\|(3) has been called.
178 It is also possible to abandon a stream abnormally by calling
181 Once a stream object is no longer needed it should be freed via a call to
183 this is only meaningful for connection level \fBSSL\fR objects. Freeing the stream
187 Given a stream object it is possible to get the \fBSSL\fR object corresponding to
190 object. Specifically, if you are handling each of your stream objects in a
197 A stream object does not inherit all its settings and values from its parent
199 the connection as a whole will not work on a stream. For example the function
201 when called with a connection \fBSSL\fR object. When called with a stream \fBSSL\fR
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
214 blocking QUIC client and the multi-stream QUIC client. Although the example code
219 The complete source code for this example multi-stream QUIC client is available
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>.
223 .SS "Disabling the default stream"
224 .IX Subsection "Disabling the default stream"
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
232 \& * We will use multiple streams so we will disable the default stream mode.
236 \& printf("Failed to disable the default stream mode\en");
244 first of these will be a bi-directional stream and the second one will be a
262 this example we will be sending a different HTTP request on each stream. To
264 request to a stream:
267 \& int write_a_request(SSL *stream, const char *request_start,
273 \& if (!SSL_write_ex(stream, request_start, strlen(request_start), &written))
275 \& if (!SSL_write_ex(stream, hostname, strlen(hostname), &written))
277 \& if (!SSL_write_ex(stream, request_end, strlen(request_end), &written))
291 order. For example we could start two threads (one for each stream) and write
292 the requests to each stream simultaneously.
297 \& printf("Failed to write HTTP request on stream 1\en");
302 \& printf("Failed to write HTTP request on stream 2\en");
306 .SS "Reading data from a stream"
307 .IX Subsection "Reading data from a stream"
308 In this example \fBstream1\fR is a bi-directional stream so, once we have sent the
311 either that there has been a problem, or that the peer has signalled the stream
315 \& printf("Stream 1 data:\en");
317 \& * Get up to sizeof(buf) bytes of the response from stream 1 (which is a
318 \& * bidirectional stream). We keep reading until the server closes the
345 the stream is concluded and there will be no more data available to read from
346 it. Care must be taken to distinguish between an error at the stream level (i.e.
347 a stream reset) and an error at the connection level (i.e. a connection closed).
357 \& * QUIC terms this means that the peer has sent FIN on the stream to
362 \& /* Normal completion of the stream */
367 \& * Some stream fatal error occurred. This could be because of a stream
372 \& printf("Stream reset occurred\en");
373 \& /* The stream has been reset but the connection is still healthy. */
382 \& printf("Unknown stream failure\en");
393 .SS "Accepting an incoming stream"
394 .IX Subsection "Accepting an incoming stream"
395 Our \fBstream2\fR object that we created above was a uni-directional stream so it
397 we assume that the server initiates a new stream to send us back the data that
399 blocking application this will wait indefinitely until the new stream has
406 \& * assume that the server will respond with a server initiated stream
407 \& * containing the data requested in our uni\-directional stream. This doesn\*(Aqt
411 \& * We\*(Aqre using blocking mode so this will block until a stream becomes
417 \& printf("Failed to accept a new stream\en");
422 We can now read data from the stream in the same way that we did for \fBstream1\fR
433 We should not call \fBSSL_shutdown\fR\|(3) or \fBSSL_shutdown_ex\fR\|(3) on the stream