1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_easy_upkeep 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_TCP_KEEPALIVE (3) 9 - CURLOPT_TCP_KEEPIDLE (3) 10Protocol: 11 - All 12Added-in: 7.62.0 13--- 14 15# NAME 16 17curl_easy_upkeep - keep existing connections alive 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLcode curl_easy_upkeep(CURL *handle); 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 34Currently the only protocol with a connection upkeep mechanism is HTTP/2: when 35the connection upkeep interval is exceeded and curl_easy_upkeep(3) 36is called, an HTTP/2 PING frame is sent on the connection. 37 38This function must be explicitly called in order to perform the upkeep work. 39The connection upkeep interval is set with 40CURLOPT_UPKEEP_INTERVAL_MS(3). 41 42If you call this function on an easy handle that uses a shared connection cache 43then upkeep is performed on the connections in that cache, even if those 44connections were never used by the easy handle. (Added in 8.10.0) 45 46# %PROTOCOLS% 47 48# EXAMPLE 49 50~~~c 51int main(void) 52{ 53 CURL *curl = curl_easy_init(); 54 if(curl) { 55 /* Make a connection to an HTTP/2 server. */ 56 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 57 58 /* Set the interval to 30000ms / 30s */ 59 curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); 60 61 curl_easy_perform(curl); 62 63 /* Perform more work here. */ 64 65 /* While the connection is being held open, curl_easy_upkeep() can be 66 called. If curl_easy_upkeep() is called and the time since the last 67 upkeep exceeds the interval, then an HTTP/2 PING is sent. */ 68 curl_easy_upkeep(curl); 69 70 /* Perform more work here. */ 71 72 /* always cleanup */ 73 curl_easy_cleanup(curl); 74 } 75} 76~~~ 77 78# %AVAILABILITY% 79 80# RETURN VALUE 81 82On success, returns **CURLE_OK**. 83 84On failure, returns the appropriate error code. 85
