KURL Class Reference
Represents and parses a URL. More...
#include <kurl.h>
Collaboration diagram for KURL:

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 cleanPath(), hasSubURL(), isRelativeURL(), join(), m_strHost, m_strPass, m_strProtocol, m_strUser, ref(), setHTMLRef(), split(), and url(). |
Member Function Documentation
|
Returns the protocol for the URL (i.e., file, http, etc.).
Referenced by KApplication::allowURLAction(), KApplication::authorizeURLAction(), relativeURL(), KGlobalSettings::showFilePreview(), and KURLDrag::urlToString(). |
|
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.
|
|
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(), upURL(), and KURLDrag::urlToString(). |
|
References path(). |
|
Sets the path of the URL. The query is not changed by this function.
References Auto, 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.
|
|
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 setEncodedPath(). |
|
Sets the (already encoded) path.
Referenced by setEncodedPathAndQuery(), and setFileName(). |
|
Returns the encoded path and the query.
References Mailto, and path(). Referenced by url(). |
|
|
|
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.
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 hasSubURL(), ref(), and split(). |
|
Returns the HTML reference (the part of the URL after "#") in encoded form.
References hasSubURL(), ref(), and split(). |
|
Sets the HTML-style reference.
References hasSubURL(), join(), and split(). |
|
Checks whether there is a HTML reference.
References 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(). 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(), isLocalFile(), and query(). |
|
Returns encoding information from url, the content of the "charset" parameter.
References decode_string(), isLocalFile(), and query(). |
|
Checks whether the URL has any sub URLs. See split() for examples for sub URLs.
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(), join(), 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(). |
|
Returns the list of query items as a map mapping keys to values.
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.
References cleanPath(), encode_string(), path(), setEncodedPath(), and setPath(). |
|
Returns the filename of the path.
References hasSubURL(), path(), and split(). |
|
Returns the directory of the path.
Referenced by KConfigINIBackEnd::parseConfigFiles(), relativeURL(), and KConfigINIBackEnd::sync(). |
|
Set the directory to Definition at line 1934 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
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().
References encodedPathAndQuery(), hasHost(), hasPass(), hasRef(), hasUser(), Mailto, 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 hasHost(), hasRef(), hasUser(), Mailto, 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(). |
|
Returns the URL as string, escaped for HTML.
References prettyURL(). |
|
Test to see if the KURL is empty.
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(), hasSubURL(), join(), KURL(), path(), query(), 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 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.
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 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 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.
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.
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(), 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.
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 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 split(). |
The documentation for this class was generated from the following files: