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().
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 118 of file kurl.h.
Member Enumeration Documentation
|
Defines the type of URI we are processing.
Referenced by uriModeForProtocol(). |
|
Options for queryItems. Currently, only one option is defined:
|
Constructor & Destructor Documentation
|
Constructs an empty URL. Definition at line 427 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.
References QValueList::append(), cleanPath(), QString::find(), QString::findRev(), hasSubURL(), QString::isEmpty(), QString::isNull(), isRelativeURL(), join(), QValueList::last(), QString::length(), m_strHost, m_strPass, m_strProtocol, m_strUser, ref(), QValueList::remove(), setHTMLRef(), split(), QString::truncate(), and url(). |
Member Function Documentation
|
Returns the protocol for the URL (i.e., file, http, etc.).
Referenced by KApplication::allowURLAction(), KApplication::authorizeURLAction(), relativeURL(), and KGlobalSettings::showFilePreview(). |
|
Sets the protocol for the URL (i.e., file, http, etc.).
References Auto, and uriModeForProtocol(). |
|
Returns the URI processing mode for the URL.
|
|
Returns the decoded user name (login, user id, ...) included in the URL.
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.
Referenced by prettyURL(), relativeURL(), and url(). |
|
Returns the decoded password (corresponding to user()) included in the URL.
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.
Referenced by relativeURL(), and url(). |
|
Returns the decoded hostname included in the URL.
Referenced by KApplication::allowURLAction(), and relativeURL(). |
|
Sets the hostname included in the URL. Special characters in the hostname will appear encoded in the URL.
References Auto, QString::isEmpty(), QString::lower(), and URL. |
|
Test to see if this URL has a hostname included in it.
Referenced by prettyURL(), and url(). |
|
Returns the port number included in the URL.
Referenced by relativeURL(). |
|
Sets the port number included in the URL.
|
|
Returns the current decoded path. This does not include the query.
Referenced by KApplication::allowURLAction(), KApplication::authorizeURLAction(), cd(), encodedPathAndQuery(), equals(), fileName(), KApplication::invokeMailer(), isParentOf(), path(), relativeURL(), setFileName(), and upURL(). |
|
References path(). |
|
Sets the path of the URL. The query is not changed by this function.
References Auto, QString::isEmpty(), isEmpty(), and URL. Referenced by KApplication::authorizeURLAction(), cd(), fromPathOrURL(), 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.
References URL. Referenced by KURL(), KCmdLineArgs::makeURL(), and setFileName(). |
|
Add or remove a trailing slash to/from the path.
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.
References QString::find(), QString::left(), QString::length(), QString::right(), and setEncodedPath(). |
|
Sets the (already encoded) path.
Referenced by setEncodedPathAndQuery(), and setFileName(). |
|
Returns the encoded path and the query.
References QString::isEmpty(), QString::isNull(), Mailto, and path(). Referenced by url(). |
|
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.
References QString::isNull(). Referenced by fileEncoding(), KApplication::invokeMailer(), relativeURL(), setFileEncoding(), and upURL(). |
|
The reference is never decoded automatically.
Referenced by encodedHtmlRef(), htmlRef(), KURL(), relativeURL(), and split(). |
|
Sets the reference part (everything after '#').
|
|
Checks whether the URL has a reference part.
Referenced by hasHTMLRef(), prettyURL(), relativeURL(), and url(). |
|
Returns the HTML reference (the part of the URL after "#").
References QValueList::begin(), hasSubURL(), ref(), and split(). |
|
Returns the HTML reference (the part of the URL after "#") in encoded form.
References QValueList::begin(), hasSubURL(), ref(), and split(). |
|
Sets the HTML-style reference.
References QValueList::begin(), hasSubURL(), join(), and split(). |
|
Checks whether there is a HTML reference.
References QValueList::begin(), hasRef(), hasSubURL(), and split(). |
|
Checks whether the URL is well formed.
Referenced by KURLDrag::decode(), equals(), isMalformed(), and isParentOf(). |
|
References isValid(). |
|
Checks whether the file is local.
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.
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.
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.
References QString::isEmpty(), and QString::startsWith(). 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.
References hasSubURL(), QString::isEmpty(), join(), QValueList::last(), QString::length(), QString::mid(), and split(). |
|
call the function below with encoding_hint = 0 (will be merged for KDE4) |
|
Returns the value of a certain query item.
References decode_string(), QString::fromLatin1(), QString::length(), QString::replace(), and QStringList::split(). |
|
Returns the list of query items as a map mapping keys to values.
References decode_string(), QMap::insert(), QString::isEmpty(), QString::replace(), and QStringList::split(). |
|
Add an additional query item. To replace an existing query item, the item should first be removed with removeQueryItem()
References QString::isEmpty(). |
|
Remove an item from the query.
References QStringList::join(), QString::length(), and QStringList::split(). |
|
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.
References cleanPath(), encode_string(), QString::findRev(), QString::isEmpty(), QString::mid(), path(), QString::right(), setEncodedPath(), setPath(), and QString::truncate(). |
|
Returns the filename of the path.
References QString::contains(), QString::findRev(), QValueList::fromLast(), hasSubURL(), QString::isEmpty(), QString::left(), QString::length(), QString::mid(), path(), and split(). |
|
Returns the directory of the path.
References QString::findRev(), QString::isEmpty(), and QString::left(). Referenced by KConfigINIBackEnd::parseConfigFiles(), relativeURL(), and KConfigINIBackEnd::sync(). |
|
Set the directory to Definition at line 1934 of file kurl.cpp. References QString::endsWith(), and setPath(). |
|
Changes the directory by descending into the given directory.
It is assumed the current URL represents a directory. If
References hasSubURL(), QDir::homeDirPath(), QString::isEmpty(), join(), QValueList::last(), QString::length(), path(), QString::right(), 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().
References encodedPathAndQuery(), QString::find(), hasHost(), hasPass(), hasRef(), hasUser(), QString::isEmpty(), Mailto, QString::sprintf(), and URL. Referenced by fromPathOrURL(), 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
References QString::find(), hasHost(), hasRef(), hasUser(), QString::isEmpty(), QString::isNull(), Mailto, QString::sprintf(), and URL. Referenced by htmlURL(), kdbgstream::operator<<(), and prettyURL(). |
|
Returns the URL as string, escaped for HTML. Example: http://localhost:8080/test.cgi?test=hello world&name=fred
References prettyURL(), QString::remove(), and QString::startsWith(). |
|
Returns the URL as string, escaped for HTML.
References QStyleSheet::escape(), and prettyURL(). |
|
Test to see if the KURL is empty.
References QString::isEmpty(). 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.
References _setQuery(), cd(), QValueList::count(), QValueList::fromLast(), hasSubURL(), QValueList::isEmpty(), QString::isEmpty(), join(), KURL(), QValueList::last(), path(), query(), QValueList::remove(), and split(). |
|
The same as equals(), just with a less obvious name.
Compares this url with
References equals(). |
|
Compares this url with
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/.
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.
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.
References QValueList::append(), QValueList::begin(), QValueList::end(), hasSubURL(), KURL(), m_strRef_encoded, ref(), 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.
References QValueList::end(), QValueList::fromLast(), QValueList::isEmpty(), 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.
References QString::isEmpty(), KURL(), setPath(), and url(). |
|
Convenience function. Convert unicoded string to local encoding and use -style encoding for all common delimiters / non-ascii characters.
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()
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.
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
References directory(), hasPass(), hasRef(), hasUser(), host(), QString::isEmpty(), pass(), path(), port(), protocol(), query(), ref(), url(), and user(). |
|
Convenience function.
Returns a relative path based on
References QString::prepend(). |
|
Determine which URI mode is suitable for processing URIs of a given protocol.
References Auto, Mailto, RawURI, URIMode, KProtocolInfo::uriParseMode(), and URL. Referenced by setProtocol(). |
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 2011 of file kurl.cpp. References QValueList::isEmpty(), QString::isEmpty(), and 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.
References QValueList::begin(), QValueList::count(), QValueList::end(), QValueList::isEmpty(), QString::isEmpty(), and split(). |
The documentation for this class was generated from the following files: