mirror of https://github.com/curl/curl.git synced 2024-12-09 06:30:06 +08:00

Daniel Stenberg e3fe020089

docs/libcurl: generate PROTOCOLS from meta-data

Remove the PROTOCOLS section from the source files completely and
instead generate them based on the header data in the curldown files.

It also generates TLS backend information for options marked for TLS as
protocol.

Closes #13175

2024-03-23 18:13:03 +01:00

1.8 KiB

Raw Blame History

SPDX-License-Identifier

Title

Section

Source

See-also

Protocol

curl

curl_easy_upkeep

libcurl

CURLOPT_TCP_KEEPALIVE (3)

CURLOPT_TCP_KEEPIDLE (3)

All

NAME

curl_easy_upkeep - Perform any connection upkeep checks.

SYNOPSIS

#include <curl/curl.h>

CURLcode curl_easy_upkeep(CURL *handle);

DESCRIPTION

Some protocols have "connection upkeep" mechanisms. These mechanisms usually send some traffic on existing connections in order to keep them alive; this can prevent connections from being closed due to overzealous firewalls, for example.

Currently the only protocol with a connection upkeep mechanism is HTTP/2: when the connection upkeep interval is exceeded and curl_easy_upkeep(3) is called, an HTTP/2 PING frame is sent on the connection.

This function must be explicitly called in order to perform the upkeep work. The connection upkeep interval is set with CURLOPT_UPKEEP_INTERVAL_MS(3).

EXAMPLE

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    /* Make a connection to an HTTP/2 server. */
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

    /* Set the interval to 30000ms / 30s */
    curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L);

    curl_easy_perform(curl);

    /* Perform more work here. */

    /* While the connection is being held open, curl_easy_upkeep() can be
       called. If curl_easy_upkeep() is called and the time since the last
       upkeep exceeds the interval, then an HTTP/2 PING is sent. */
    curl_easy_upkeep(curl);

    /* Perform more work here. */

    /* always cleanup */
    curl_easy_cleanup(curl);
  }
}

AVAILABILITY

Added in 7.62.0.

RETURN VALUE

On success, returns CURLE_OK.

On failure, returns the appropriate error code.

1.8 KiB Raw Blame History