quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

CURLOPT_CONNECT_TO.md (3833B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_CONNECT_TO
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLOPT_FOLLOWLOCATION (3)
      9   - CURLOPT_HTTPPROXYTUNNEL (3)
     10   - CURLOPT_RESOLVE (3)
     11   - CURLOPT_URL (3)
     12 Protocol:
     13   - All
     14 Added-in: 7.49.0
     15 ---
     16 
     17 # NAME
     18 
     19 CURLOPT_CONNECT_TO - connect to another host and port instead
     20 
     21 # SYNOPSIS
     22 
     23 ~~~c
     24 #include <curl/curl.h>
     25 
     26 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO,
     27                           struct curl_slist *connect_to);
     28 ~~~
     29 
     30 # DESCRIPTION
     31 
     32 Pass a pointer to a linked list of strings with "connect to" information to
     33 use for establishing network connections with this handle. The linked list
     34 should be a fully valid list of **struct curl_slist** structs properly filled
     35 in. Use curl_slist_append(3) to create the list and curl_slist_free_all(3) to
     36 clean up an entire list.
     37 
     38 Each single string should be written using the format
     39 HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT where HOST is the host of the
     40 request, PORT is the port of the request, CONNECT-TO-HOST is the hostname to
     41 connect to, and CONNECT-TO-PORT is the port to connect to.
     42 
     43 The first string that matches the request's host and port is used.
     44 
     45 Dotted numerical IP addresses are supported for HOST and CONNECT-TO-HOST.
     46 A numerical IPv6 address must be written within [brackets].
     47 
     48 Any of the four values may be empty. When the HOST or PORT is empty, the host
     49 or port always match (the request's host or port is ignored). When
     50 CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature is
     51 disabled for the host or port, and the request's host or port are used to
     52 establish the network connection.
     53 
     54 This option is suitable to direct the request at a specific server, e.g. at a
     55 specific cluster node in a cluster of servers.
     56 
     57 The "connect to" host and port are only used to establish the network
     58 connection. They do NOT affect the host and port that are used for TLS/SSL
     59 (e.g. SNI, certificate verification) or for the application protocols.
     60 
     61 In contrast to CURLOPT_RESOLVE(3), the option CURLOPT_CONNECT_TO(3) does not
     62 pre-populate the DNS cache and therefore it does not affect future transfers
     63 of other easy handles that have been added to the same multi handle.
     64 
     65 The "connect to" host and port are ignored if they are equal to the host and
     66 the port in the request URL, because connecting to the host and the port in
     67 the request URL is the default behavior.
     68 
     69 If an HTTP proxy is used for a request having a special "connect to" host or
     70 port, and the "connect to" host or port differs from the request's host and
     71 port, the HTTP proxy is automatically switched to tunnel mode for this
     72 specific request. This is necessary because it is not possible to connect to a
     73 specific host or port in normal (non-tunnel) mode.
     74 
     75 When this option is passed to curl_easy_setopt(3), libcurl does not copy the
     76 list so you **must** keep it around until you no longer use this *handle* for
     77 a transfer before you call curl_slist_free_all(3) on the list.
     78 
     79 Using this option multiple times makes the last set list override the previous
     80 ones. Set it to NULL to disable its use again.
     81 
     82 # DEFAULT
     83 
     84 NULL
     85 
     86 # %PROTOCOLS%
     87 
     88 # EXAMPLE
     89 
     90 ~~~c
     91 int main(void)
     92 {
     93   CURL *curl;
     94   struct curl_slist *connect_to = NULL;
     95   connect_to = curl_slist_append(NULL, "example.com::server1.example.com:");
     96 
     97   curl = curl_easy_init();
     98   if(curl) {
     99     curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to);
    100     curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    101 
    102     curl_easy_perform(curl);
    103 
    104     /* always cleanup */
    105     curl_easy_cleanup(curl);
    106   }
    107 
    108   curl_slist_free_all(connect_to);
    109 }
    110 ~~~
    111 
    112 # %AVAILABILITY%
    113 
    114 # RETURN VALUE
    115 
    116 curl_easy_setopt(3) returns a CURLcode indicating success or error.
    117 
    118 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
    119 libcurl-errors(3).