quickjs-tart

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

CURLOPT_PREREQFUNCTION.md (3454B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_PREREQFUNCTION
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLINFO_PRIMARY_IP (3)
      9   - CURLINFO_PRIMARY_PORT (3)
     10   - CURLOPT_PREREQDATA (3)
     11 Protocol:
     12   - All
     13 Added-in: 7.80.0
     14 ---
     15 
     16 # NAME
     17 
     18 CURLOPT_PREREQFUNCTION - user callback called when a connection has been
     19 established, but before a request has been made.
     20 
     21 # SYNOPSIS
     22 
     23 ~~~c
     24 #include <curl/curl.h>
     25 
     26 /* These are the return codes for the pre-request callback. */
     27 #define CURL_PREREQFUNC_OK 0
     28 #define CURL_PREREQFUNC_ABORT 1 /* fail the entire transfer */
     29 
     30 int prereq_callback(void *clientp,
     31                     char *conn_primary_ip,
     32                     char *conn_local_ip,
     33                     int conn_primary_port,
     34                     int conn_local_port);
     35 
     36 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback);
     37 ~~~
     38 
     39 # DESCRIPTION
     40 
     41 Pass a pointer to your callback function, which should match the prototype
     42 shown above.
     43 
     44 This function gets called by libcurl after a connection has been established
     45 or a connection has been reused (including any SSL handshaking), but before any
     46 request is actually made on the connection. For example, for HTTP, this
     47 callback is called once a connection has been established to the server, but
     48 before a GET/HEAD/POST/etc request has been sent.
     49 
     50 This function may be called multiple times if redirections are enabled and are
     51 being followed (see CURLOPT_FOLLOWLOCATION(3)).
     52 
     53 The callback function must return *CURL_PREREQFUNC_OK* on success, or
     54 *CURL_PREREQFUNC_ABORT* to cause the transfer to fail with result
     55 *CURLE_ABORTED_BY_CALLBACK*.
     56 
     57 This function is passed the following arguments:
     58 
     59 ## `conn_primary_ip`
     60 
     61 A pointer to a null-terminated C string containing the primary IP of the
     62 remote server established with this connection. For FTP, this is the IP for
     63 the control connection. IPv6 addresses are represented without surrounding
     64 brackets.
     65 
     66 ## `conn_local_ip`
     67 
     68 A pointer to a null-terminated C string containing the originating IP for this
     69 connection. IPv6 addresses are represented without surrounding brackets.
     70 
     71 ## `conn_primary_port`
     72 
     73 The primary port number on the remote server established with this connection.
     74 For FTP, this is the port for the control connection. This can be a TCP or a
     75 UDP port number depending on the protocol.
     76 
     77 ## `conn_local_port`
     78 
     79 The originating port number for this connection. This can be a TCP or a UDP
     80 port number depending on the protocol.
     81 
     82 ## `clientp`
     83 
     84 The pointer you set with CURLOPT_PREREQDATA(3).
     85 
     86 # DEFAULT
     87 
     88 NULL
     89 
     90 # %PROTOCOLS%
     91 
     92 # EXAMPLE
     93 
     94 ~~~c
     95 struct priv {
     96   void *custom;
     97 };
     98 
     99 static int prereq_callback(void *clientp,
    100                            char *conn_primary_ip,
    101                            char *conn_local_ip,
    102                            int conn_primary_port,
    103                            int conn_local_port)
    104 {
    105   printf("Connection made to %s:%d\n", conn_primary_ip, conn_primary_port);
    106   return CURL_PREREQFUNC_OK;
    107 }
    108 
    109 int main(void)
    110 {
    111   struct priv prereq_data;
    112   CURL *curl = curl_easy_init();
    113   if(curl) {
    114     curl_easy_setopt(curl, CURLOPT_PREREQFUNCTION, prereq_callback);
    115     curl_easy_setopt(curl, CURLOPT_PREREQDATA, &prereq_data);
    116     curl_easy_perform(curl);
    117   }
    118 }
    119 ~~~
    120 
    121 # %AVAILABILITY%
    122 
    123 # RETURN VALUE
    124 
    125 curl_easy_setopt(3) returns a CURLcode indicating success or error.
    126 
    127 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
    128 libcurl-errors(3).