KURL Class Reference
Represents and parses a URL. More...
#include <kurl.h>
Public Types | |
enum | AdjustementFlags { NoAdjustements = 0, StripFileProtocol = 1 } |
enum | URIMode { Auto, Invalid, RawURI, URL, Mailto } |
enum | QueryItemsOptions { CaseInsensitiveKeys = 1 } |
Public Member Functions | |
KURL () | |
~KURL () | |
KURL (const QString &url, int encoding_hint=0) | |
KURL (const char *url, int encoding_hint=0) | |
KURL (const QCString &url, int encoding_hint=0) | |
KURL (const KURL &u) | |
KURL (const QUrl &u) | |
KURL (const KURL &_baseurl, const QString &_rel_url, int encoding_hint=0) | |
QString | protocol () const |
void | setProtocol (const QString &_txt) |
int | uriMode () const |
QString | user () const |
void | setUser (const QString &_txt) |
bool | hasUser () const |
QString | pass () const |
void | setPass (const QString &_txt) |
bool | hasPass () const |
QString | host () const |
void | setHost (const QString &_txt) |
bool | hasHost () const |
unsigned short int | port () const |
void | setPort (unsigned short int _p) |
QString | path () const |
QString | path (int _trailing) const |
void | setPath (const QString &path) |
bool | hasPath () const |
void | cleanPath (bool cleanDirSeparator=true) |
void | adjustPath (int _trailing) |
void | setEncodedPathAndQuery (const QString &_txt, int encoding_hint=0) |
void | setEncodedPath (const QString &_txt, int encoding_hint=0) |
QString | encodedPathAndQuery (int _trailing=0, bool _no_empty_path=false, int encoding_hint=0) const |
void | setQuery (const QString &_txt, int encoding_hint=0) |
QString | query () const |
QString | ref () const |
void | setRef (const QString &_txt) |
bool | hasRef () const |
QString | htmlRef () const |
QString | encodedHtmlRef () const |
void | setHTMLRef (const QString &_ref) |
bool | hasHTMLRef () const |
bool | isValid () const |
KDE_DEPRECATED bool | isMalformed () const |
bool | isLocalFile () const |
void | setFileEncoding (const QString &encoding) |
QString | fileEncoding () const |
bool | hasSubURL () const |
void | addPath (const QString &txt) |
QString | queryItem (const QString &item) const |
QString | queryItem (const QString &item, int encoding_hint) const |
QMap< QString, QString > | queryItems (int options=0) const |
QMap< QString, QString > | queryItems (int options, int encoding_hint) const |
void | addQueryItem (const QString &_item, const QString &_value, int encoding_hint=0) |
void | removeQueryItem (const QString &_item) |
void | setFileName (const QString &_txt) |
QString | fileName (bool _ignore_trailing_slash_in_path=true) const |
QString | directory (bool _strip_trailing_slash_from_result=true, bool _ignore_trailing_slash_in_path=true) const |
void | setDirectory (const QString &dir) |
bool | cd (const QString &_dir) |
QString | url (int _trailing=0, int encoding_hint=0) const |
QString | prettyURL (int _trailing=0) const |
QString | prettyURL (int _trailing, AdjustementFlags _flags) const |
QString | pathOrURL () const |
QString | htmlURL () const |
bool | isEmpty () const |
KURL | upURL () const |
bool | operator< (const KURL &_u) const |
KURL & | operator= (const KURL &_u) |
KURL & | operator= (const QString &_url) |
KURL & | operator= (const char *_url) |
KURL & | operator= (const QUrl &u) |
bool | operator== (const KURL &_u) const |
bool | operator== (const QString &_u) const |
bool | operator!= (const KURL &_u) const |
bool | operator!= (const QString &_u) const |
bool | cmp (const KURL &u, bool ignore_trailing=false) const KDE_DEPRECATED |
bool | equals (const KURL &u, bool ignore_trailing=false) const |
bool | isParentOf (const KURL &u) const |
QString | filename (bool _ignore_trailing_slash_in_path=true) const |
Static Public Member Functions | |
List | split (const QString &_url) |
List | split (const KURL &_url) |
KURL | join (const List &_list) |
KURL | fromPathOrURL (const QString &text) |
QString | encode_string (const QString &str, int encoding_hint=0) |
QString | encode_string_no_slash (const QString &str, int encoding_hint=0) |
QString | decode_string (const QString &str, int encoding_hint=0) |
bool | isRelativeURL (const QString &_url) |
QString | relativeURL (const KURL &base_url, const KURL &url, int encoding_hint=0) |
QString | relativePath (const QString &base_dir, const QString &path, bool *isParent=0) |
URIMode | uriModeForProtocol (const QString &protocol) |
Protected Member Functions | |
void | reset () |
void | parseURL (const QString &_url, int encoding_hint=0) |
void | parseRawURI (const QString &_url, int encoding_hint=0) |
void | parseMailto (const QString &_url, int encoding_hint=0) |
void | parse (const QString &_url, int encoding_hint=0) |
Friends | |
KDECORE_EXPORT QDataStream & | operator<< (QDataStream &s, const KURL &a) |
KDECORE_EXPORT QDataStream & | operator>> (QDataStream &s, KURL &a) |
Related Functions | |
(Note that these are not member functions.) | |
KDECORE_EXPORT bool | urlcmp (const QString &_url1, const QString &_url2) |
KDECORE_EXPORT bool | urlcmp (const QString &_url1, const QString &_url2, bool _ignore_trailing, bool _ignore_ref) |
Detailed Description
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. For instance a local file or directory "/bar/#foo#" would have the URL file:///bar/%23foo%23. If you have the absolute path and need the URL-escaping you should create KURL via the default-constructor and then call setPath(const QString&).
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#"
The other way round: if the user can enter a string, that can be either a path or a URL, then you need to use KURL::fromPathOrURL() to build a KURL.
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.
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"
KURL has some restrictions regarding the path encoding. KURL works internally with the decoded path and and encoded query. For example,
http://localhost/cgi-bin/test%20me.pl?cmd=Hello%20you
- Author:
- Torben Weis <weis@kde.org>
Definition at line 122 of file kurl.h.
Member Enumeration Documentation
|
Defines the type of URI we are processing.
Definition at line 134 of file kurl.h. Referenced by uriModeForProtocol(). |
|
Options for queryItems. Currently, only one option is defined:
|
Constructor & Destructor Documentation
|
Constructs an empty URL.
Definition at line 447 of file kurl.cpp. Referenced by fromPathOrURL(), join(), KURL::List::List(), split(), and upURL(). |
|
Destructs the KURL object.
|
|
Usual constructor, to construct from a string.
|
|
Constructor taking a char * This is useful when then URL, in its encoded form, is strictly ascii.
|
|
Constructor taking a QCString This is useful when then URL, in its encoded form, is strictly ascii.
|
|
Copy constructor.
|
|
Converts from a QUrl.
|
|
Constructor allowing relative URLs.
Definition at line 520 of file kurl.cpp. References cleanPath(), hasSubURL(), isRelativeURL(), join(), m_strHost, m_strPass, m_strProtocol, m_strUser, ref(), split(), and url(). |
Member Function Documentation
|
Returns the protocol for the URL (i.e., file, http, etc.).
Definition at line 271 of file kurl.h. Referenced by KApplication::allowURLAction(), KApplication::authorizeURLAction(), relativeURL(), KGlobalSettings::showFilePreview(), and KURLDrag::urlToString(). |
|
Sets the protocol for the URL (i.e., file, http, etc.).
Definition at line 1925 of file kurl.cpp. References uriModeForProtocol(). Referenced by KApplication::invokeMailer(). |
|
Returns the URI processing mode for the URL.
|
|
Returns the decoded user name (login, user id, ...) included in the URL.
Definition at line 289 of file kurl.h. Referenced by relativeURL(). |
|
Sets the user name (login, user id, ...) included in the URL. Special characters in the user name will appear encoded in the URL.
|
|
Test to see if this URL has a user name included in it.
Definition at line 301 of file kurl.h. Referenced by prettyURL(), relativeURL(), and url(). |
|
Returns the decoded password (corresponding to user()) included in the URL.
Definition at line 307 of file kurl.h. Referenced by relativeURL(). |
|
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.
|
|
Test to see if this URL has a password included in it.
Definition at line 323 of file kurl.h. Referenced by relativeURL(), and url(). |
|
Returns the decoded hostname included in the URL.
Definition at line 329 of file kurl.h. Referenced by KApplication::allowURLAction(), and relativeURL(). |
|
Sets the hostname included in the URL. Special characters in the hostname will appear encoded in the URL.
Definition at line 1945 of file kurl.cpp. References URL. |
|
Test to see if this URL has a hostname included in it.
Definition at line 342 of file kurl.h. Referenced by prettyURL(), and url(). |
|
Returns the port number included in the URL.
Definition at line 349 of file kurl.h. Referenced by relativeURL(). |
|
Sets the port number included in the URL.
|
|
Returns the current decoded path. This does not include the query.
Definition at line 361 of file kurl.h. Referenced by KApplication::allowURLAction(), KApplication::authorizeURLAction(), cd(), encodedPathAndQuery(), equals(), KApplication::invokeMailer(), isParentOf(), path(), pathOrURL(), relativeURL(), upURL(), and KURLDrag::urlToString(). |
|
Definition at line 1353 of file kurl.cpp. References path(). |
|
Sets the path of the URL. The query is not changed by this function.
Definition at line 1972 of file kurl.cpp. References isEmpty(). Referenced by KApplication::authorizeURLAction(), cd(), fromPathOrURL(), KApplication::invokeMailer(), KCmdLineArgs::makeURL(), KConfigINIBackEnd::parseConfigFiles(), KDesktopFile::readURL(), setDirectory(), setFileName(), and KConfigINIBackEnd::sync(). |
|
Test to see if this URL has a path is included in it.
|
|
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.
Definition at line 1250 of file kurl.cpp. Referenced by KURL(), KCmdLineArgs::makeURL(), and setFileName(). |
|
Add or remove a trailing slash to/from the path.
|
|
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.
Definition at line 1338 of file kurl.cpp. References setEncodedPath(). |
|
Sets the (already encoded) path.
Definition at line 1324 of file kurl.cpp. Referenced by setEncodedPathAndQuery(), and setFileName(). |
|
Returns the encoded path and the query.
Definition at line 1296 of file kurl.cpp. References path(). Referenced by url(). |
|
Definition at line 1994 of file kurl.cpp. Referenced by KApplication::invokeMailer(). |
|
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.
Definition at line 2041 of file kurl.cpp. Referenced by fileEncoding(), KApplication::invokeMailer(), relativeURL(), setFileEncoding(), and upURL(). |
|
The reference is never decoded automatically.
Definition at line 477 of file kurl.h. Referenced by encodedHtmlRef(), htmlRef(), KURL(), and relativeURL(). |
|
Sets the reference part (everything after '#').
|
|
Checks whether the URL has a reference part.
Definition at line 491 of file kurl.h. Referenced by hasHTMLRef(), prettyURL(), relativeURL(), and url(). |
|
Returns the HTML reference (the part of the URL after "#").
Definition at line 1876 of file kurl.cpp. References hasSubURL(), ref(), and split(). |
|
Returns the HTML reference (the part of the URL after "#") in encoded form.
Definition at line 1887 of file kurl.cpp. References hasSubURL(), ref(), and split(). |
|
Sets the HTML-style reference.
Definition at line 1898 of file kurl.cpp. References hasSubURL(), join(), and split(). Referenced by cd(). |
|
Checks whether there is a HTML reference.
Definition at line 1913 of file kurl.cpp. References hasRef(), hasSubURL(), and split(). |
|
Checks whether the URL is well formed.
Definition at line 530 of file kurl.h. Referenced by KURLDrag::decode(), equals(), isMalformed(), and isParentOf(). |
|
Definition at line 534 of file kurl.h. References isValid(). |
|
Checks whether the file is local.
Definition at line 1358 of file kurl.cpp. References hasSubURL(). Referenced by fileEncoding(), pathOrURL(), setFileEncoding(), and KURLDrag::urlToString(). |
|
Adds encoding information to url by adding a "charset" parameter. If there is already a charset parameter, it will be replaced.
Definition at line 1377 of file kurl.cpp. References decode_string(), encode_string(), isLocalFile(), and query(). |
|
Returns encoding information from url, the content of the "charset" parameter.
Definition at line 1406 of file kurl.cpp. References decode_string(), isLocalFile(), and query(). |
|
Checks whether the URL has any sub URLs. See split() for examples for sub URLs.
Definition at line 1431 of file kurl.cpp. Referenced by addPath(), cd(), encodedHtmlRef(), fileName(), hasHTMLRef(), htmlRef(), isLocalFile(), KURL(), setHTMLRef(), split(), and upURL(). |
|
Adds to the current path.
Assumes that the current path is a directory.
Definition at line 1723 of file kurl.cpp. References hasSubURL(), join(), and split(). |
|
call the function below with encoding_hint = 0 (will be merged for KDE4)
|
|
Returns the value of a certain query item.
Definition at line 2157 of file kurl.cpp. References decode_string(). |
|
Returns the list of query items as a map mapping keys to values.
Definition at line 2121 of file kurl.cpp. References decode_string(). |
|
Add an additional query item. To replace an existing query item, the item should first be removed with removeQueryItem()
|
|
Remove an item from the query.
|
|
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.
Definition at line 1211 of file kurl.cpp. References cleanPath(), encode_string(), setEncodedPath(), and setPath(). |
|
Returns the filename of the path.
Definition at line 1664 of file kurl.cpp. References hasSubURL(), and split(). Referenced by filename(). |
|
Returns the directory of the path.
Definition at line 1756 of file kurl.cpp. Referenced by KConfigINIBackEnd::parseConfigFiles(), relativeURL(), and KConfigINIBackEnd::sync(). |
|
Set the directory to
Definition at line 1986 of file kurl.cpp. References setPath(). |
|
Changes the directory by descending into the given directory.
It is assumed the current URL represents a directory. If
Definition at line 1790 of file kurl.cpp. References hasSubURL(), join(), path(), setHTMLRef(), setPath(), and split(). Referenced by upURL(). |
|
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().
Definition at line 1454 of file kurl.cpp. References encodedPathAndQuery(), hasHost(), hasPass(), hasRef(), hasUser(), and URL. Referenced by KApplication::invokeMailer(), join(), KURL(), KDesktopFile::readURL(), relativeURL(), split(), and KURLDrag::urlToString(). |
|
Returns the URL as string in human-friendly format. Example: http://localhost:8080/test.cgi?test=hello world&name=fred
Definition at line 1514 of file kurl.cpp. References hasHost(), hasRef(), and hasUser(). Referenced by htmlURL(), kdbgstream::operator<<(), pathOrURL(), and prettyURL(). |
|
Returns the URL as string in human-friendly format. Example: http://localhost:8080/test.cgi?test=hello world&name=fred
Definition at line 1581 of file kurl.cpp. References prettyURL(). |
|
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, together with its opposite, fromPathOrURL(), to display and even let the user edit URLs.
Definition at line 1593 of file kurl.cpp. References isLocalFile(), path(), and prettyURL(). |
|
Returns the URL as string, escaped for HTML.
Definition at line 1602 of file kurl.cpp. References prettyURL(). |
|
Test to see if the KURL is empty.
Definition at line 625 of file kurl.cpp. Referenced by KApplication::authorizeURLAction(), and setPath(). |
|
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.
Definition at line 1842 of file kurl.cpp. References _setQuery(), cd(), hasSubURL(), join(), KURL(), path(), query(), and split(). |
|
The same as equals(), just with a less obvious name.
Compares this url with
Definition at line 1147 of file kurl.cpp. References equals(). |
|
Compares this url with
Definition at line 1152 of file kurl.cpp. References isValid(), m_iPort, m_strHost, m_strPass, m_strProtocol, m_strQuery_encoded, m_strRef_encoded, m_strUser, and path(). Referenced by cmp(). |
|
Checks whether the given URL is parent of this URL. For instance, ftp://host/dir/ is a parent of ftp://host/dir/subdir/subsubdir/.
Definition at line 1179 of file kurl.cpp. References isValid(), m_iPort, m_strHost, m_strPass, m_strProtocol, m_strQuery_encoded, m_strRef_encoded, m_strUser, and path(). |
|
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.
Definition at line 1639 of file kurl.cpp. References KURL(). Referenced by addPath(), cd(), encodedHtmlRef(), fileName(), hasHTMLRef(), htmlRef(), KURL(), setHTMLRef(), upURL(), and urlcmp(). |
|
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.
Definition at line 1607 of file kurl.cpp. References hasSubURL(), KURL(), m_strRef_encoded, and url(). |
|
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.
Definition at line 1644 of file kurl.cpp. References KURL(), m_strRef_encoded, and url(). Referenced by addPath(), cd(), KURL(), setHTMLRef(), and upURL(). |
|
Creates a KURL object from a QString representing either an absolute path or a real URL. Use this method instead of Otherwise some characters (e.g. the '#') won't be encoded properly.
|
|
Convenience function. Convert unicoded string to local encoding and use -style encoding for all common delimiters / non-ascii characters.
Definition at line 2053 of file kurl.cpp. Referenced by setFileEncoding(), and setFileName(). |
|
Convenience function. Convert unicoded string to local encoding and use -style encoding for all common delimiters / non-ascii characters as well as the slash '/'.
|
|
Convenience function. Decode -style encoding and convert from local encoding to unicode. Reverse of encode_string()
Definition at line 2048 of file kurl.cpp. Referenced by fileEncoding(), KApplication::invokeMailer(), queryItem(), queryItems(), and setFileEncoding(). |
|
Convenience function. Returns whether '_url' is likely to be a "relative" URL instead of an "absolute" URL.
Definition at line 395 of file kurl.cpp. Referenced by KURL(), and KCmdLineArgs::makeURL(). |
|
Convenience function.
Returns a "relative URL" based on
If no "relative URL" can be created, e.g. because the protocol and/or hostname differ between
Definition at line 2281 of file kurl.cpp. References directory(), hasPass(), hasRef(), hasUser(), host(), pass(), path(), port(), protocol(), query(), ref(), url(), and user(). |
|
Convenience function.
Returns a relative path based on
|
|
Determine which URI mode is suitable for processing URIs of a given protocol.
Definition at line 2319 of file kurl.cpp. References URIMode, and KProtocolInfo::uriParseMode(). Referenced by setProtocol(). |
|
Definition at line 982 of file kurl.h. References fileName(). |
Friends And Related Function Documentation
|
Compares URLs. They are parsed, split and compared. Two malformed URLs with the same string representation are nevertheless considered to be unequal. That means no malformed URL equals anything else. Definition at line 2063 of file kurl.cpp. References split(). |
|
Compares URLs. They are parsed, split and compared. Two malformed URLs with the same string representation are nevertheless considered to be unequal. That means no malformed URL equals anything else.
Definition at line 2082 of file kurl.cpp. References split(). |
The documentation for this class was generated from the following files: