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