1=pod
2
3=head1 NAME
4
5SSL_get_event_timeout - determine when an SSL object next needs to have events
6handled
7
8=head1 SYNOPSIS
9
10 #include <openssl/ssl.h>
11
12 int SSL_get_event_timeout(SSL *s, struct timeval *tv, int *is_infinite);
13
14=head1 DESCRIPTION
15
16SSL_get_event_timeout() determines when the SSL object next needs to perform
17internal processing due to the passage of time.
18
19All arguments are required; I<tv> and I<is_infinite> must be non-NULL.
20
21Upon the successful return of SSL_get_event_timeout(), one of the following
22cases applies:
23
24=over 4
25
26=item
27
28The SSL object has events which need to be handled immediately; The fields of
29I<*tv> are set to 0 and I<*is_infinite> is set to 0.
30
31=item
32
33The SSL object has events which need to be handled after some amount of time
34(relative to the time at which SSL_get_event_timeout() was called). I<*tv> is
35set to the amount of time after which L<SSL_handle_events(3)> should be called
36and I<*is_infinite> is set to 0.
37
38=item
39
40There are currently no timer events which require handling in the future. The
41value of I<*tv> is unspecified and I<*is_infinite> is set to 1.
42
43=back
44
45This function is currently applicable only to DTLS and QUIC connection SSL
46objects. If it is called on any other kind of SSL object, it always outputs
47infinity. This is considered a success condition.
48
49For DTLS, this function can be used instead of the older
50L<DTLSv1_get_timeout(3)> function. Note that this function differs from
51L<DTLSv1_get_timeout(3)> in that the case where no timeout is active is
52considered a success condition.
53
54Note that the value output by a call to SSL_get_event_timeout() may change as a
55result of other calls to the SSL object.
56
57Once the timeout expires, L<SSL_handle_events(3)> should be called to handle any
58internal processing which is due; for more information, see
59L<SSL_handle_events(3)>.
60
61Note that SSL_get_event_timeout() supersedes the older L<DTLSv1_get_timeout(3)>
62function for all use cases.
63
64If the call to SSL_get_event_timeout() fails, the values of I<*tv> and
65I<*is_infinite> may still be changed and their values become unspecified.
66
67=head1 RETURN VALUES
68
69Returns 1 on success and 0 on failure.
70
71=head1 SEE ALSO
72
73L<SSL_handle_events(3)>, L<DTLSv1_get_timeout(3)>, L<ssl(7)>
74
75=head1 HISTORY
76
77The SSL_get_event_timeout() function was added in OpenSSL 3.2.
78
79=head1 COPYRIGHT
80
81Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
82
83Licensed under the Apache License 2.0 (the "License").  You may not use
84this file except in compliance with the License.  You can obtain a copy
85in the file LICENSE in the source distribution or at
86L<https://www.openssl.org/source/license.html>.
87
88=cut
89