KDE 4.0 API Reference KDECore
KUrl Class Reference
#include <kurl.h>
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. 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.
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"
Definition at line 109 of file kurl.h.
Public Types | |
| enum | MimeDataFlags { DefaultMimeDataFlags = 0, NoTextExport = 1 } |
| enum | AdjustPathOption { RemoveTrailingSlash, LeaveTrailingSlash, AddTrailingSlash } |
| enum | CleanPathOption { SimplifyDirSeparators = 0x00, KeepDirSeparators = 0x01 } |
| enum | EncodedPathAndQueryOption { PermitEmptyPath = 0x00, AvoidEmptyPath = 0x01 } |
| enum | QueryItemsOption { CaseInsensitiveKeys = 1 } |
| enum | DirectoryOption { ObeyTrailingSlash = 0x02, AppendTrailingSlash = 0x04, IgnoreTrailingSlash = 0x01 } |
| enum | EqualsOption { CompareWithoutTrailingSlash = 0x01, CompareWithoutFragment = 0x02 } |
| typedef QMap< QString, QString > | MetaDataMap |
Public Member Functions | |
| KUrl () | |
| ~KUrl () | |
| KUrl (const QString &urlOrPath) | |
| KUrl (const char *urlOrPath) | |
| KUrl (const QByteArray &urlOrPath) | |
| KUrl (const KUrl &u) | |
| KUrl (const QUrl &u) | |
| KUrl (const KUrl &_baseurl, const QString &_rel_url) | |
| QString | protocol () const |
| void | setProtocol (const QString &proto) |
| QString | user () const |
| void | setUser (const QString &user) |
| bool | hasUser () const |
| QString | pass () const |
| void | setPass (const QString &pass) |
| bool | hasPass () const |
| bool | hasHost () const |
| QString | path (AdjustPathOption trailing=LeaveTrailingSlash) const |
| QString | toLocalFile (AdjustPathOption trailing=LeaveTrailingSlash) const |
| void | setPath (const QString &path) |
| bool | hasPath () const |
| void | cleanPath (const CleanPathOption &options=SimplifyDirSeparators) |
| void | adjustPath (AdjustPathOption trailing) |
| void | setEncodedPathAndQuery (const QString &_txt) |
| QString | encodedPathAndQuery (AdjustPathOption trailing=LeaveTrailingSlash, const EncodedPathAndQueryOptions &options=PermitEmptyPath) const |
| void | setQuery (const QString &query) |
| QString | query () const |
| QString | ref () const |
| void | setRef (const QString &fragment) |
| bool | hasRef () const |
| QString | htmlRef () const |
| QString | encodedHtmlRef () const |
| void | setHTMLRef (const QString &_ref) |
| bool | hasHTMLRef () const |
| bool | isLocalFile () const |
| void | setFileEncoding (const QString &encoding) |
| QString | fileEncoding () const |
| bool | hasSubUrl () const |
| void | addPath (const QString &txt) |
| QMap< QString, QString > | queryItems (const QueryItemsOptions &options=0) const |
| QString | queryItem (const QString &item) const |
| void | addQueryItem (const QString &_item, const QString &_value) |
| void | setFileName (const QString &_txt) |
| QString | fileName (const DirectoryOptions &options=IgnoreTrailingSlash) const |
| QString | directory (const DirectoryOptions &options=IgnoreTrailingSlash) const |
| void | setDirectory (const QString &dir) |
| bool | cd (const QString &_dir) |
| QString | url (AdjustPathOption trailing=LeaveTrailingSlash) const |
| QString | prettyUrl (AdjustPathOption trailing=LeaveTrailingSlash) const |
| QString | pathOrUrl () const |
| QString | toMimeDataString () const |
| KUrl | upUrl () const |
| KUrl & | operator= (const KUrl &_u) |
| KUrl & | operator= (const char *_url) |
| KUrl & | operator= (const QByteArray &_url) |
| KUrl & | operator= (const QString &_url) |
| bool | operator== (const KUrl &_u) const |
| bool | operator== (const QString &_u) const |
| bool | operator!= (const KUrl &_u) const |
| bool | operator!= (const QString &_u) const |
| operator QVariant () const | |
| bool | cmp (const KUrl &u, bool ignore_trailing=false) const |
| bool | equals (const KUrl &u, const EqualsOptions &options=0) const |
| bool | isParentOf (const KUrl &u) const |
| void | populateMimeData (QMimeData *mimeData, const MetaDataMap &metaData=MetaDataMap(), MimeDataFlags flags=DefaultMimeDataFlags) const |
Static Public Member Functions | |
| static List | split (const QString &_url) |
| static List | split (const KUrl &_url) |
| static KUrl | join (const List &_list) |
| static KUrl | fromPath (const QString &text) |
| static KUrl | fromPathOrUrl (const QString &text) |
| static KUrl | fromMimeDataByteArray (const QByteArray &str) |
| static QString | encode_string (const QString &str) |
| static QString | encode_string_no_slash (const QString &str) |
| static QString | decode_string (const QString &str) |
| static bool | isRelativeUrl (const QString &_url) |
| static QString | relativeUrl (const KUrl &base_url, const KUrl &url) |
| static QString | relativePath (const QString &base_dir, const QString &path, bool *isParent=0) |
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, const KUrl::EqualsOptions &options) |
Classes | |
| class | List |
| KUrl::List is a QList that contains KUrls with a few convenience methods. More... | |
Member Typedef Documentation
Member Enumeration Documentation
| enum KUrl::MimeDataFlags |
option to be used in fileName and directory
- Enumerator:
-
ObeyTrailingSlash This tells whether a trailing '/' should be ignored. If the flag is not set, for both
file:///hallo/torben/andfile:///hallo/torbenthe 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.
AppendTrailingSlash tells whether the returned result should end with '/' or not. If the flag is set, '/' is added to the end of the path
If the path is empty or just "/" then this flag has no effect.
This option should only be used in directory(), it has no effect in fileName()
IgnoreTrailingSlash Opposite of ObeyTrailingSlash (default).
| enum KUrl::EqualsOption |
Constructor & Destructor Documentation
| KUrl::KUrl | ( | const QString & | urlOrPath | ) |
| KUrl::KUrl | ( | const char * | urlOrPath | ) | [explicit] |
| KUrl::KUrl | ( | const QByteArray & | urlOrPath | ) | [explicit] |
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.
- Parameters:
-
urlOrPath An encoded URL, or a path.
| KUrl::KUrl | ( | const KUrl & | u | ) |
| KUrl::KUrl | ( | const QUrl & | u | ) |
Constructor allowing relative URLs.
- Parameters:
-
_baseurl The base url. _rel_url A relative or absolute URL. If this is an absolute URL then _baseurlwill 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).
Member Function Documentation
| QString KUrl::protocol | ( | ) | const |
| void KUrl::setProtocol | ( | const QString & | proto | ) |
| QString KUrl::user | ( | ) | const |
| void KUrl::setUser | ( | const QString & | user | ) |
| bool KUrl::hasUser | ( | ) | const |
| QString KUrl::pass | ( | ) | const |
| void KUrl::setPass | ( | const QString & | pass | ) |
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.
- Parameters:
-
pass the password to set or QString() to remove the password
| bool KUrl::hasPass | ( | ) | const |
| bool KUrl::hasHost | ( | ) | const |
| QString KUrl::path | ( | AdjustPathOption | trailing = LeaveTrailingSlash |
) | const |
| QString KUrl::toLocalFile | ( | AdjustPathOption | trailing = LeaveTrailingSlash |
) | const |
| void KUrl::setPath | ( | const QString & | path | ) |
| bool KUrl::hasPath | ( | ) | const |
| void KUrl::cleanPath | ( | const CleanPathOption & | options = SimplifyDirSeparators |
) |
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.
- Parameters:
-
options use KeepDirSeparators if you don't want to remove consecutive occurrences of directory separator
| void KUrl::adjustPath | ( | AdjustPathOption | trailing | ) |
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.
- Parameters:
-
trailing RemoveTrailingSlash strips any trailing '/' and AddTrailingSlash adds a trailing '/' if there is none yet
| void KUrl::setEncodedPathAndQuery | ( | const QString & | _txt | ) |
| QString KUrl::encodedPathAndQuery | ( | AdjustPathOption | trailing = LeaveTrailingSlash, |
|
| const EncodedPathAndQueryOptions & | options = PermitEmptyPath | |||
| ) | const |
| void KUrl::setQuery | ( | const QString & | query | ) |
| QString KUrl::query | ( | ) | const |
| QString KUrl::ref | ( | ) | const |
| void KUrl::setRef | ( | const QString & | fragment | ) |
Sets the reference part (everything after '#').
If you have an encoded fragment already (as a QByteArray), you can call setFragment directly.
- Parameters:
-
fragment the encoded reference (or QString() to remove it).
Reimplemented from QUrl.
| bool KUrl::hasRef | ( | ) | const |
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.
| QString KUrl::htmlRef | ( | ) | const |
Returns the HTML reference (the part of the URL after "#").
- Returns:
- The HTML-style reference.
- See also:
- split
| QString KUrl::encodedHtmlRef | ( | ) | const |
| void KUrl::setHTMLRef | ( | const QString & | _ref | ) |
| bool KUrl::hasHTMLRef | ( | ) | const |
| bool KUrl::isLocalFile | ( | ) | const |
| void KUrl::setFileEncoding | ( | const QString & | encoding | ) |
| QString KUrl::fileEncoding | ( | ) | const |
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.
| bool KUrl::hasSubUrl | ( | ) | const |
| void KUrl::addPath | ( | const QString & | txt | ) |
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.
- Parameters:
-
txt The text to add. It is considered to be decoded.
Reimplemented from QUrl.
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.
- Parameters:
-
options any of QueryItemsOption ored together.
- Returns:
- the map of query items or the empty map if the url has no query items.
Returns the value of a certain query item.
This does the same as QUrl::queryItemValue(), except that it decodes "+" into " " in the value.
- Parameters:
-
item Item whose value we want
- Returns:
- the value of the given query item name or QString() if the specified item does not exist.
Add an additional query item.
To replace an existing query item, the item should first be removed with removeQueryItem()
- Parameters:
-
_item Name of item to add _value Value of item to add
Reimplemented from QUrl.
| void KUrl::setFileName | ( | const QString & | _txt | ) |
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.
- Parameters:
-
_txt The filename to be set. It is considered to be decoded. If the current path ends with '/' then _txtint just appended, otherwise all text behind the last '/' in the current path is erased and_txtis appended then. It does not matter whether_txtstarts with '/' or not.
Reimplemented from QUrl.
| QString KUrl::fileName | ( | const DirectoryOptions & | options = IgnoreTrailingSlash |
) | const |
| QString KUrl::directory | ( | const DirectoryOptions & | options = IgnoreTrailingSlash |
) | const |
Returns the directory of the path.
- Parameters:
-
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/" whilefile:///hallo/torbenwould return "hallo/". The returned string is decoded. QString() is returned when there is no path.
| void KUrl::setDirectory | ( | const QString & | dir | ) |
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:/
- Parameters:
-
_dir the directory to change to
- Returns:
- true if successful
| QString KUrl::url | ( | AdjustPathOption | trailing = LeaveTrailingSlash |
) | const |
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().
- Parameters:
-
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()
| QString KUrl::prettyUrl | ( | AdjustPathOption | trailing = LeaveTrailingSlash |
) | const |
Returns the URL as string in human-friendly format.
Example:
http://localhost:8080/test.cgi?test=hello world&name=fred
- Parameters:
-
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()
| QString KUrl::pathOrUrl | ( | ) | const |
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
| QString KUrl::toMimeDataString | ( | ) | const |
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.
| KUrl KUrl::upUrl | ( | ) | const |
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
| KUrl & KUrl::operator= | ( | const KUrl & | _u | ) |
| KUrl& KUrl::operator= | ( | const char * | _url | ) | [inline] |
| KUrl& |