class KUrl |
|
Represents and parses a URL.
A prototypical URL looks like: protocol://user:password\@hostname:port/path/to/file.ext#reference KUrl handles escaping of URLs. This means that the specification of a full URL will differ from the corresponding string that would specify a local file or directory in file-operations like fopen. This is because an URL doesn't allow certain characters and escapes them. (e.g. '#'->"%23", space->"%20") (In a URL the hash-character '#' is used to specify a "reference", i.e. the position within a document). The constructor KUrl(const QString&) expects a string properly escaped, or at least non-ambiguous. If you have the absolute path you should use KUrl.fromPath(const QString&). KUrl kurl = KUrl.fromPath("/bar/#foo#"); QString url = kurl.url(); // . "file:bar/%23foo%23" If you have the URL of a local file or directory and need the absolute path, you would use path(). KUrl url( "file:bar/%23foo%23" ); ... if ( url.isLocalFile() ) QString path = url.path(); // . "/bar/#foo#" This must also be considered when you have separated directory and file strings and need to put them together. While you can simply concatenate normal path strings, you must take care if the directory-part is already an escaped URL. (This might be needed if the user specifies a relative path, and your program supplies the rest from elsewhere.) Wrong: QString dirUrl = "file:bar/"; QString fileName = "#foo#"; QString invalidURL = dirUrl + fileName; // . "file:bar/#foo#" won't behave like you would expect.Instead you should use addPath(): Right: KUrl url( "file:bar/" ); QString fileName = "#foo#"; url.addPath( fileName ); QString validURL = url.url(); // . "file:bar/%23foo%23" Also consider that some URLs contain the password, but this shouldn't be visible. Your program should use prettyUrl() every time it displays a URL, whether in the GUI or in debug output or...
KUrl url( "ftp://name:password@ftp.faraway.org/bar/%23foo%23"); QString visibleURL = url.prettyUrl(); // . "ftp://name@ftp.faraway.org/bar/%23foo%23"Note that prettyUrl() doesn't change the character escapes (like "%23"). Otherwise the URL would be invalid and the user wouldn't be able to use it in another context. |
|
|
Usual constructor, to construct from a string.
urlOrPath - An encoded URL or a path. |
|
Constructor taking a char * urlOrPath, which is an _encoded_ representation
of the URL, exactly like the usual constructor. This is useful when
then URL, in its encoded form, is strictly ascii.
urlOrPath - An encoded URL, or a path. |
|
Constructor taking a QByteArray urlOrPath, which is an _encoded_ representation
of the URL, exactly like the usual constructor. This is useful when
then URL, in its encoded form, is strictly ascii.
urlOrPath - An encoded URL, or a path. |
|
Copy constructor.
u - the KUrl to copy |
|
Converts from a QUrl.
u - the QUrl |
|
Constructor allowing relative URLs.
_baseurl - The base url. _rel_url - A relative or absolute URL. If this is an absolute URL then _baseurl will be ignored. If this is a relative URL it will be combined with _baseurl. Note that _rel_url should be encoded too, in any case. So do NOT pass a path here (use setPath or addPath instead). |
|
Adds to the current path.
Assumes that the current path is a directory. _txt is appended to the
current path. The function adds '/' if needed while concatenating.
This means it does not matter whether the current path has a trailing
'/' or not. If there is none, it becomes appended. If _txt
has a leading '/' then this one is stripped.
txt - The text to add. It is considered to be decoded. |
|
Add an additional query item.
To replace an existing query item, the item should first be
removed with removeQueryItem()
_item - Name of item to add _value - Value of item to add |
|
Add or remove a trailing slash to/from the path.
If the URL has no path, then no '/' is added anyway. And on the other side: If the path is "/", then this character won't be stripped. Reason: "ftp://weis\@host" means something completely different than "ftp://weis\@host/". So adding or stripping the '/' would really alter the URL, while "ftp://host/path" and "ftp://host/path/" mean the same directory. trailing - RemoveTrailingSlash strips any trailing '/' and AddTrailingSlash adds a trailing '/' if there is none yet |
|
Changes the directory by descending into the given directory.
It is assumed the current URL represents a directory.
If dir starts with a "/" the
current URL will be "protocol://host/dir" otherwise _dir will
be appended to the path. _dir can be ".."
This function won't strip protocols. That means that when you are in
file:dir/dir2/my.tgz#tar:/ and you do cd("..") you will
still be in file:dir/dir2/my.tgz#tar:/
_dir - the directory to change to Returns true if successful |
|
Resolves "." and ".." components in path.
Some servers seem not to like the removal of extra '/'
even though it is against the specification in RFC 2396.
options - use KeepDirSeparators if you don't want to remove consecutive occurrences of directory separator |
|
The same as equals(), just with a less obvious name.
Compares this url with u.
u - the URL to compare this one with. ignore_trailing - set to true to ignore trailing '/' characters. Returns true if both urls are the same See also operator==. This function should be used if you want to ignore trailing '/' characters. Deprecated Use equals() instead. |
|
Decode %-style encoding and convert from local encoding to unicode.
Reverse of encode_string()
str - String to decode (can be QString()). Deprecated use QUrl.fromPercentEncoding(encodedURL) instead, but note that it takes a QByteArray and not a QString. Which makes sense since everything is 7 bit (ascii) when being percent-encoded. |
|
Returns the directory of the path.
options - a set of DirectoryOption flags Returns The directory part of the current path. Everything between the last and the second last '/' is returned. For example file:hallo/torben/ would return "/hallo/torben/" while file:hallo/torben would return "hallo/". The returned string is decoded. QString() is returned when there is no path. |
|
Convert unicoded string to local encoding and use %-style
encoding for all common delimiters / non-ascii characters.
str - String to encode (can be QString()). Returns the encoded string Deprecated use QUrl.toPercentEncoding instead, but note that it returns a QByteArray and not a QString. Which makes sense since everything is 7 bit (ascii) after being percent-encoded. |
|
Convert unicoded string to local encoding and use %-style
encoding for all common delimiters / non-ascii characters
as well as the slash '/'.
str - String to encode Deprecated use QUrl.toPercentEncoding(str,"/") instead, but note that it returns a QByteArray and not a QString. Which makes sense since everything is 7 bit (ascii) after being percent-encoded. |
|
Returns the HTML reference (the part of the URL after "#") in encoded form. Returns The HTML-style reference in its original form. |
|
Returns the encoded path and the query.
trailing - add or remove a trailing '/', see adjustPath options - a set of flags from EncodedPathAndQueryOption Returns The concatenation of the encoded path , '?' and the encoded query. |
|
Compares this url with u.
u - the URL to compare this one with. options - a set of EqualsOption flags Returns true if both urls are the same See also operator==. This function should be used if you want to ignore trailing '/' characters. |
|
Returns encoding information from url, the content of the "charset" parameter. Returns An encoding suitable for QTextCodec.codecForName() or QString() if not encoding was specified. |
|
Returns the filename of the path.
options - a set of DirectoryOption flags. (StripTrailingSlashFromResult has no effect) Returns The filename of the current path. The returned string is decoded. Null if there is no file (and thus no path). |
|
Creates a KUrl from a string, using the standard conventions for mime data (drag-n-drop or copy-n-paste). Internally used by KUrl.List.fromMimeData, which is probably what you want to use instead. |
|
Creates a KUrl object from a QString representing an absolute path.
KUrl url( somePath ) does the same, but this method is more explicit
and avoids the path-or-url detection in the KUrl constructor.
text - the path Returns the new KUrl |
|
Deprecated Since KDE4 you can pass both urls and paths to the KUrl constructors. Use KUrl(text) instead. |
|
Checks whether there is a HTML reference.
Returns true if the URL has an HTML-style reference.
See also htmlRef() |
|
Test to see if this URL has a hostname included in it. Returns true if the URL has a host |
|
Test to see if this URL has a password included in it. Returns true if there is a non-empty password set |
|
Test to see if this URL has a path is included in it. Returns true if there is a path |
|
Checks whether the URL has a reference part. Returns true if the URL has a reference part. In a URL like http://www.kde.org/kdebase.tar#tar:/README it would return true, too. |
|
Checks whether the URL has any sub URLs. See split()
for examples for sub URLs.
Returns true if the file has at least one sub URL.
See also split |
|
Test to see if this URL has a user name included in it. Returns true if the URL has an non-empty user name |
|
Returns the HTML reference (the part of the URL after "#").
Returns The HTML-style reference.
See also split See also hasSubUrl See also encodedHtmlRef |
|
Checks whether the file is local. Returns true if the file is a plain local file and has no filter protocols attached to it. |
|
Checks whether the given URL is parent of this URL. For instance, ftp://host/dir/ is a parent of ftp://host/dir/subdir/subsubdir/. Returns true if this url is a parent of u (or the same URL as u) |
|
Convenience function.
Returns whether '_url' is likely to be a "relative" URL instead of an "absolute" URL. _url - URL to examine Returns true when the URL is likely to be "relative", false otherwise. |
|
Reverses split(). Only the first URL may have a reference. This reference
is considered to be HTML-like and is appended at the end of the resulting
joined URL.
_list - the list to join Returns the joined URL |
|
|
|
|
|
Returns the decoded password (corresponding to user()) included in the URL. Returns the password or QString() if it does not exist |
|
trailing - use to add or remove a trailing slash to/from the path. see adjustPath
Returns The current decoded path. This does not include the query. Can be QString() if no path is set. |
|
Return the URL as a string, which will be either the URL (as prettyUrl
would return) or, when the URL is a local file without query or ref,
the path.
Use this method, to display URLs to the user.
You can give the result of pathOrUrl back to the KUrl constructor, it accepts
both paths and urls.
Returns the new KUrl |
|
Adds URL data into the given QMimeData.
By default, populateMimeData also exports the URL as plain text, for e.g. dropping onto a text editor. But in some cases this might not be wanted, e.g. if adding other mime data which provides better plain text data. WARNING: do not call this method multiple times, use KUrl.List.populateMimeData instead. mimeData - the QMimeData instance used to drag or copy this URL metaData - KIO metadata shipped in the mime data, which is used for instance to set a correct HTTP referrer (some websites require it for downloading e.g. an image) flags - set NoTextExport to prevent setting plain/text data into mimeData In such a case, setExportAsText( false ) should be called. |
|
Returns the URL as string in human-friendly format.
Example:
http://localhost:8080/test.cgi?test=hello world&name=fred trailing - use to add or remove a trailing slash to/from the path. see adjustPath. Returns A human readable URL, with no non-necessary encodings/escaped characters. Password will not be shown. See also url() |
|
Returns the protocol for the URL (i.e., file, http, etc.), lowercased.
See also QUrl.scheme |
|
Returns the query of the URL. The query may contain the 0 character. If a query is present it always starts with a '?'. A single '?' means an empty query. An empty string means no query. Returns The encoded query, or QString() if there is none. |
|
Returns the value of a certain query item.
This does the same as QUrl.queryItemValue(), except that it decodes "+" into " " in the value. item - Item whose value we want Returns the value of the given query item name or QString() if the specified item does not exist. |
|
Returns the list of query items as a map mapping keys to values.
This does the same as QUrl.queryItems(), except that it decodes "+" into " " in the value, supports CaseInsensitiveKeys, and returns a different data type. options - any of QueryItemsOption ored together. Returns the map of query items or the empty map if the url has no query items. |
|
The reference is never decoded automatically. Returns the undecoded reference, or QString() if there is none |
|
Convenience function
Returns a relative path based on base_dir that points to path. base_dir - the base directory to derive from path - the new target directory isParent - A pointer to a boolean which, if provided, will be set to reflect whether path has base_dir is a parent dir. |
|
Convenience function
Returns a "relative URL" based on base_url that points to url. If no "relative URL" can be created, e.g. because the protocol and/or hostname differ between base_url and url an absolute URL is returned. Note that if base_url represents a directory, it should contain a trailing slash. base_url - the URL to derive from url - new URL See also adjustPath() |
|
Set the directory to dir, leaving the filename empty. |
|
This is useful for HTTP. It looks first for '?' and decodes then.
The encoded path is the concatenation of the current path and the query.
_txt - the new path and query. |
|
Adds encoding information to url by adding a "charset" parameter. If there
is already a charset parameter, it will be replaced.
encoding - the encoding to add or QString() to remove the encoding. |
|
Sets the filename of the path.
In comparison to addPath() this function does not assume that the current
path is a directory. This is only assumed if the current path ends with '/'.
Any reference is reset. _txt - The filename to be set. It is considered to be decoded. If the current path ends with '/' then _txt int just appended, otherwise all text behind the last '/' in the current path is erased and _txt is appended then. It does not matter whether _txt starts with '/' or not. |
|
Sets the HTML-style reference.
_ref - The new reference. This is considered to be not encoded in contrast to setRef(). Use QString() to remove it. See also htmlRef() |
|
Sets the password (corresponding to user()) included in the URL.
Special characters in the password will appear encoded in the URL. Note that a password can only appear in a URL string if you also set a user. pass - the password to set or QString() to remove the password See also setUser See also hasUser |
|
\reimp so that KUrl u; u.setPath(path); implies "file" protocol. |
|
Sets the protocol for the URL (i.e., file, http, etc.)
proto - the new protocol of the URL (without colon) |
|
query - This is considered to be encoded. This has a good reason:
The query may contain the 0 character.
The query should start with a '?'. If it doesn't '?' is prepended. |
|
Sets the reference part (everything after '#').
If you have an encoded fragment already (as a QByteArray), you can call setFragment directly.
fragment - the encoded reference (or QString() to remove it). |
|
Sets the user name (login, user id, ...) included in the URL.
Special characters in the user name will appear encoded in the URL. user - the name of the user or QString() to remove the user |
|
Splits nested URLs like file:home/weis/kde.tgz#gzip:/#tar:/kdebase
A URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in
http://www.kde.org and tar:/kde/README.html#ref1.
That means in turn that "#ref1" is an HTML-style reference and not a new sub URL.
Since HTML-style references mark
a certain position in a document this reference is appended to every URL.
The idea behind this is that browsers, for example, only look at the first URL while
the rest is not of interest to them.
_url - The URL that has to be split. Returns An empty list on error or the list of split URLs. See also hasSubUrl |
|
Splits nested URLs like file:home/weis/kde.tgz#gzip:/#tar:/kdebase
A URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in
http://www.kde.org and tar:/kde/README.html#ref1.
That means in turn that "#ref1" is an HTML-style reference and not a new sub URL.
Since HTML-style references mark
a certain position in a document this reference is appended to every URL.
The idea behind this is that browsers, for example, only look at the first URL while
the rest is not of interest to them.
Returns An empty list on error or the list of split URLs. _url - The URL that has to be split. See also hasSubUrl |
|
trailing - use to add or remove a trailing slash to/from the local path. see adjustPath
Returns The current local path. Can be QString() if no path is set. |
|
Returns the URL as a string, using the standard conventions for mime data (drag-n-drop or copy-n-paste). Internally used by KUrl.List.fromMimeData, which is probably what you want to use instead. |
|
This function is useful to implement the "Up" button in a file manager for example. cd() never strips a sub-protocol. That means that if you are in file:home/x.tgz#gzip:/#tar:/ and hit the up button you expect to see file:home. The algorithm tries to go up on the right-most URL. If that is not possible it strips the right most URL. It continues stripping URLs. Returns a URL that is a level higher |
|
Returns the URL as string, with all escape sequences intact,
encoded in a given charset.
This is used in particular for encoding URLs in UTF-8 before using them
in a drag and drop operation.
Please note that the string returned by url() will include
the password of the URL. If you want to show the URL to the
user, use prettyUrl().
trailing - use to add or remove a trailing slash to/from the path. See adjustPath Returns The complete URL, with all escape sequences intact, encoded in a given charset. See also prettyUrl() |
|
Returns the decoded user name (login, user id, ...) included in the URL. Returns the user name or QString() if there is no user name |
strips any trailing '/'
RemoveTrailingSlash | - | - | ||
LeaveTrailingSlash | - | - | ||
AddTrailingSlash | - | - |
if set, occurrences of consecutive directory separators (e.g. /foo//bar) are cleaned up as well. (set by default)
SimplifyDirSeparators | - 0x00 | - | ||
KeepDirSeparators | - 0x01 | - |
This tells whether a trailing '/' should be ignored.
If the flag is not set, for both file:hallo/torben/ and file:hallo/torben the fileName is "torben" and the path is "hallo"
If the flag is set, then everything behind the last '/'is considered to be the filename. So "hallo/torben" will be the path and the filename will be empty.
ObeyTrailingSlash | - 0x02 | - | ||
AppendTrailingSlash | - 0x04 | - | ||
IgnoreTrailingSlash | - 0x01 | - |
Permit empty path (default)
PermitEmptyPath | - 0x00 | - | ||
AvoidEmptyPath | - 0x01 | - |
ignore trailing '/' characters
CompareWithoutTrailingSlash | - 0x01 | - | ||
CompareWithoutFragment | - 0x02 | - |
DefaultMimeDataFlags | - 0 | - | ||
NoTextExport | - 1 | - |
Options for queryItems. Currently, only one option is defined:
CaseInsensitiveKeys - normalize query keys to lowercase.
CaseInsensitiveKeys | - 1 | - |