quickjs-tart

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

CURLOPT_POSTFIELDS.md (3932B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_POSTFIELDS
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLOPT_COPYPOSTFIELDS (3)
      9   - CURLOPT_MIMEPOST (3)
     10   - CURLOPT_POSTFIELDSIZE (3)
     11   - CURLOPT_READFUNCTION (3)
     12   - CURLOPT_UPLOAD (3)
     13 Protocol:
     14   - HTTP
     15   - MQTT
     16 Added-in: 7.1
     17 ---
     18 
     19 # NAME
     20 
     21 CURLOPT_POSTFIELDS - data to POST to server
     22 
     23 # SYNOPSIS
     24 
     25 ~~~c
     26 #include <curl/curl.h>
     27 
     28 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata);
     29 ~~~
     30 
     31 # DESCRIPTION
     32 
     33 Pass a char pointer as parameter, pointing to the data buffer to use in an
     34 HTTP POST operation or an MQTT subscribe. The data must be formatted and
     35 encoded the way you want the server to receive it. libcurl does not convert or
     36 encode it in any way. For example, a web server may assume that this data is
     37 URL encoded.
     38 
     39 The data pointed to is NOT copied by the library: as a consequence, it must be
     40 preserved by the calling application until the associated transfer finishes.
     41 This behavior can be changed (so libcurl does copy the data) by instead using
     42 the CURLOPT_COPYPOSTFIELDS(3) option.
     43 
     44 This POST is a normal **application/x-www-form-urlencoded** kind (and libcurl
     45 sets that Content-Type by default when this option is used), which is commonly
     46 used by HTML forms. Change Content-Type with CURLOPT_HTTPHEADER(3).
     47 
     48 You can use curl_easy_escape(3) to URL encode your data, if
     49 necessary. It returns a pointer to an encoded string that can be passed as
     50 *postdata*.
     51 
     52 Using CURLOPT_POSTFIELDS(3) implies setting CURLOPT_POST(3) to 1.
     53 
     54 If CURLOPT_POSTFIELDS(3) is explicitly set to NULL then libcurl gets the POST
     55 data from the read callback. To send a zero-length (empty) POST, set
     56 CURLOPT_POSTFIELDS(3) to an empty string, or set CURLOPT_POST(3) to 1 and
     57 CURLOPT_POSTFIELDSIZE(3) to 0.
     58 
     59 libcurl assumes this option points to a null-terminated string unless you also
     60 set CURLOPT_POSTFIELDSIZE(3) to specify the length of the provided data, which
     61 then is strictly required if you want to send off null bytes included in the
     62 data.
     63 
     64 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header,
     65 and libcurl adds that header automatically if the POST is either known to be
     66 larger than 1MB or if the expected size is unknown. You can disable this
     67 header with CURLOPT_HTTPHEADER(3) as usual.
     68 
     69 To make **multipart/formdata** posts, check out the
     70 CURLOPT_MIMEPOST(3) option combined with curl_mime_init(3).
     71 
     72 Using this option multiple times makes the last set pointer override the
     73 previous ones. Set it to NULL to disable its use again.
     74 
     75 # DEFAULT
     76 
     77 NULL
     78 
     79 # %PROTOCOLS%
     80 
     81 # EXAMPLE
     82 
     83 ~~~c
     84 /* send an application/x-www-form-urlencoded POST */
     85 int main(void)
     86 {
     87   CURL *curl = curl_easy_init();
     88   if(curl) {
     89     const char *data = "data to send";
     90 
     91     curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
     92 
     93     /* size of the POST data if strlen() is not good enough */
     94     curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L);
     95 
     96     /* pass in a pointer to the data - libcurl does not copy */
     97     curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
     98 
     99     curl_easy_perform(curl);
    100   }
    101 
    102   /* send an application/json POST */
    103   curl = curl_easy_init();
    104   if(curl) {
    105     const char *json = "{\"name\": \"daniel\"}";
    106     struct curl_slist *slist1 = NULL;
    107     slist1 = curl_slist_append(slist1, "Content-Type: application/json");
    108     slist1 = curl_slist_append(slist1, "Accept: application/json");
    109 
    110     /* set custom headers */
    111     curl_easy_setopt(curl, CURLOPT_HTTPHEADER, slist1);
    112 
    113     curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    114 
    115     /* pass in a pointer to the data - libcurl does not copy */
    116     curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json);
    117 
    118     curl_easy_perform(curl);
    119   }
    120 }
    121 ~~~
    122 
    123 # %AVAILABILITY%
    124 
    125 # RETURN VALUE
    126 
    127 curl_easy_setopt(3) returns a CURLcode indicating success or error.
    128 
    129 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
    130 libcurl-errors(3).