1--- 2c: Copyright (C) Daniel Stenberg, <daniel.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) 10--- 11 12# NAME 13 14curl_easy_upkeep - Perform any connection upkeep checks. 15 16# SYNOPSIS 17 18~~~c 19#include <curl/curl.h> 20 21CURLcode curl_easy_upkeep(CURL *handle); 22~~~ 23 24# DESCRIPTION 25 26Some protocols have "connection upkeep" mechanisms. These mechanisms usually 27send some traffic on existing connections in order to keep them alive; this 28can prevent connections from being closed due to overzealous firewalls, for 29example. 30 31Currently the only protocol with a connection upkeep mechanism is HTTP/2: when 32the connection upkeep interval is exceeded and curl_easy_upkeep(3) 33is called, an HTTP/2 PING frame is sent on the connection. 34 35This function must be explicitly called in order to perform the upkeep work. 36The connection upkeep interval is set with 37CURLOPT_UPKEEP_INTERVAL_MS(3). 38 39# EXAMPLE 40 41~~~c 42int main(void) 43{ 44 CURL *curl = curl_easy_init(); 45 if(curl) { 46 /* Make a connection to an HTTP/2 server. */ 47 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 48 49 /* Set the interval to 30000ms / 30s */ 50 curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); 51 52 curl_easy_perform(curl); 53 54 /* Perform more work here. */ 55 56 /* While the connection is being held open, curl_easy_upkeep() can be 57 called. If curl_easy_upkeep() is called and the time since the last 58 upkeep exceeds the interval, then an HTTP/2 PING is sent. */ 59 curl_easy_upkeep(curl); 60 61 /* Perform more work here. */ 62 63 /* always cleanup */ 64 curl_easy_cleanup(curl); 65 } 66} 67~~~ 68 69# AVAILABILITY 70 71Added in 7.62.0. 72 73# RETURN VALUE 74 75On success, returns **CURLE_OK**. 76 77On failure, returns the appropriate error code. 78