diff options
Diffstat (limited to 'docs/libcurl/libcurl-url.md')
-rw-r--r-- | docs/libcurl/libcurl-url.md | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/docs/libcurl/libcurl-url.md b/docs/libcurl/libcurl-url.md new file mode 100644 index 000000000..a2948001a --- /dev/null +++ b/docs/libcurl/libcurl-url.md @@ -0,0 +1,162 @@ +--- +c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. +SPDX-License-Identifier: curl +Title: libcurl +Section: 3 +Source: libcurl +See-also: + - CURLOPT_URL (3) + - curl_url (3) + - curl_url_cleanup (3) + - curl_url_dup (3) + - curl_url_get (3) + - curl_url_set (3) + - curl_url_strerror (3) +--- + +# NAME + +libcurl-url - URL interface overview + +# DESCRIPTION + +The URL interface provides functions for parsing and generating URLs. + +# INCLUDE + +You still only include <curl/curl.h> in your code. + +# CREATE + +Create a handle that holds URL info and resources with curl_url(3): +~~~c + CURLU *h = curl_url(); +~~~ + +# CLEANUP + +When done with it, clean it up with curl_url_cleanup(3) +~~~c + curl_url_cleanup(h); +~~~ + +# DUPLICATE + +When you need a copy of a handle, just duplicate it with curl_url_dup(3): +~~~c + CURLU *nh = curl_url_dup(h); +~~~ + +# PARSING + +By setting a URL to the handle with curl_url_set(3), the URL is parsed +and stored in the handle. If the URL is not syntactically correct it returns +an error instead. +~~~c + rc = curl_url_set(h, CURLUPART_URL, + "https://example.com:449/foo/bar?name=moo", 0); +~~~ + +The zero in the fourth argument is a bitmask for changing specific features. + +If successful, this stores the URL in its individual parts within the handle. + +# REDIRECT + +When a handle already contains info about a URL, setting a relative URL makes +it "redirect" to that. +~~~c + rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0); +~~~ + +# GET URL + +The **CURLU** handle represents a URL and you can easily extract that with +curl_url_get(3): +~~~c + char *url; + rc = curl_url_get(h, CURLUPART_URL, &url, 0); + curl_free(url); +~~~ +The zero in the fourth argument is a bitmask for changing specific features. + +# GET PARTS + +When a URL has been parsed or parts have been set, you can extract those +pieces from the handle at any time. + +~~~c + rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0); + rc = curl_url_get(h, CURLUPART_HOST, &host, 0); + rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0); + rc = curl_url_get(h, CURLUPART_PATH, &path, 0); + rc = curl_url_get(h, CURLUPART_PORT, &port, 0); + rc = curl_url_get(h, CURLUPART_QUERY, &query, 0); + rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0); + rc = curl_url_get(h, CURLUPART_USER, &user, 0); + rc = curl_url_get(h, CURLUPART_ZONEID, &zoneid, 0); +~~~ + +Extracted parts are not URL decoded unless the user also asks for it with the +*CURLU_URLDECODE* flag set in the fourth bitmask argument. + +Remember to free the returned string with curl_free(3) when you are done +with it! + +# SET PARTS + +A user set individual URL parts, either after having parsed a full URL or +instead of parsing such. + +~~~c + rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0); + rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0); + rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0); + rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0); + rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0); + rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0); + rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0); + rc = curl_url_set(urlp, CURLUPART_USER, "john", 0); + rc = curl_url_set(urlp, CURLUPART_ZONEID, "eth0", 0); +~~~ + +Set parts are not URL encoded unless the user asks for it with the +*CURLU_URLENCODE* flag. + +# CURLU_APPENDQUERY + +An application can append a string to the right end of the query part with the +*CURLU_APPENDQUERY* flag to curl_url_set(3). + +Imagine a handle that holds the URL "https://example.com/?shoes=2". An +application can then add the string "hat=1" to the query part like this: + +~~~c + rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY); +~~~ + +It notices the lack of an ampersand (&) separator and injects one, and the +handle's full URL then equals "https://example.com/?shoes=2&hat=1". + +The appended string can of course also get URL encoded on add, and if asked to +URL encode, the encoding process skips the '=' character. For example, append +"candy=N&N" to what we already have, and URL encode it to deal with the +ampersand in the data: + +~~~c + rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N", + CURLU_APPENDQUERY | CURLU_URLENCODE); +~~~ + +Now the URL looks like + +~~~c + https://example.com/?shoes=2&hat=1&candy=N%26N +~~~ + +# AVAILABILITY + +The URL API was introduced in libcurl 7.62.0. + +A URL with a literal IPv6 address can be parsed even when IPv6 support is not +enabled. |