Return to curl_easy_upkeep.3 CVS log | Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl |
1.1 ! misho 1: .\" ************************************************************************** ! 2: .\" * _ _ ____ _ ! 3: .\" * Project ___| | | | _ \| | ! 4: .\" * / __| | | | |_) | | ! 5: .\" * | (__| |_| | _ <| |___ ! 6: .\" * \___|\___/|_| \_\_____| ! 7: .\" * ! 8: .\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. ! 9: .\" * ! 10: .\" * This software is licensed as described in the file COPYING, which ! 11: .\" * you should have received as part of this distribution. The terms ! 12: .\" * are also available at https://curl.haxx.se/docs/copyright.html. ! 13: .\" * ! 14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell ! 15: .\" * copies of the Software, and permit persons to whom the Software is ! 16: .\" * furnished to do so, under the terms of the COPYING file. ! 17: .\" * ! 18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY ! 19: .\" * KIND, either express or implied. ! 20: .\" * ! 21: .\" ************************************************************************** ! 22: .\" ! 23: .TH curl_easy_upkeep 3 "31 Oct 2018" "libcurl 7.62.0" "libcurl Manual" ! 24: .SH NAME ! 25: curl_easy_upkeep - Perform any connection upkeep checks. ! 26: .SH SYNOPSIS ! 27: .B #include <curl/curl.h> ! 28: ! 29: .BI "CURLcode curl_easy_upkeep(CURL *" handle ");" ! 30: .SH DESCRIPTION ! 31: ! 32: Some protocols have "connection upkeep" mechanisms. These mechanisms usually ! 33: send some traffic on existing connections in order to keep them alive; this ! 34: can prevent connections from being closed due to overzealous firewalls, for ! 35: example. ! 36: ! 37: Currently the only protocol with a connection upkeep mechanism is HTTP/2: when ! 38: the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP ! 39: is called, an HTTP/2 PING frame is sent on the connection. ! 40: ! 41: This function must be explicitly called in order to perform the upkeep work. ! 42: The connection upkeep interval is set with ! 43: \fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP. ! 44: ! 45: .SH AVAILABILITY ! 46: Added in 7.62.0. ! 47: .SH RETURN VALUE ! 48: On success, returns \fBCURLE_OK\fP. ! 49: ! 50: On failure, returns the appropriate error code. ! 51: ! 52: .SH EXAMPLE ! 53: .nf ! 54: CURL *curl = curl_easy_init(); ! 55: if(curl) { ! 56: /* Make a connection to an HTTP/2 server. */ ! 57: curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); ! 58: ! 59: /* Set the interval to 30000ms / 30s */ ! 60: curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); ! 61: ! 62: curl_easy_perform(curl); ! 63: ! 64: /* Perform more work here. */ ! 65: ! 66: /* While the connection is being held open, curl_easy_upkeep() can be ! 67: called. If curl_easy_upkeep() is called and the time since the last ! 68: upkeep exceeds the interval, then an HTTP/2 PING is sent. */ ! 69: curl_easy_upkeep(curl); ! 70: ! 71: /* Perform more work here. */ ! 72: ! 73: /* always cleanup */ ! 74: curl_easy_cleanup(curl); ! 75: } ! 76: ! 77: .fi