libcurl-url.md (4422B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: libcurl-url 5 Section: 3 6 Source: libcurl 7 See-also: 8 - CURLOPT_URL (3) 9 - curl_url (3) 10 - curl_url_cleanup (3) 11 - curl_url_dup (3) 12 - curl_url_get (3) 13 - curl_url_set (3) 14 - curl_url_strerror (3) 15 Protocol: 16 - All 17 Added-in: 7.62.0 18 --- 19 20 # NAME 21 22 libcurl-url - URL interface overview 23 24 # DESCRIPTION 25 26 The URL interface provides functions for parsing and generating URLs. 27 28 # INCLUDE 29 30 You still only include \<curl/curl.h\> in your code. 31 32 # CREATE 33 34 Create a handle that holds URL info and resources with curl_url(3): 35 ~~~c 36 CURLU *h = curl_url(); 37 ~~~ 38 39 # CLEANUP 40 41 When done with it, clean it up with curl_url_cleanup(3) 42 ~~~c 43 curl_url_cleanup(h); 44 ~~~ 45 46 # DUPLICATE 47 48 When you need a copy of a handle, just duplicate it with curl_url_dup(3): 49 ~~~c 50 CURLU *nh = curl_url_dup(h); 51 ~~~ 52 53 # PARSING 54 55 By setting a URL to the handle with curl_url_set(3), the URL is parsed 56 and stored in the handle. If the URL is not syntactically correct it returns 57 an error instead. 58 ~~~c 59 rc = curl_url_set(h, CURLUPART_URL, 60 "https://example.com:449/foo/bar?name=moo", 0); 61 ~~~ 62 63 The zero in the fourth argument is a bitmask for changing specific features. 64 65 If successful, this stores the URL in its individual parts within the handle. 66 67 # REDIRECT 68 69 When a handle already contains info about a URL, setting a relative URL makes 70 it "redirect" to that. 71 ~~~c 72 rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0); 73 ~~~ 74 75 # GET URL 76 77 The **CURLU** handle represents a URL and you can easily extract that with 78 curl_url_get(3): 79 ~~~c 80 char *url; 81 rc = curl_url_get(h, CURLUPART_URL, &url, 0); 82 curl_free(url); 83 ~~~ 84 The zero in the fourth argument is a bitmask for changing specific features. 85 86 # GET PARTS 87 88 When a URL has been parsed or parts have been set, you can extract those 89 pieces from the handle at any time. 90 91 ~~~c 92 rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0); 93 rc = curl_url_get(h, CURLUPART_HOST, &host, 0); 94 rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0); 95 rc = curl_url_get(h, CURLUPART_PATH, &path, 0); 96 rc = curl_url_get(h, CURLUPART_PORT, &port, 0); 97 rc = curl_url_get(h, CURLUPART_QUERY, &query, 0); 98 rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0); 99 rc = curl_url_get(h, CURLUPART_USER, &user, 0); 100 rc = curl_url_get(h, CURLUPART_ZONEID, &zoneid, 0); 101 ~~~ 102 103 Extracted parts are not URL decoded unless the user also asks for it with the 104 *CURLU_URLDECODE* flag set in the fourth bitmask argument. 105 106 Remember to free the returned string with curl_free(3) when you are done 107 with it. 108 109 # SET PARTS 110 111 A user set individual URL parts, either after having parsed a full URL or 112 instead of parsing such. 113 114 ~~~c 115 rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0); 116 rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0); 117 rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0); 118 rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0); 119 rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0); 120 rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0); 121 rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0); 122 rc = curl_url_set(urlp, CURLUPART_USER, "john", 0); 123 rc = curl_url_set(urlp, CURLUPART_ZONEID, "eth0", 0); 124 ~~~ 125 126 Set parts are not URL encoded unless the user asks for it with the 127 *CURLU_URLENCODE* flag. 128 129 # CURLU_APPENDQUERY 130 131 An application can append a string to the right end of the query part with the 132 *CURLU_APPENDQUERY* flag to curl_url_set(3). 133 134 Imagine a handle that holds the URL "https://example.com/?shoes=2". An 135 application can then add the string "hat=1" to the query part like this: 136 137 ~~~c 138 rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY); 139 ~~~ 140 141 It notices the lack of an ampersand (&) separator and injects one, and the 142 handle's full URL then equals "https://example.com/?shoes=2&hat=1". 143 144 The appended string can of course also get URL encoded on add, and if asked to 145 URL encode, the encoding process skips the '=' character. For example, append 146 "candy=N&N" to what we already have, and URL encode it to deal with the 147 ampersand in the data: 148 149 ~~~c 150 rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N", 151 CURLU_APPENDQUERY | CURLU_URLENCODE); 152 ~~~ 153 154 Now the URL looks like 155 156 ~~~c 157 https://example.com/?shoes=2&hat=1&candy=N%26N 158 ~~~ 159 160 # NOTES 161 162 A URL with a literal IPv6 address can be parsed even when IPv6 support is not 163 enabled.