Return to libcurl-url.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl

Annotation of embedaddon/curl/docs/libcurl/libcurl-url.3, revision 1.1.1.1

1.1       misho       1: .\" **************************************************************************
                      2: .\" *                                  _   _ ____  _
                      3: .\" *  Project                     ___| | | |  _ \| |
                      4: .\" *                             / __| | | | |_) | |
                      5: .\" *                            | (__| |_| |  _ <| |___
                      6: .\" *                             \___|\___/|_| \_\_____|
                      7: .\" *
                      8: .\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
                      9: .\" *
                     10: .\" * This software is licensed as described in the file COPYING, which
                     11: .\" * you should have received as part of this distribution. The terms
                     12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
                     13: .\" *
                     14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
                     15: .\" * copies of the Software, and permit persons to whom the Software is
                     16: .\" * furnished to do so, under the terms of the COPYING file.
                     17: .\" *
                     18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
                     19: .\" * KIND, either express or implied.
                     20: .\" *
                     21: .\" **************************************************************************
                     22: .TH libcurl 3 "September 10, 2018" "libcurl 7.70.0" "libcurl url interface"
                     23: 
                     24: .SH NAME
                     25: libcurl-url \- URL interface overview
                     26: .SH DESCRIPTION
                     27: The URL interface provides a set of functions for parsing and generating URLs.
                     28: .SH INCLUDE
                     29: You still only include <curl/curl.h> in your code. Note that the URL API was
                     30: introduced in 7.62.0.
                     31: .SH CREATE
                     32: Create a handle that holds URL info and resources with \fIcurl_url(3)\fP:
                     33: 
                     34:   CURLU *h = curl_url();
                     35: .SH CLEANUP
                     36: When done with it, clean it up with \fIcurl_url_cleanup(3)\fP:
                     37: 
                     38:   curl_url_cleanup(h);
                     39: .SH DUPLICATE
                     40: When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP:
                     41: 
                     42:   CURLU *nh = curl_url_dup(h);
                     43: .SH PARSING
                     44: By "setting" a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed
                     45: and stored in the handle. If the URL is not syntactically correct it will
                     46: return an error instead.
                     47: 
                     48: .nf
                     49:   rc = curl_url_set(h, CURLUPART_URL,
                     50:                     "https://example.com:449/foo/bar?name=moo", 0);
                     51: .fi
                     52: 
                     53: The zero in the fourth argument is a bitmask for changing specific features.
                     54: 
                     55: If successful, this stores the URL in its individual parts within the handle.
                     56: .SH REDIRECT
                     57: When a handle already contains info about a URL, setting a relative URL will
                     58: make it "redirect" to adapt to it.
                     59: 
                     60:   rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
                     61: .SH "GET URL"
                     62: The `CURLU` handle represents a URL and you can easily extract that with
                     63: \fIcurl_url_get(3)\fP:
                     64: 
                     65:   char *url;
                     66:   rc = curl_url_get(h, CURLUPART_URL, &url, 0);
                     67:   curl_free(url);
                     68: 
                     69: The zero in the fourth argument is a bitmask for changing specific features.
                     70: .SH "GET PARTS"
                     71: When a URL has been parsed or parts have been set, you can extract those
                     72: pieces from the handle at any time.
                     73: 
                     74: .nf
                     75:   rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
                     76:   rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);
                     77:   rc = curl_url_get(h, CURLUPART_USER, &user, 0);
                     78:   rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
                     79:   rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
                     80:   rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
                     81:   rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
                     82:   rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);
                     83: .fi
                     84: 
                     85: Extracted parts are not URL decoded unless the user also asks for it with the
                     86: CURLU_URLDECODE flag set in the fourth bitmask argument.
                     87: 
                     88: Remember to free the returned string with \fIcurl_free(3)\fP when you're done
                     89: with it!
                     90: .SH "SET PARTS"
                     91: A user set individual URL parts, either after having parsed a full URL or
                     92: instead of parsing such.
                     93: 
                     94: .nf
                     95:   rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
                     96:   rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
                     97:   rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
                     98:   rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
                     99:   rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
                    100:   rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
                    101:   rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
                    102:   rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
                    103: .fi
                    104: 
                    105: Set parts are not URL encoded unless the user asks for it with the
                    106: `CURLU_URLENCODE` flag.
                    107: .SH "APPENDQUERY"
                    108: An application can append a string to the right end of the query part with the
                    109: `CURLU_APPENDQUERY` flag to \fIcurl_url_set(3)\fP.
                    110: 
                    111: Imagine a handle that holds the URL `https://example.com/?shoes=2`. An
                    112: application can then add the string `hat=1` to the query part like this:
                    113: 
                    114: .nf
                    115:   rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
                    116: .fi
                    117: 
                    118: It will even notice the lack of an ampersand (`&`) separator so it will inject
                    119: one too, and the handle's full URL will then equal
                    120: `https://example.com/?shoes=2&hat=1`.
                    121: 
                    122: The appended string can of course also get URL encoded on add, and if asked to
                    123: URL encode, the encoding process will skip the '=' character. For example,
                    124: append `candy=N&N` to what we already have, and URL encode it to deal with the
                    125: ampersand in the data:
                    126: 
                    127: .nf
                    128:   rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
                    129:                     CURLU_APPENDQUERY | CURLU_URLENCODE);
                    130: .fi
                    131: 
                    132: Now the URL looks like
                    133: .nf
                    134:   https://example.com/?shoes=2&hat=1&candy=N%26N`
                    135: .fi
                    136: .SH "SEE ALSO"
                    137: .BR curl_url "(3), " curl_url_cleanup "(3), " curl_url_get "(3), "
                    138: .BR curl_url_dup "(3), " curl_url_set "(3), " CURLOPT_URL "(3), "