1=pod
2
3=head1 NAME
4
5SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired,
6SSL_net_write_desired - obtain information which can be used to determine when
7network I/O can be performed
8
9=head1 SYNOPSIS
10
11 #include <openssl/ssl.h>
12
13 int SSL_get_rpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
14 int SSL_get_wpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
15 int SSL_net_read_desired(SSL *s);
16 int SSL_net_write_desired(SSL *s);
17
18=head1 DESCRIPTION
19
20The functions SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() can be
21used to determine when an SSL object which represents a QUIC connection can
22perform useful network I/O, so that an application using a QUIC connection SSL
23object in nonblocking mode can determine when it should call SSL_handle_events().
24
25On success, these functions output poll descriptors. For more information on
26poll descriptors, see L<BIO_get_rpoll_descriptor(3)>.
27
28The functions SSL_net_read_desired() and SSL_net_write_desired() return 1 or 0
29depending on whether the SSL object is currently interested in receiving data
30from the network and/or writing data to the network respectively.
31If an SSL object is not interested in reading data from the network at the
32current time, SSL_net_read_desired() will return 0; likewise, if an SSL object is
33not interested in writing data to the network at the current time,
34SSL_net_write_desired() will return 0.
35
36The intention is that an application using QUIC in nonblocking mode can use
37these calls, in conjunction with L<SSL_get_event_timeout(3)> to wait for network
38I/O conditions which allow the SSL object to perform useful work. When such a
39condition arises, L<SSL_handle_events(3)> should be called.
40
41In particular, the expected usage is as follows:
42
43=over 4
44
45=item *
46
47SSL_handle_events() should be called whenever the timeout returned by
48SSL_get_event_timeout(3) (if any) expires
49
50=item *
51
52If the last call to SSL_net_read_desired() returned 1, SSL_handle_events() should be called
53whenever the poll descriptor output by SSL_get_rpoll_descriptor() becomes
54readable.
55
56=item *
57
58If the last call to SSL_net_write_desired() returned 1, SSL_handle_events() should be called
59whenever the poll descriptor output by SSL_get_wpoll_descriptor() becomes
60writable.
61
62=back
63
64The return values of the SSL_net_read_desired() and SSL_net_write_desired() functions
65may change in response to any call to the SSL object other than
66SSL_net_read_desired(), SSL_net_write_desired(), SSL_get_rpoll_descriptor(),
67SSL_get_wpoll_descriptor() and SSL_get_event_timeout().
68
69On non-QUIC SSL objects, calls to SSL_get_rpoll_descriptor() and
70SSL_get_wpoll_descriptor() function the same as calls to
71BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() on the respective read
72and write BIOs configured on the SSL object.
73
74On non-QUIC SSL objects, calls to SSL_net_read_desired() and
75SSL_net_write_desired() function identically to calls to SSL_want_read() and
76SSL_want_write() respectively.
77
78=head1 RETURN VALUES
79
80These functions return 1 on success and 0 on failure.
81
82=head1 SEE ALSO
83
84L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>, L<ssl(7)>
85
86=head1 HISTORY
87
88The SSL_get_rpoll_descriptor(), SSL_get_wpoll_descriptor(), SSL_net_read_desired()
89and SSL_net_write_desired() functions were added in OpenSSL 3.2.
90
91=head1 COPYRIGHT
92
93Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
94
95Licensed under the Apache License 2.0 (the "License").  You may not use
96this file except in compliance with the License.  You can obtain a copy
97in the file LICENSE in the source distribution or at
98L<https://www.openssl.org/source/license.html>.
99
100=cut
101