quickjs-tart

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

curl_easy_escape.md (2503B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: curl_easy_escape
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - curl_easy_unescape (3)
      9   - curl_url_set (3)
     10   - curl_url_get (3)
     11 Protocol:
     12   - All
     13 Added-in: 7.15.4
     14 ---
     15 
     16 # NAME
     17 
     18 curl_easy_escape - URL encode a string
     19 
     20 # SYNOPSIS
     21 
     22 ~~~c
     23 #include <curl/curl.h>
     24 
     25 char *curl_easy_escape(CURL *curl, const char *string, int length);
     26 ~~~
     27 
     28 # DESCRIPTION
     29 
     30 This function converts the given input *string* to a URL encoded string and
     31 returns that as a new allocated string. All input characters that are not a-z,
     32 A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version
     33 (**%NN** where **NN** is a two-digit hexadecimal number).
     34 
     35 If *length* is set to 0 (zero), curl_easy_escape(3) uses strlen() on the input
     36 *string* to find out the size. This function does not accept input strings
     37 longer than **CURL_MAX_INPUT_LENGTH** (8 MB).
     38 
     39 You must curl_free(3) the returned string when you are done with it.
     40 
     41 # ENCODING
     42 
     43 libcurl is typically not aware of, nor does it care about, character
     44 encodings. curl_easy_escape(3) encodes the data byte-by-byte into the
     45 URL encoded version without knowledge or care for what particular character
     46 encoding the application or the receiving server may assume that the data
     47 uses.
     48 
     49 The caller of curl_easy_escape(3) must make sure that the data passed in
     50 to the function is encoded correctly.
     51 
     52 # URLs
     53 
     54 URLs are by definition *URL encoded*. To create a proper URL from a set of
     55 components that may not be URL encoded already, you cannot just URL encode the
     56 entire URL string with curl_easy_escape(3), because it then also converts
     57 colons, slashes and other symbols that you probably want untouched.
     58 
     59 To create a proper URL from strings that are not already URL encoded, we
     60 recommend using libcurl's URL API: set the pieces with curl_url_set(3) and get
     61 the final correct URL with curl_url_get(3).
     62 
     63 # %PROTOCOLS%
     64 
     65 # EXAMPLE
     66 
     67 ~~~c
     68 int main(void)
     69 {
     70   CURL *curl = curl_easy_init();
     71   if(curl) {
     72     char *output = curl_easy_escape(curl, "data to convert", 15);
     73     if(output) {
     74       printf("Encoded: %s\n", output);
     75       curl_free(output);
     76     }
     77     curl_easy_cleanup(curl);
     78   }
     79 }
     80 ~~~
     81 
     82 # HISTORY
     83 
     84 Since 7.82.0, the **curl** parameter is ignored. Prior to that there was
     85 per-handle character conversion support for some old operating systems such as
     86 TPF, but it was otherwise ignored.
     87 
     88 # %AVAILABILITY%
     89 
     90 # RETURN VALUE
     91 
     92 A pointer to a null-terminated string or NULL if it failed.