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