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 | 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 | |
QDataStream & | operator<< (QDataStream &s, const KURL &a) |
QDataStream & | operator>> (QDataStream &s, KURL &a) |
Related Functions | |
(Note that these are not member functions.) | |
bool | urlcmp (const QString &_url1, const QString &_url2) |
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().
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:
Instead you should use addPath(): Right:
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...
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.
KURL has some restrictions regarding the path encoding. KURL works internally with the decoded path and and encoded query. For example,
would result in a decoded path "/cgi-bin/test me.pl" and in the encoded query "?cmd=Hello%20you". Since path is internally always encoded you may not use "%00" in the path, although this is OK for the query.http://localhost/cgi-bin/test%20me.pl?cmd=Hello%20you
- Author:
- Torben Weis <weis@kde.org>
Definition at line 118 of file kurl.h.
Member Enumeration Documentation
|
Defines the type of URI we are processing.
|
|
Options for queryItems. Currently, only one option is defined:
|
Constructor & Destructor Documentation
|
Constructs an empty URL.
Definition at line 426 of file kurl.cpp. Referenced by KURL::List::List(), and split(). |
|
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 497 of file kurl.cpp. References QValueList< KURL >::append(), cleanPath(), QString::find(), QString::findRev(), hasSubURL(), QString::isEmpty(), QString::isNull(), isRelativeURL(), join(), QValueList< KURL >::last(), QString::length(), m_strHost, m_strPass, m_strProtocol, m_strUser, QValueList< KURL >::remove(), setHTMLRef(), split(), QString::truncate(), and url(). |
Member Function Documentation
|
Returns the protocol for the URL (i.e., file, http, etc.).
Definition at line 267 of file kurl.h. Referenced by KApplication::allowURLAction(), KApplication::authorizeURLAction(), and KGlobalSettings::showFilePreview(). |
|
Sets the protocol for the URL (i.e., file, http, etc.).
|
|
Returns the URI processing mode for the URL.
|
|
Returns the decoded user name (login, user id, ...) included in the URL.
|
|
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 297 of file kurl.h. References QString::isEmpty(). Referenced by prettyURL(), and url(). |
|
Returns the decoded password (corresponding to user()) included in the URL.
|
|
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 319 of file kurl.h. References QString::isEmpty(). Referenced by url(). |
|
Returns the decoded hostname included in the URL.
Definition at line 325 of file kurl.h. Referenced by KApplication::allowURLAction(). |
|
Sets the hostname included in the URL. Special characters in the hostname will appear encoded in the URL.
|
|
Test to see if this URL has a hostname included in it.
Definition at line 338 of file kurl.h. References QString::isEmpty(). Referenced by url(). |
|
Returns the port number included in the URL.
|
|
Sets the port number included in the URL.
|
|
Returns the current decoded path. This does not include the query.
Definition at line 357 of file kurl.h. Referenced by KApplication::allowURLAction(), KApplication::authorizeURLAction(), encodedPathAndQuery(), equals(), KApplication::invokeMailer(), isParentOf(), and path(). |
|
Definition at line 1304 of file kurl.cpp. References path(). |
|
Sets the path of the URL. The query is not changed by this function.
Definition at line 1906 of file kurl.cpp. References QString::length(). Referenced by KApplication::authorizeURLAction(), KCmdLineArgs::makeURL(), KConfigINIBackEnd::parseConfigFiles(), KDesktopFile::readURL(), setFileName(), and KConfigINIBackEnd::sync(). |
|
Test to see if this URL has a path is included in it.
Definition at line 388 of file kurl.h. References QString::isEmpty(). |
|
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 1208 of file kurl.cpp. References URL. Referenced by KURL(), KCmdLineArgs::makeURL(), and setFileName(). |
|
Add or remove a trailing slash to/from the path.
Definition at line 1244 of file kurl.cpp. References QString::isEmpty(). |
|
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 1289 of file kurl.cpp. References QString::find(), QString::left(), QString::length(), QString::right(), and setEncodedPath(). |
|
Sets the (already encoded) path.
Definition at line 1275 of file kurl.cpp. Referenced by setEncodedPathAndQuery(), and setFileName(). |
|
Returns the encoded path and the query.
Definition at line 1254 of file kurl.cpp. References QString::isEmpty(), QString::isNull(), and path(). |
|
Definition at line 1928 of file kurl.cpp. References QString::mid(). |
|
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 1975 of file kurl.cpp. Referenced by fileEncoding(), KApplication::invokeMailer(), and setFileEncoding(). |
|
The reference is never decoded automatically.
|
|
Sets the reference part (everything after '#').
|
|
Checks whether the URL has a reference part.
Definition at line 487 of file kurl.h. References QString::isNull(). |
|
Returns the HTML reference (the part of the URL after "#").
|
|
Returns the HTML reference (the part of the URL after "#") in encoded form.
|
|
Sets the HTML-style reference.
Definition at line 1832 of file kurl.cpp. Referenced by KURL(). |
|
Checks whether there is a HTML reference.
Definition at line 1847 of file kurl.cpp. References Auto, QString::isEmpty(), QString::lower(), and URL. |
|
Checks whether the URL is well formed.
Definition at line 526 of file kurl.h. Referenced by KURLDrag::decode(), equals(), isMalformed(), and isParentOf(). |
|
Definition at line 530 of file kurl.h. References isValid(). |
|
Checks whether the file is local.
Definition at line 1309 of file kurl.cpp. References hasSubURL(), and QString::isEmpty(). Referenced by fileEncoding(), 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 1328 of file kurl.cpp. References decode_string(), encode_string(), QString::isEmpty(), isLocalFile(), QStringList::join(), QString::mid(), query(), QStringList::split(), and QString::startsWith(). |
|
Returns encoding information from url, the content of the "charset" parameter.
Definition at line 1357 of file kurl.cpp. References decode_string(), QString::isEmpty(), isLocalFile(), QString::mid(), query(), QStringList::split(), and QString::startsWith(). |
|
Checks whether the URL has any sub URLs. See split() for examples for sub URLs.
Definition at line 1382 of file kurl.cpp. References QString::isEmpty(), and QString::startsWith(). Referenced by isLocalFile(), and KURL(). |
|
Adds to the current path.
Assumes that the current path is a directory.
|
|
call the function below with encoding_hint = 0 (will be merged for KDE4)
Definition at line 2086 of file kurl.cpp. References QString::length(). Referenced by queryItems(). |
|
Returns the value of a certain query item.
|
|
Returns the list of query items as a map mapping keys to values.
Definition at line 2055 of file kurl.cpp. References queryItem(). |
|
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 1169 of file kurl.cpp. References cleanPath(), encode_string(), QString::findRev(), QString::isEmpty(), QString::mid(), QString::right(), setEncodedPath(), setPath(), and QString::truncate(). |
|
Returns the filename of the path.
|
|
Returns the directory of the path.
Definition at line 1690 of file kurl.cpp. Referenced by KConfigINIBackEnd::parseConfigFiles(), and KConfigINIBackEnd::sync(). |
|
Set the directory to
Definition at line 1920 of file kurl.cpp. References QString::latin1(). |
|
Changes the directory by descending into the given directory.
It is assumed the current URL represents a directory. If
|
|
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 1405 of file kurl.cpp. References hasHost(), hasPass(), hasUser(), and QString::isEmpty(). Referenced by KURL(), KDesktopFile::readURL(), and KURLDrag::urlToString(). |
|
Returns the URL as string in human-friendly format. Example:
Definition at line 1465 of file kurl.cpp. References hasUser(). Referenced by kdbgstream::operator<<(). |
|
Returns the URL as string, escaped for HTML. Example:
|
|
Returns the URL as string, escaped for HTML.
|
|
Test to see if the KURL is empty.
Definition at line 599 of file kurl.cpp. References QString::isEmpty(). Referenced by KApplication::authorizeURLAction(). |
|
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.
|
|
The same as equals(), just with a less obvious name.
Compares this url with
Definition at line 1105 of file kurl.cpp. References equals(). |
|
Compares this url with
Definition at line 1110 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 1137 of file kurl.cpp. References QString::isEmpty(), isValid(), QString::length(), m_iPort, m_strHost, m_strPass, m_strProtocol, m_strQuery_encoded, m_strRef_encoded, m_strUser, path(), and QString::startsWith(). |
|
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.
|
|
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.
|
|
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 1574 of file kurl.cpp. Referenced by KURL(). |
|
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 1987 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 1982 of file kurl.cpp. Referenced by fileEncoding(), KApplication::invokeMailer(), and setFileEncoding(). |
|
Convenience function. Returns whether '_url' is likely to be a "relative" URL instead of an "absolute" URL.
Definition at line 374 of file kurl.cpp. References QChar::latin1(), QString::length(), and QString::unicode(). 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
|
|
Convenience function.
Returns a relative path based on
|
|
Determine which URI mode is suitable for processing URIs of a given protocol.
|
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. |
|
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.
|
The documentation for this class was generated from the following files: