mirror of
https://github.com/curl/curl.git
synced 2024-12-15 06:40:09 +08:00
9307c219ad
In order for this API to fully work for libcurl itself, it now offers a CURLU_GUESS_SCHEME flag that makes it "guess" scheme based on the host name prefix just like libcurl always did. If there's no known prefix, it will guess "http://". Separately, it relaxes the check of the host name so that IDN host names can be passed in as well. Both these changes are necessary for libcurl itself to use this API. Assisted-by: Daniel Gustafsson Closes #3018
131 lines
5.2 KiB
Groff
131 lines
5.2 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.TH curl_url_set 3 "6 Aug 2018" "libcurl" "libcurl Manual"
|
|
.SH NAME
|
|
curl_url_set - set a URL part
|
|
.SH SYNOPSIS
|
|
.B #include <curl/curl.h>
|
|
|
|
CURLUcode curl_url_set(CURLU *url,
|
|
CURLUPart part,
|
|
const char *content,
|
|
unsigned int flags)
|
|
.fi
|
|
.SH DESCRIPTION
|
|
Given the \fIurl\fP handle of an already parsed URL, this function lets the
|
|
user set/update individual pieces of it.
|
|
|
|
The \fIpart\fP argument should identify the particular URL part (see list
|
|
below) to set or change, with \fIcontent\fP pointing to a zero terminated
|
|
string with the new contents for that URL part. The contents should be in the
|
|
form and encoding they'd use in a URL: URL encoded.
|
|
|
|
Setting a part to a NULL pointer will effectively remove that part's contents
|
|
from the CURLU handle.
|
|
|
|
The \fIflags\fP argument is a bitmask with independent features.
|
|
.SH PARTS
|
|
.IP CURLUPART_URL
|
|
Allows the full URL of the handle to be replaced. If the handle already is
|
|
populated with a URL, the new URL can be relative to the previous.
|
|
|
|
When successfully setting a new URL, relative or absolute, the handle contents
|
|
will be replaced with the information of the newly set URL.
|
|
|
|
Pass a pointer to a zero terminated string to the \fIurl\fP parameter. The
|
|
string must point to a correctly formatted "RFC 3986+" URL or be a NULL
|
|
pointer.
|
|
.IP CURLUPART_SCHEME
|
|
Scheme cannot be URL decoded on set.
|
|
.IP CURLUPART_USER
|
|
.IP CURLUPART_PASSWORD
|
|
.IP CURLUPART_OPTIONS
|
|
.IP CURLUPART_HOST
|
|
The host name can use IDNA. The string must then be encoded as your locale
|
|
says or UTF-8 (when winidn is used).
|
|
.IP CURLUPART_PORT
|
|
Port cannot be URL encoded on set.
|
|
.IP CURLUPART_PATH
|
|
If a path is set in the URL without a leading slash, a slash will be inserted
|
|
automatically when this URL is read from the handle.
|
|
.IP CURLUPART_QUERY
|
|
The query part will also get spaces converted to pluses when asked to URL
|
|
encode on set with the CURLU_URLENCODE bit.
|
|
|
|
If used in with \fICURLU_APPENDQUERY\fP, the provided part will be appended on
|
|
the end of the existing query - and if the previous part didn't end with an
|
|
ampersand (&), an ampersand will be inserted before the new appended part.
|
|
|
|
When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP,
|
|
the '=' symbols will not be URL encoded.
|
|
|
|
The question mark in the URL is not part of the actual query contents.
|
|
.IP CURLUPART_FRAGMENT
|
|
The hash sign in the URL is not part of the actual fragment contents.
|
|
.SH FLAGS
|
|
The flags argument is zero, one or more bits set in a bitmask.
|
|
.IP CURLU_NON_SUPPORT_SCHEME
|
|
If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme.
|
|
.IP CURLU_URLENCODE
|
|
When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for
|
|
scheme, port and URL.
|
|
|
|
When setting the path component with URL encoding enabled, the slash character
|
|
will be skipped.
|
|
|
|
The query part gets space-to-plus conversion before the URL conversion.
|
|
|
|
This URL encoding is charset unaware and will convert the input on a
|
|
byte-by-byte manner.
|
|
.IP CURLU_DEFAULT_SCHEME
|
|
If set, will make libcurl allow the URL to be set without a scheme and then
|
|
sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP
|
|
option if both are set.
|
|
.IP CURLU_GUESS_SCHEME
|
|
If set, will make libcurl allow the URL to be set without a scheme and it
|
|
instead "guesses" which scheme that was intended based on the host name. If
|
|
the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then
|
|
that scheme will be used, otherwise it picks HTTP. Conflicts with the
|
|
\fICURLU_DEFAULT_SCHEME\fP option which takes precendence if both are set.
|
|
.SH RETURN VALUE
|
|
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
|
|
fine.
|
|
|
|
If this function returns an error, no URL part is returned.
|
|
.SH EXAMPLE
|
|
.nf
|
|
CURLUcode rc;
|
|
CURLU *url = curl_url();
|
|
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
|
|
if(!rc) {
|
|
char *scheme;
|
|
/* change it to an FTP URL */
|
|
rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
|
|
}
|
|
curl_url_cleanup(url);
|
|
.fi
|
|
.SH AVAILABILITY
|
|
Added in curl 7.62.0
|
|
.SH "SEE ALSO"
|
|
.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
|
|
.BR curl_url_dup "(3), "
|