diff --git a/docs/libcurl/opts/CURLMOPT_NETWORK_CHANGED.md b/docs/libcurl/opts/CURLMOPT_NETWORK_CHANGED.md index 0ad0074353..8c8e14aa40 100644 --- a/docs/libcurl/opts/CURLMOPT_NETWORK_CHANGED.md +++ b/docs/libcurl/opts/CURLMOPT_NETWORK_CHANGED.md @@ -27,24 +27,30 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_NETWORK_CHANGED, # DESCRIPTION -Pass a long for **value**. The set number determines how the multi -handle should adapt to a change in the network. +Pass a long with a bitmask to tell libcurl how the multi +handle should react. The following values in the mask are +defined. All bits not mentioned are reserved for future +extensions. -`1`: do not reuse any existing connection in the multi handle's +This option can be set at any time and repeatedly. Any connection created or +DNS information cached afterwards is considered fresh again. The call affects +only the connection and DNS cache of the multi handle itself and not the +ones owned by SHARE handles. + + +## CURLM_NWCOPT_CLEAR_CONNS + +No longer reuse any existing connection in the multi handle's connection cache. This closes all connections that are not in use. Ongoing transfers continue on the connections they operate on. -`2`: in addition to `1` also clear the multi handle's DNS cache. +## CURLM_NWCOPT_CLEAR_DNS -This option can be set at any time and repeatedly. Any connection created or -DNS information cached afterwards is considered fresh again. - -This affects only the connection and DNS cache of the multi handle and -not the ones owned by SHARE handles. +Clear the multi handle's DNS cache. # DEFAULT -0, which means that there was no change. +0, which has no effect. # %PROTOCOLS% @@ -56,7 +62,7 @@ int main(void) CURLM *m = curl_multi_init(); /* do transfers on the multi handle */ /* do not reuse existing connections */ - curl_multi_setopt(m, CURLMOPT_NETWORK_CHANGED, 1L); + curl_multi_setopt(m, CURLMOPT_NETWORK_CHANGED, CURLM_NWCOPT_CLEAR_CONNS); } ~~~ diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 910adc04b4..02d7e3bef2 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -545,6 +545,8 @@ CURLM_BAD_SOCKET 7.15.4 CURLM_CALL_MULTI_PERFORM 7.9.6 CURLM_CALL_MULTI_SOCKET 7.15.5 CURLM_INTERNAL_ERROR 7.9.6 +CURLM_NWCOPT_CLEAR_CONNS 8.15.0 +CURLM_NWCOPT_CLEAR_DNS 8.15.0 CURLM_OK 7.9.6 CURLM_OUT_OF_MEMORY 7.9.6 CURLM_RECURSIVE_API_CALL 7.59.0 diff --git a/include/curl/multi.h b/include/curl/multi.h index e39f896940..0fbea88707 100644 --- a/include/curl/multi.h +++ b/include/curl/multi.h @@ -401,6 +401,17 @@ typedef enum { CURLMOPT_LASTENTRY /* the last unused */ } CURLMoption; +/* Definition of bits for the CURLMOPT_NETWORK_CHANGED argument: */ + +/* - CURLM_NWCOPT_CLEAR_CONNS tells libcurl to prevent further reuse + of existing connections. Connections that are idle will be closed. + Ongoing transfers will continue with the connection they have. */ +#define CURLM_NWCOPT_CLEAR_CONNS (1L<<0) + +/* - CURLM_NWCOPT_CLEAR_DNS tells libcurl to prevent further reuse + of existing connections. Connections that are idle will be closed. + Ongoing transfers will continue with the connection they have. */ +#define CURLM_NWCOPT_CLEAR_DNS (1L<<0) /* * Name: curl_multi_setopt() diff --git a/lib/multi.c b/lib/multi.c index f23fc6ec19..194cf75d40 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -3237,12 +3237,10 @@ CURLMcode curl_multi_setopt(CURLM *m, break; case CURLMOPT_NETWORK_CHANGED: { long val = va_arg(param, long); - if(val >= 2) { - /* clear DNS cache */ + if(val & CURLM_NWCOPT_CLEAR_DNS) { Curl_dnscache_clear(multi->admin); } - if(val >= 1) { - /* do not reuse existing connections */ + if(val & CURLM_NWCOPT_CLEAR_CONNS) { Curl_cpool_nw_changed(multi->admin); } break; diff --git a/tests/libtest/lib3033.c b/tests/libtest/lib3033.c index 6ef25c3de2..433b4d9f6c 100644 --- a/tests/libtest/lib3033.c +++ b/tests/libtest/lib3033.c @@ -36,7 +36,8 @@ static CURLcode t3033_req_test(CURLM *multi, CURL *easy, int still_running = 0; if(index == 1) { - curl_multi_setopt(multi, CURLMOPT_NETWORK_CHANGED, 1L); + curl_multi_setopt(multi, CURLMOPT_NETWORK_CHANGED, + CURLM_NWCOPT_CLEAR_CONNS); curl_mprintf("[1] signal network change\n"); } else {