upkeep: add a connection upkeep API: curl_easy_conn_upkeep()

Add functionality so that protocols can do custom keepalive on their
connections, when an external API function is called.

Add docs for the new options in 7.62.0

Closes #1641

2 files changed, 16 insertions, 0 deletions

diff --git a/include/curl/curl.h b/include/curl/curl.h
index c19613072..8aac52a2a 100644
--- a/include/curl/curl.h
+++ b/include/curl/curl.h
@@ -803,6 +803,9 @@ typedef enum {
    this value, keep them in sync. */
 #define CURL_HET_DEFAULT 200L
 
+/* The default connection upkeep interval in milliseconds. */
+#define CURL_UPKEEP_INTERVAL_DEFAULT 60000L
+
 #ifndef CURL_NO_OLDIES /* define this to test if your app builds with all
                           the obsolete stuff removed! */
 
@@ -1865,6 +1868,9 @@ typedef enum {
   /* Preferred buffer size to use for uploads */
   CINIT(UPLOAD_BUFFERSIZE, LONG, 280),
 
+  /* Time in ms between connection upkeep calls for long-lived connections. */
+  CINIT(CONN_UPKEEP_INTERVAL_MS, LONG, 281),
+
   CURLOPT_LASTENTRY /* the last unused */
 } CURLoption;
 
diff --git a/include/curl/easy.h b/include/curl/easy.h
index 752c5049f..4328e9fdd 100644
--- a/include/curl/easy.h
+++ b/include/curl/easy.h
@@ -95,6 +95,16 @@ CURL_EXTERN CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen,
 CURL_EXTERN CURLcode curl_easy_send(CURL *curl, const void *buffer,
                                     size_t buflen, size_t *n);
 
+
+/*
+ * NAME curl_easy_conn_upkeep()
+ *
+ * DESCRIPTION
+ *
+ * Performs connection upkeep for the given session handle.
+ */
+CURL_EXTERN CURLcode curl_easy_conn_upkeep(CURL *curl);
+
 #ifdef  __cplusplus
 }
 #endif