quickjs-tart

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

CURLOPT_CUSTOMREQUEST.md (3894B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_CUSTOMREQUEST
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLINFO_EFFECTIVE_METHOD (3)
      9   - CURLOPT_HTTPHEADER (3)
     10   - CURLOPT_NOBODY (3)
     11   - CURLOPT_REQUEST_TARGET (3)
     12 Protocol:
     13   - HTTP
     14   - FTP
     15   - IMAP
     16   - POP3
     17   - SMTP
     18 Added-in: 7.1
     19 ---
     20 
     21 # NAME
     22 
     23 CURLOPT_CUSTOMREQUEST - custom request method
     24 
     25 # SYNOPSIS
     26 
     27 ~~~c
     28 #include <curl/curl.h>
     29 
     30 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *method);
     31 ~~~
     32 
     33 # DESCRIPTION
     34 
     35 Pass a pointer to a null-terminated string as parameter.
     36 
     37 When changing the request *method* by setting CURLOPT_CUSTOMREQUEST(3), you do
     38 not actually change how libcurl behaves or acts: you only change the actual
     39 string sent in the request.
     40 
     41 libcurl passes on the verbatim string in its request without any filter or
     42 other safe guards. That includes white space and control characters.
     43 
     44 The application does not have to keep the string around after setting this
     45 option.
     46 
     47 Using this option multiple times makes the last set string override the
     48 previous ones. Restore to the internal default by setting this to NULL.
     49 
     50 This option can be used to specify the request:
     51 
     52 ## HTTP
     53 
     54 Instead of GET or HEAD when performing HTTP based requests. This is
     55 particularly useful, for example, for performing an HTTP DELETE request.
     56 
     57 For example:
     58 
     59 When you tell libcurl to do a HEAD request, but then specify a GET though a
     60 custom request libcurl still acts as if it sent a HEAD. To switch to a proper
     61 HEAD use CURLOPT_NOBODY(3), to switch to a proper POST use
     62 CURLOPT_POST(3) or CURLOPT_POSTFIELDS(3) and to switch to a proper
     63 GET use CURLOPT_HTTPGET(3).
     64 
     65 Many people have wrongly used this option to replace the entire request with
     66 their own, including multiple headers and POST contents. While that might work
     67 in many cases, it might cause libcurl to send invalid requests and it could
     68 possibly confuse the remote server badly. Use CURLOPT_POST(3) and
     69 CURLOPT_POSTFIELDS(3) to set POST data. Use CURLOPT_HTTPHEADER(3) to replace
     70 or extend the set of headers sent by libcurl. Use CURLOPT_HTTP_VERSION(3) to
     71 change the HTTP version.
     72 
     73 When this option is used together with CURLOPT_FOLLOWLOCATION(3), the custom
     74 set method overrides the method libcurl could otherwise change to for the
     75 subsequent requests. You can fine-tune that decision by using the
     76 CURLFOLLOW_OBEYCODE bit to CURLOPT_FOLLOWLOCATION(3) to make redirects adhere
     77 to the redirect response code as the protocol instructs.
     78 
     79 ## FTP
     80 
     81 Instead of LIST and NLST when performing FTP directory listings.
     82 
     83 ## IMAP
     84 
     85 Instead of LIST when issuing IMAP based requests.
     86 
     87 ## POP3
     88 
     89 Instead of LIST and RETR when issuing POP3 based requests.
     90 
     91 For example:
     92 
     93 When you tell libcurl to use a custom request it behaves like a LIST or RETR
     94 command was sent where it expects data to be returned by the server. As such
     95 CURLOPT_NOBODY(3) should be used when specifying commands such as
     96 **DELE** and **NOOP** for example.
     97 
     98 ## SMTP
     99 
    100 Instead of a **HELP** or **VRFY** when issuing SMTP based requests.
    101 
    102 For example:
    103 
    104 Normally a multi line response is returned which can be used, in conjunction
    105 with CURLOPT_MAIL_RCPT(3), to specify an EXPN request. If the
    106 CURLOPT_NOBODY(3) option is specified then the request can be used to
    107 issue **NOOP** and **RSET** commands.
    108 
    109 # DEFAULT
    110 
    111 NULL
    112 
    113 # %PROTOCOLS%
    114 
    115 # EXAMPLE
    116 
    117 ~~~c
    118 int main(void)
    119 {
    120   CURL *curl = curl_easy_init();
    121   if(curl) {
    122     CURLcode res;
    123     curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
    124 
    125     /* DELETE the given path */
    126     curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE");
    127 
    128     res = curl_easy_perform(curl);
    129 
    130     curl_easy_cleanup(curl);
    131   }
    132 }
    133 ~~~
    134 
    135 # %AVAILABILITY%
    136 
    137 # RETURN VALUE
    138 
    139 curl_easy_setopt(3) returns a CURLcode indicating success or error.
    140 
    141 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
    142 libcurl-errors(3).