1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_UPKEEP_INTERVAL_MS
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_TCP_KEEPALIVE (3)
9Protocol:
10  - All
11Added-in: 7.62.0
12---
13
14# NAME
15
16CURLOPT_UPKEEP_INTERVAL_MS - connection upkeep interval
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPKEEP_INTERVAL_MS,
24                          long upkeep_interval_ms);
25~~~
26
27# DESCRIPTION
28
29Some protocols have "connection upkeep" mechanisms. These mechanisms usually
30send some traffic on existing connections in order to keep them alive; this
31can prevent connections from being closed due to overzealous firewalls, for
32example.
33
34The user needs to explicitly call curl_easy_upkeep(3) in order to
35perform the upkeep work.
36
37Currently the only protocol with a connection upkeep mechanism is HTTP/2: when
38the connection upkeep interval is exceeded and curl_easy_upkeep(3)
39is called, an HTTP/2 PING frame is sent on the connection.
40
41# DEFAULT
42
43CURL_UPKEEP_INTERVAL_DEFAULT (currently defined as 60000L, which is 60 seconds)
44
45# %PROTOCOLS%
46
47# EXAMPLE
48
49~~~c
50int main(void)
51{
52  CURL *curl = curl_easy_init();
53  if(curl) {
54    /* Make a connection to an HTTP/2 server. */
55    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
56
57    /* Set the interval to 30000ms / 30s */
58    curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L);
59
60    curl_easy_perform(curl);
61
62    /* Perform more work here. */
63
64    /* While the connection is being held open, curl_easy_upkeep() can be
65       called. If curl_easy_upkeep() is called and the time since the last
66       upkeep exceeds the interval, then an HTTP/2 PING is sent. */
67    curl_easy_upkeep(curl);
68
69    /* Perform more work here. */
70
71    /* always cleanup */
72    curl_easy_cleanup(curl);
73  }
74}
75~~~
76
77# %AVAILABILITY%
78
79# RETURN VALUE
80
81Returns CURLE_OK
82