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