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     ! 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), "