KURL Class Reference

`#include <kurl.h>`

## Classes

class | List

## 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

static List | split (const QString &_url)
static List | split (const KURL &_url)
static KURL | join (const List &_list)
static KURL | fromPathOrURL (const QString &text)
static QString | encode_string (const QString &str, int encoding_hint=0)
static QString | encode_string_no_slash (const QString &str, int encoding_hint=0)
static QString | decode_string (const QString &str, int encoding_hint=0)
static bool | isRelativeURL (const QString &_url)
static QString | relativeURL (const KURL &base_url, const KURL &url, int encoding_hint=0)
static QString | relativePath (const QString &base_dir, const QString &path, bool *isParent=0)
static 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.

For examle:

- '#' -> "%23" (In a URL the hash-character `'#'` is used to specify a "reference", i.e. the position within a document)
- space -> "%20"

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&):

KURL kurl;
kurl.setPath( "/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#"

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.

Instead you should use addPath().

Right:

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"

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,

http://localhost/cgi-bin/test%20me.pl?cmd=Hello%20you

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.

Author
  Torben Weis weis@.nosp@m.kde..nosp@m.org

Definition at line 127 of file kurl.h.

## Member Enumeration Documentation

enum KURL::AdjustementFlags

Flags to choose how file: URLs are treated when creating their QString representation with prettyURL(int,AdjustementFlags)

However it is recommended to use pathOrURL() instead of this variant of prettyURL()

Enumerator
NoAdjustements | Do not treat file: URLs differently.
StripFileProtocol | Strip the file: protocol from the string, i.e. return only the path and filename as a local path

Definition at line 136 of file kurl.h.

enum KURL::QueryItemsOptions

Options for queryItems()

Since
  3.1

Enumerator
CaseInsensitiveKeys | Normalize query keys to lowercase.

Definition at line 925 of file kurl.h.

enum KURL::URIMode

Defines the type of URI we are processing.

Enumerator
Auto | Automatically detected. Using this mode, an appropriate processing mode will be selected when the URI is first processed.
Invalid | Invalid URI. This is something that can't be parsed as a URI at all. The contents are accessible through the protocol() method.
RawURI | Raw URI. This type of URI should not be processed in any way. Contents are accessible through the path() method.
URL | Standards compliant URL. Process as a syntactically correct URL.
Mailto | Mailto URI. path() contains an email address which should have its domain part processed as a DNS name. The email address is accessible through the path() method.

Definition at line 152 of file kurl.h.

## Constructor & Destructor Documentation

KURL::KURL | ( |  | ) |

Constructs an empty URL.

The created instance will also be invalid, see isValid()

Definition at line 455 of file kurl.cpp.

KURL::~KURL | ( |  | ) |

Destructs the KURL object.

Definition at line 460 of file kurl.cpp.

KURL::KURL | ( | const QString & | url,
|  | int | encoding_hint = `0`
| ) |  |

Usual constructor, to construct from a string.

Warning
  It is dangerous to feed UNIX filenames into this function, this will work most of the time but not always.

For example `"/home/Torben%20Weis"` will be considered a URL pointing to the file `"/home/Torben Weis"` instead of to the file `"/home/Torben%20Weis"`.

This means that if you have a usual UNIX like path you should not use this constructor. Instead use fromPathOrURL()

Parameters

  url | a URL, not a filename. If the URL does not have a protocol part, `"file:"` is assumed
  encoding_hint | MIB of original encoding of URL. See QTextCodec::mibEnum()

See also
  fromPathOrURL()

Definition at line 465 of file kurl.cpp.

KURL::KURL | ( | const char * | url,
|  | int | encoding_hint = `0`
| ) |  |

Constructor taking an URL encoded in a C string.

Constructor taking a char * `url`, which is an encoded representation of the URL, exactly like the usual constructor. This is useful when the URL, in its encoded form, is strictly ASCII.

Warning
  It is dangerous to feed UNIX filenames into this function, this will work most of the time but not always.

For example `"/home/Torben%20Weis"` will be considered a URL pointing to the file `"/home/Torben Weis"` instead of to the file `"/home/Torben%20Weis"`.

This means that if you have a usual UNIX like path you should not use this constructor. Instead use fromPathOrURL()

Parameters

  url | an encoded URL. If the URL does not have a protocol part, `"file:"` is assumed
  encoding_hint | MIB of original encoding of URL. See QTextCodec::mibEnum()

See also
  fromPathOrURL()
  QString::fromLatin1()

Definition at line 471 of file kurl.cpp.

KURL::KURL | ( | const QCString & | url,
|  | int | encoding_hint = `0`
| ) |  |

Constructor taking an URL encoded in a QCString.

Constructor taking a QCString `url`, which is an encoded representation of the URL, exactly like the usual constructor. This is useful when the URL, in its encoded form, is strictly ASCII.

Warning
  It is dangerous to feed UNIX filenames into this function, this will work most of the time but not always.

For example `"/home/Torben%20Weis"` will be considered a URL pointing to the file `"/home/Torben Weis"` instead of to the file `"/home/Torben%20Weis"`.

This means that if you have a usual UNIX like path you should not use this constructor. Instead use fromPathOrURL()

Parameters

  url | A encoded URL. If the URL does not have a protocol part, `"file:"` is assumed
  encoding_hint | MIB of original encoding of URL. See QTextCodec::mibEnum()

See also
  fromPathOrURL()
  QString::fromLatin1()

Definition at line 477 of file kurl.cpp.

KURL::KURL | ( | const KURL & | u | ) |

Copy constructor.

Parameters

  u | the KURL to copy

Definition at line 483 of file kurl.cpp.

KURL::KURL | ( | const QUrl & | u | ) |

Constructor taking a Qt URL.

Converts from a Qt URL.

Parameters

  u | the QUrl

Definition at line 522 of file kurl.cpp.

KURL::KURL | ( | const KURL & | _baseurl,
|  | const QString & | _rel_url,
|  | int | encoding_hint = `0`
| ) |  |

Constructor allowing relative URLs.

Warning
  It is dangerous to feed UNIX filenames into this function, this will work most of the time but not always.

For example `"/home/Torben%20Weis"` will be considered a URL pointing to the file `"/home/Torben Weis"` instead of to the file `"/home/Torben%20Weis"`.

This means that if you have a usual UNIX like path you should not use this constructor. Instead use fromPathOrURL()

Parameters

  _baseurl | The base url.
  _rel_url | A relative or absolute URL. If this is an absolute URL then `_baseurl` will 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() or fromPathOrURL() instead)
  encoding_hint | MIB of original encoding of URL. See QTextCodec::mibEnum()

See also
  fromPathOrURL()

Definition at line 528 of file kurl.cpp.

## Member Function Documentation

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

See also
  setPath()
  hasPath()

Definition at line 1733 of file kurl.cpp.

void KURL::addQueryItem | ( | const QString & | _item,
|  | const QString & | _value,
|  | int | encoding_hint = `0`
| ) |  |

Adds 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
  encoding_hint | MIB of encoding to use for _value. See QTextCodec::mibEnum()

See also
  queryItem()
  queryItems()
  query()

Definition at line 2224 of file kurl.cpp.

void KURL::adjustPath | ( | int | _trailing | ) |

Adds or removes a trailing slash to/from the path.

The `_trailing` parameter allows to ensure the existance or absence of the last (trailing) `'/'` character in the path. If the URL has no path, then no `'/'` is added anyway. And on the other side: if the path is just `"/"`, 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 | May be ( `-1`, `0`, `+1` ). `-1` strips a trailing `'/'`, `+1` adds a trailing `'/'` if there is none yet and `0` returns the path unchanged

See also
  hasPath()
  cleanPath()

Definition at line 1296 of file kurl.cpp.

bool KURL::cd | ( | 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

See also
  directory()
  path()

Definition at line 1800 of file kurl.cpp.

void KURL::cleanPath | ( | bool | cleanDirSeparator = `true` | ) |

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

  cleanDirSeparator | if `true`, occurrences of consecutive directory separators (e.g. `"/foo//bar"`) are cleaned up as well

See also
  hasPath()
  adjustPath()

Definition at line 1257 of file kurl.cpp.

bool KURL::cmp | ( | const KURL & | u,
|  | bool | ignore_trailing = `false`
| ) |  | const

Compares this URL with another one.

The same as equals(), just with a less obvious name.

Parameters

  u | the URL to compare this one with
  ignore_trailing | set to `true` to ignore trailing `'/'` characters

Returns
  `true` if both URLs are the same

See also
  operator==. This function should be used if you want to ignore trailing `'/'` characters

Deprecated:
  Use equals() instead.

Definition at line 1154 of file kurl.cpp.

QString KURL::decode_string | ( | const QString & | str,
|  | int | encoding_hint = `0`
| ) |  |

static

Decodes a string as used in URLs.

Convenience function.

Decode %-style encoding and convert from local encoding to unicode.

Reverse of encode_string()

Parameters

  str | the string to decode (can be `QString::null`)
  encoding_hint | MIB of original encoding of `str` . See QTextCodec::mibEnum()

Returns
  the decoded string

See also
  encode_string()
  encode_string_no_slash()

Definition at line 2066 of file kurl.cpp.

QString KURL::directory | ( | bool | _strip_trailing_slash_from_result = `true`,
|  | bool | _ignore_trailing_slash_in_path = `true`
| ) |  | const

Returns the directory of the path.

The directory is everything between the last and the second last `'/'` is returned. For example `"file:///hallo/torben/"` would return `"/hallo/torben/"` while `"file:///hallo/torben"` would return `"hallo/"`.

`_ignore_trailing_slash_in_path` tells whether a trailing `'/'` should be ignored. This means that the function would return `"/hallo"` (or `"/hallo"` depending on `_strip_trailing_slash_from_result`) for `"file:///hallo/torben/"` and `"file:///hallo/torben"`.

Parameters

  _strip_trailing_slash_from_result | tells whether the returned result should end with `'/'` or not. If the path is empty or just `"/"` then this flag has no effect
  _ignore_trailing_slash_in_path | if set to `false`, then everything behind the last `'/'` is considered to be the filename

Returns
  the directory part of the current path or `QString::null` when there is no path. The returned string is decoded

See also
  setDirectory()
  fileName()
  path()

Definition at line 1766 of file kurl.cpp.

QString KURL::encode_string | ( | const QString & | str,
|  | int | encoding_hint = `0`
| ) |  |

static

Encodes a string for use in URLs.

Convenience function.

Convert unicoded string to local encoding and use %%-style encoding for all common delimiters / non-ascii characters.

Parameters

  str | the string to encode (can be `QString::null`)
  encoding_hint | MIB of encoding to use. See QTextCodec::mibEnum()

Returns
  the encoded string

See also
  encode_string_no_slash()
  decode_string()

Definition at line 2071 of file kurl.cpp.

QString KURL::encode_string_no_slash | ( | const QString & | str,
|  | int | encoding_hint = `0`
| ) |  |

static

Encodes a string for use in URLs.

Convenience function.

Convert unicoded string to local encoding and use %%-style encoding for all common delimiters and non-ascii characters as well as the slash `'/'`.

Parameters

  str | the string to encode (can be `QString::null`)
  encoding_hint | MIB of encoding to use. See QTextCodec::mibEnum()

See also
  encode_string()
  decode_string()

Definition at line 2076 of file kurl.cpp.

QString KURL::encodedHtmlRef | ( |  | ) | const

Returns the encoded HTML-style reference (the part of the URL after `'#'`)

Returns
  the HTML-style reference in its original, encoded, form

See also
  htmlRef()
  setHTMLRef()
  hasHTMLRef()

Definition at line 1899 of file kurl.cpp.

QString KURL::encodedPathAndQuery | ( | int | _trailing = `0`,
|  | bool | _no_empty_path = `false`,
|  | int | encoding_hint = `0`
| ) |  | const

Returns the encoded path and the query.

The `_trailing` parameter allows to ensure the existance or absence of the last (trailing) `'/'` character in the path. If the URL has no path, then no `'/'` is added anyway. And on the other side: if the path is just `"/"`, 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 | May be ( `-1`, `0`, `+1` ). `-1` strips a trailing `'/'`, `+1` adds a trailing `'/'` if there is none yet and `0` returns the path unchanged
  _no_empty_path | if set to `true` then an empty path is substituted by `"/"`
  encoding_hint | MIB of desired encoding of URL. See QTextCodec::mibEnum()

Returns
  the concatenation of the encoded path , `'`?' and the encoded query

See also
  setEncodedPathAndQuery()
  path()
  query()

Definition at line 1306 of file kurl.cpp.

bool KURL::equals | ( | const KURL & | u,
|  | bool | ignore_trailing = `false`
| ) |  | const

Compares this URL with another one.

Parameters

  u | the URL to compare this one with
  ignore_trailing | set to `true` to ignore trailing `'/'` characters

Returns
  `true` if both urls are the same

See also
  operator==. This function should be used if you want to ignore trailing `'/'` characters

Since
  3.1

Definition at line 1159 of file kurl.cpp.

QString KURL::fileEncoding | ( |  | ) | const

Returns encoding information of the URL.

The encoding information is the content of the `"charset"` parameter.

Returns
  an encoding suitable for QTextCodec::codecForName() or `QString::null` if not encoding was specified

Definition at line 1416 of file kurl.cpp.

QString KURL::fileName | ( | bool | _ignore_trailing_slash_in_path = `true` | ) | const

Returns the filename of the path.

`_ignore_trailing_slash_in_path` tells whether a trailing `'/'` should be ignored. This means that the function would return `"torben"` for `"file:///hallo/torben/"` and `"file:///hallo/torben"`.

Parameters

  _ignore_trailing_slash_in_path | if set to `false`, then everything behind the last `'/'` is considered to be the filename

Returns
  the filename of the current path. The returned string is decoded. `QString::null` if there is no file (and thus no path)

See also
  setFileName()
  directory()
  path()

Definition at line 1674 of file kurl.cpp.

QString KURL::filename | ( | bool | _ignore_trailing_slash_in_path = `true` | ) | const

inline

Deprecated:
  change code to call fileName()

Definition at line 1718 of file kurl.h.

KURL KURL::fromPathOrURL | ( | const QString & | text | ) |

static

Creates a KURL object from a QString representing either an absolute path or a real URL.

Use this method instead of

QString someDir = ...
KURL url = someDir;

Otherwise some characters (e.g. the '#') won't be encoded properly.

Parameters

  text | the string representation of the URL to convert

Returns
  the new KURL

See also
  pathOrURL()
  KURL(const QString&, int)

Since
  3.1

Definition at line 2235 of file kurl.cpp.

bool KURL::hasHost | ( |  | ) | const

inline

Tests if this URL has a hostname included in it.

Returns
  `true` if the URL has a non-empty host

See also
  host()
  setHost()

Definition at line 498 of file kurl.h.

bool KURL::hasHTMLRef | ( |  | ) | const

Tests if there is an HTML-style reference.

Returns
  `true` if the URL has an HTML-style reference

See also
  htmlRef()
  encodedHtmlRef()
  setHTMLRef()
  hasRef()

Definition at line 1925 of file kurl.cpp.

bool KURL::hasPass | ( |  | ) | const

inline

Tests if this URL has a password included in it.

Note
  a password can only appear in a URL string if you also set a user, see setUser().

Returns
  `true` if there is a non-empty password set

See also
  pass()
  setPass()
  hasUser()

Definition at line 467 of file kurl.h.

bool KURL::hasPath | ( |  | ) | const

inline

Tests if this URL has a path included in it.

Returns
  `true` if there is a non-empty path

See also
  path()
  setPath()

Definition at line 591 of file kurl.h.

bool KURL::hasRef | ( |  | ) | const

inline

Tests if 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` as well

See also
  ref()
  setRef()

Definition at line 758 of file kurl.h.

bool KURL::hasSubURL | ( |  | ) | const

Tests if the URL has any sub URLs.

See split() for examples for sub URLs.

Returns
  `true` if the file has at least one sub URL

See also
  split()

Definition at line 1441 of file kurl.cpp.

bool KURL::hasUser | ( |  | ) | const

inline

Tests if this URL has a user name included in it.

Returns
  `true` if the URL has an non-empty user name

See also
  user()
  setUser()
  hasPass()

Definition at line 425 of file kurl.h.

QString KURL::host | ( |  | ) | const

inline

Returns the decoded hostname included in the URL.

Returns
  the name of the host or `QString::null` if no host is set

See also
  setHost()
  hasHost()

Definition at line 477 of file kurl.h.

QString KURL::htmlRef | ( |  | ) | const

Returns decoded the HTML-style reference (the part of the URL after `'#'`)

Returns
  the HTML-style reference

See also
  encodedHtmlRef()
  setHTMLRef()
  hasHTMLRef()
  split()
  hasSubURL()
  ref()

Definition at line 1888 of file kurl.cpp.

QString KURL::htmlURL | ( |  | ) | const

Returns the URL as string, escaped for HTML.

Returns
  a human readable URL, with no non-necessary encodings/escaped characters which is HTML encoded for safe inclusion in HTML or rich text. Password will not be shown.

See also
  prettyURL()
  url()
  pathOrURL()

Definition at line 1612 of file kurl.cpp.

bool KURL::isEmpty | ( |  | ) | const

Tests if the KURL is empty.

An empty URL has neither path nor protocol set.

Returns
  `true` if the URL is empty

See also
  hasPath()
  protocol()
  isValid()

Definition at line 632 of file kurl.cpp.

bool KURL::isLocalFile | ( |  | ) | const

Tests if the file is local.

Returns
  `true` if the file is a plain local file and has no filter protocols attached to it

Definition at line 1368 of file kurl.cpp.

KDE_DEPRECATED bool KURL::isMalformed | ( |  | ) | const

inline

Tests if the URL is malformed.

Returns
  `true` if the URL is malformed. This function does not test whether sub URLs are well-formed as well

Deprecated:
  Use !isValid() instead

See also
  isValid()

Definition at line 827 of file kurl.h.

bool KURL::isParentOf | ( | const KURL & | u | ) | const

Tests if the given URL is parent of this URL.

For instance, `"ftp://host/dir/"` is a parent of `"ftp://host/dir/subdir/subsubdir/"`.

Returns
  `true` if this URL is a parent of `u` (or the same URL as `u`)

See also
  equals()
  cd()

Definition at line 1186 of file kurl.cpp.

bool KURL::isRelativeURL | ( | const QString & | _url | ) |

static

Tests if a given URL is a relative as opposed to an absolute URL.

Convenience function.

Returns whether `_url` is likely to be a "relative" URL instead of an "absolute" URL.

Parameters

  _url | the URL to examine

Returns
  `true` when the URL is likely to be "relative", `false` otherwise

See also
  relativeURL()

Definition at line 403 of file kurl.cpp.

bool KURL::isValid | ( |  | ) | const

inline

Tests if the URL is well formed.

Returns
  `false` if the URL is malformed. This function does not test whether sub URLs are well-formed as well

Definition at line 816 of file kurl.h.

KURL KURL::join | ( | const List & | _list | ) |

static

Joins a list of URLs into a single URL with sub URLs.

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.

Parameters

  _list | the list to join

Returns
  the joined URL or an invalid URL if the list is empty

See also
  split()

Definition at line 1654 of file kurl.cpp.

bool KURL::operator!= | ( | const KURL & | _u | ) | const

inline

Tests if this URL is different from the given one.

Tests by negating the result of operator==()

Parameters

  _u | the URL to compare to

Returns
  the negated result of operator==()

See also
  operator==()
  operator<()

Definition at line 1430 of file kurl.h.

bool KURL::operator!= | ( | const QString & | _u | ) | const

inline

Tests if this URL is different from the one given as a string.

Tests by negating the result of operator==(const QString &)

Parameters

  _u | the URL to compare to

Returns
  the negated result of operator==(const QString &)

See also
  operator==(const QString &)
  operator<()

Definition at line 1444 of file kurl.h.

bool KURL::operator< | ( | const KURL & | _u | ) | const

Tests if this URL is less than the given URL.

The current URL is consideres `"less than"` then `_u` if (tested in this order):

- it is not valid but `_u` is. See isValid()
- its protocol is "less than" `_u's` protocol. See protocol()
- its host is "less than" `_u's` host. See host()
- its port is "less than" `_u's` port. See port()
- its path is "less than" `_u's` path. See path()
- its encoded query is "less than" `_u's` encoded query. See query()
- its endoded reference is "less than" `_u's` encoded reference. See ref()
- its username is "less than" `_u's` username. See user()
- its password is "less than" `_u's` password. See pass()

Examples:

KURL url1;
KURL url2;
bool lessThan = url1 < url2; // false. Both invalid, no protocols
url2.setProtocol( QString::null );
lessThan = url1 < url2; // true. url2 is valid because of setProtocol()
url1.setProtocol( QString::null );
lessThan = url1 < url2; // false. Both valid and everything empty
url1.setProtocol( "http" );
url2.setProtocol( "https" );
lessThan = url1 < url2; // true. "http" < "https"
url2.setHost( "api.kde.org" );
url2.setProtocol( "http" );
url2.setProtocol( "www.kde.org" );
lessThan = url1 < url2; // true. protocols equal and "api" < "www"
url1.setProtocol( "https" );
url2.setProtocol( "http" );
lessThan = url1 < url2; // false. "https" > "http". host doesn't matter yet

Parameters

  _u | the URL to compare to

Returns
  `true` if the URL is less than `_u`. Otherwise `false` (equal or greater than)

See also
  operator==()
  QString::compare()

Definition at line 1084 of file kurl.cpp.

KURL & KURL::operator= | ( | const KURL & | _u | ) |

Copies the values of the given URL into this one.

Just assigns each member using the member's assignment operator.

Parameters

  _u | the URL to take the values from

Returns
  a reference to this URL (*this)

See also
  equals()

Definition at line 1067 of file kurl.cpp.

KURL & KURL::operator= | ( | const QString & | _url | ) |

Assigns the URL, given as a string, to this one.

This will reset the current URL and parse the given string. See the similar constructor for known limitations.

Parameters

  _url | the QString to parse for values

Returns
  a reference to this URL (*this)

See also
  equals()
  KURL(const QString &, int)

Definition at line 1032 of file kurl.cpp.

KURL & KURL::operator= | ( | const char * | _url | ) |

Assigns the URL, given as a C string, to this one.

This will reset the current URL and parse the given string. See the similar constructor for known limitations.

Parameters

  _url | the C string to parse for values

Returns
  a reference to this URL (*this)

See also
  equals()
  KURL(const char *, int)

Definition at line 1040 of file kurl.cpp.

KURL & KURL::operator= | ( | const QUrl & | u | ) |

Assigns the URL, given as a Qt URL, to this one.

This will reset the current URL and parse the given string.

Parameters

  u | the Qt URL to take the values from

Returns
  a reference to this URL (*this)

See also
  equals()
  KURL(const QUrl &)

Definition at line 1049 of file kurl.cpp.

bool KURL::operator== | ( | const KURL & | _u | ) | const

Tests if this URL is equal to the given one.

Tests each member for equality unless one of the URLs is invalid in which case they are not considered equal (even if both are invalid).

Same as equals() when used with `ignore_trailing` set to `false` (default)

Parameters

  _u | the URL to compare to

Returns
  `true` if equal and neither this URL nor `_u` is malformed. Otherwise `false`

See also
  equals()
  isValid()
  operator!=()
  operator<()

Definition at line 1125 of file kurl.cpp.

bool KURL::operator== | ( | const QString & | _u | ) | const

Tests if this URL is equal to the one given as a string.

Creates a KURL instance for `_u` and compares with that using the equality operator for two KURLs.

See the respective constructor for known limitations.

Parameters

  _u | the string to compare to

Returns
  `true` if equal and neither this URL nor `_u` is malformed. Otherwise `false`

See also
  KURL(const QString &, int)
  operator==(const KURL &)
  equals()
  isValid()
  operator!=()
  operator<()

Definition at line 1148 of file kurl.cpp.

void KURL::parse | ( | const QString & | _url,
|  | int | encoding_hint = `0`
| ) |  |

protected

Parses the given string and fills the URL's values on success.

Parameters

  _url | the string to parse
  encoding_hint | MIB of original encoding of `str` . See QTextCodec::mibEnum()

Definition at line 637 of file kurl.cpp.

void KURL::parseMailto | ( | const QString & | _url,
|  | int | encoding_hint = `0`
| ) |  |

protected

Parses the given string and fills the URL's values on success.

Treats the string as a `"mailto:"` URI.

Parameters

  _url | the string to parse
  encoding_hint | MIB of original encoding of `str` . See QTextCodec::mibEnum()

Definition at line 740 of file kurl.cpp.

void KURL::parseRawURI | ( | const QString & | _url,
|  | int | encoding_hint = `0`
| ) |  |

protected

Parses the given string and fills the URL's values on success.

Treats the string as a generic URI.

Parameters

  _url | the string to parse
  encoding_hint | MIB of original encoding of `str` . See QTextCodec::mibEnum()

Definition at line 707 of file kurl.cpp.

void KURL::parseURL | ( | const QString & | _url,
|  | int | encoding_hint = `0`
| ) |  |

protected

Parses the given string and fills the URL's values on success.

Treats the string as an URL.

Parameters

  _url | the string to parse
  encoding_hint | MIB of original encoding of `str` . See QTextCodec::mibEnum()

Definition at line 759 of file kurl.cpp.

QString KURL::pass | ( |  | ) | const

inline

Returns the decoded password (corresponding to user()) included in the URL.

Note
  a password can only appear in a URL string if you also set a user, see setUser().

Returns
  the password or `QString::null` if it does not exist

See also
  setPass()
  hasPass()
  hasUser()

Definition at line 440 of file kurl.h.

QString KURL::path | ( |  | ) | const

inline

Returns the current decoded path.

This does not include the query.

Returns
  the path of the URL (without query), or `QString::null` if no path is set

See also
  path(int)
  setPath()
  hasPath()

Definition at line 532 of file kurl.h.

QString KURL::path | ( | int | _trailing | ) | const

Returns the current decoded path.

This does not include the query, see query() for accessing it.

The `_trailing` parameter allows to ensure the existance or absence of the last (trailing) `'/'` character in the path. If the URL has no path, then no `'/'` is added anyway. And on the other side: if the path is just `"/"`, 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 | May be ( `-1`, `0`, `+1` ). `-1` strips a trailing `'/'`, `+1` adds a trailing `'/'` if there is none yet and `0` returns the path unchanged

Returns
  the path of the URL (without query), or `QString::null` if no path is set

See also
  path()
  setPath()
  hasPath()
  adjustPath()

Definition at line 1363 of file kurl.cpp.

QString KURL::pathOrURL | ( |  | ) | const

Returns the URL as a string depending if it is a local file.

It 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.

Returns
  the path or URL string depending on its properties

See also
  prettyURL()
  path()
  url()
  isLocalFile()

Since
  3.4

Definition at line 1603 of file kurl.cpp.

unsigned short int KURL::port | ( |  | ) | const

inline

Returns the port number included in the URL.

Returns
  the port number or `0` if there is no port number specified in the URL

See also
  setPort()
  host()

Definition at line 509 of file kurl.h.

QString KURL::prettyURL | ( | int | _trailing = `0` | ) | const

Returns the URL as string in human-friendly format.

Example:

http://localhost:8080/test.cgi?test=hello world&name=fred

Does not contain the password if the URL has one, use url() if you need to have it in the string.

The `_trailing` parameter allows to ensure the existance or absence of the last (trailing) `'/'` character in the path. If the URL has no path, then no `'/'` is added anyway. And on the other side: if the path is just `"/"`, 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 | May be ( `-1`, `0`, `+1` ). `-1` strips a trailing `'/'`, `+1` adds a trailing `'/'` if there is none yet and `0` returns the path unchanged

Returns
  a human readable URL, with no non-necessary encodings/escaped characters. Password will not be shown

See also
  url()
  pathOrURL()

Definition at line 1524 of file kurl.cpp.

QString KURL::prettyURL | ( | int | _trailing,
|  | AdjustementFlags | _flags
| ) |  | const

Returns the URL as string in human-friendly format Example:

http://localhost:8080/test.cgi?test=hello world&name=fred

Does not contain the password if the URL has one, use url() if you need to have it in the string.

The `_trailing` parameter allows to ensure the existance or absence of the last (trailing) `'/'` character in the path. If the URL has no path, then no `'/'` is added anyway. And on the other side: if the path is just `"/"`, 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 | May be ( `-1`, `0`, `+1` ). `-1` strips a trailing `'/'`, `+1` adds a trailing `'/'` if there is none yet and `0` returns the path unchanged
  _flags | if StripFileProtocol, `"file://"` will be stripped. The use of this method is now discouraged, better use pathOrURL().

Returns
  a human readable URL, with no non-necessary encodings/escaped characters. Password will not be shown

See also
  prettyURL()
  url()
  pathOrURL()

Definition at line 1591 of file kurl.cpp.

QString KURL::protocol | ( |  | ) | const

inline

Returns the protocol for the URL.

Examples for a protocol string are `"file"`, `"http"`, etc. but also `"mailto:"` and other pseudo protocols.

Returns
  the protocol of the URL, does not include the colon. If the URL is malformed, `QString::null` will be returned

See also
  setProtocol()
  isValid()

Definition at line 367 of file kurl.h.

QString KURL::query | ( |  | ) | const

Returns the encoded 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.

Returns
  the encoded query or `QString::null` if there is none

See also
  setQuery()

Definition at line 2059 of file kurl.cpp.

QString KURL::queryItem | ( | const QString & | item | ) | const

Returns the value of a certain query item.

Parameters

  item | item whose value we want

Returns
  the value of the given query item name or `QString::null` if the specified item does not exist

See also
  addQueryItem()
  removeQueryItem()
  queryItems()
  query()

Definition at line 2170 of file kurl.cpp.

QString KURL::queryItem | ( | const QString & | item,
|  | int | encoding_hint
| ) |  | const

Returns the value of a certain query item.

Parameters

  item | item whose value we want
  encoding_hint | MIB of encoding of query. See QTextCodec::mibEnum()

Returns
  the value of the given query item name or `QString::null` if the specified item does not exist

See also
  addQueryItem()
  removeQueryItem()
  queryItems()
  query()

Definition at line 2175 of file kurl.cpp.

QMap< QString, QString > KURL::queryItems | ( | int | options,
|  | int | encoding_hint
| ) |  | const

Returns the list of query items as a map mapping keys to values.

Parameters

  options | any of QueryItemsOptions ORed together
  encoding_hint | MIB of encoding of query. See QTextCodec::mibEnum()

Returns
  the map of query items or the empty map if the URL has no query items

See also
  queryItem()
  addQueryItem()
  removeQueryItem()
  query()

Since
  3.1

Definition at line 2139 of file kurl.cpp.

QString KURL::ref | ( |  | ) | const

inline

Returns the encoded reference of the URL.

The reference is never decoded automatically.

Returns
  the undecoded reference, or `QString::null` if there is none

See also
  setRef()
  hasRef()
  htmlRef()

Definition at line 733 of file kurl.h.

QString KURL::relativePath | ( | const QString & | base_dir,
|  | const QString & | path,
|  | bool * | isParent = `0`
| ) |  |

static

Creates a path relative to a base path for a given input path.

Convenience function

Returns a relative path based on `base_dir` that points to `path`.

Parameters

  base_dir | the base directory to derive from
  path | the new target directory
  isParent | an optional pointer to a boolean which, if provided, will be set to reflect whether `path` has `base_dir` as a parent dir

See also
  relativeURL()

Definition at line 2285 of file kurl.cpp.

QString KURL::relativeURL | ( | const KURL & | base_url,
|  | const KURL & | url,
|  | int | encoding_hint = `0`
| ) |  |

static

Creates an URL relative to a base URL for a given input URL.

Convenience function

Returns a "relative URL" based on `base_url` that points to `url`.

If no "relative URL" can be created, e.g. because the protocol and/or hostname differ between `base_url` and `url` an absolute URL is returned.

Note
  if `base_url` represents a directory, it should contain a trailing slash

Parameters

  base_url | the URL to derive from
  url | the URL to point to relatively from `base_url`
  encoding_hint | MIB of original encoding of `str` . See QTextCodec::mibEnum()

See also
  isRelativeURL()
  relativePath()
  adjustPath()

Definition at line 2299 of file kurl.cpp.

void KURL::removeQueryItem | ( | const QString & | _item | ) |

Removea an item from the query.

Parameters

  _item | name of item to remove

See also
  addQueryItem()
  queryItem()
  queryItems()
  query()

Definition at line 2201 of file kurl.cpp.

void KURL::reset | ( |  | ) |

protected

Resets the members to their "null" state.

All QString members get reset to `QString::null`, the port to `0` the URIMode to `Auto` and the URL becomes invalid.

This is like assigning a null URL, but more efficient as it doesn't require the temporary object.

Called by constructors, assignment operators and the parse methods in case of a parsing error.

See also
  isValid()
  isEmpty()

Definition at line 617 of file kurl.cpp.

void KURL::setDirectory | ( | const QString & | dir | ) |

Sets the directory of the path, leaving the filename empty.

Parameters

  dir | the decoded directory to set

See also
  directory()
  setFileName()
  setPath()

Definition at line 2004 of file kurl.cpp.

void KURL::setEncodedPath | ( | const QString & | _txt,
|  | int | encoding_hint = `0`
| ) |  |

Sets the (already encoded) path of the URL.

Parameters

  _txt | the new encoded path
  encoding_hint | MIB of original encoding of `_txt` . See QTextCodec::mibEnum()

See also
  setEncodedPathAndQuery()
  setPath()

Definition at line 1334 of file kurl.cpp.

void KURL::setEncodedPathAndQuery | ( | const QString & | _txt,
|  | int | encoding_hint = `0`
| ) |  |

Sets both path and query of the URL in their encoded form.

This is useful for HTTP. It looks first for `'`?' and decodes then, see setEncodedPath(). The encoded path is the concatenation of the current path and the query.

Parameters

  _txt | the new encoded path and encoded query
  encoding_hint | MIB of original encoding of `_txt` . See QTextCodec::mibEnum()

See also
  encodedPathAndQuery()
  setPath()
  setQuery()

Definition at line 1348 of file kurl.cpp.

void KURL::setFileEncoding | ( | const QString & | encoding | ) |

Adds file encoding information.

Adds encoding information to the URL by adding a `"charset"` parameter. If there is already a charset parameter, it will be replaced.

Parameters

  encoding | the encoding to add or `QString::null` to remove the encoding

See also
  fileEncoding()
  QTextCodec::codecForName()

Definition at line 1387 of file kurl.cpp.

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 `'/'`.

If the current path ends with `'/'` then `_txt` is just appended, otherwise all text behind the last `'/'` in the current path is erased and `_txt` is appended then. It does not matter whether `_txt` starts with `'/'` or not.

Any reference is reset.

Parameters

  _txt | the filename to be set. It is considered to be decoded

See also
  fileName()
  setDirectory()
  setPath()

Definition at line 1218 of file kurl.cpp.

void KURL::setHost | ( | const QString & | _txt | ) |

Sets the hostname to include in the URL.

Special characters in the hostname will appear encoded in the URL.

Parameters

  _txt | the new name of the host or QString::null to remove the host

See also
  host()
  hasHost()

Definition at line 1963 of file kurl.cpp.

void KURL::setHTMLRef | ( | const QString & | _ref | ) |

Sets the decoded HTML-style reference.

Parameters

  _ref | the new reference. This is considered to be not encoded in contrast to setRef(). Use `QString::null` to remove it

See also
  htmlRef()
  hasHTMLRef()

Definition at line 1910 of file kurl.cpp.

void KURL::setPass | ( | const QString & | _txt | ) |

Sets the password (corresponding to user()) to include in the URL.

Special characters in the password will appear encoded in the URL.

Note
  a password can only appear in a URL string if you also set a user, see setUser().

Parameters

  _txt | the password to set or `QString::null` to remove the password

See also
  pass()
  hasPass()
  hasUser()

Definition at line 1954 of file kurl.cpp.

void KURL::setPath | ( | const QString & | path | ) |

Sets the decoded path of the URL.

This does not changed the query, see setQuery() for that.

The `path` is considered to be decoded, i.e. characters not allowed in path, for example `'`?' will be encoded and does not indicate the beginning of the query part. Something that might look encoded, like `"%3f"` will not become decoded.

Parameters

  path | the new, decoded, path or `QString::null` to remove the path

See also
  path()
  path(int)
  hasPath()

Definition at line 1990 of file kurl.cpp.

void KURL::setPort | ( | unsigned short int | _p | ) |

Sets the port number to include in the URL.

Parameters

  _p | the new port number or `0` to have no port number

See also
  port()
  setHost()

Definition at line 1985 of file kurl.cpp.

void KURL::setProtocol | ( | const QString & | _txt | ) |

Sets the protocol for the URL.

Examples for a protocol string are `"file"`, `"http"`, etc. but also `"mailto:"` and other pseudo protocols.

Parameters

  _txt | the new protocol of the URL (without colon)

See also
  protocol()

Definition at line 1937 of file kurl.cpp.

void KURL::setQuery | ( | const QString & | _txt,
|  | int | encoding_hint = `0`
| ) |  |

Sets the encoded query of the URL.

The query should start with a `'`?'. If it doesn't `'`?' is prepended.

Parameters

  _txt | this is considered to be encoded. This has a good reason: the query may contain the `'0'` character
  encoding_hint | MIB of the encoding. Reserved, should be `0` . See QTextCodec::mibEnum()

See also
  query()

Definition at line 2012 of file kurl.cpp.

void KURL::setRef | ( | const QString & | _txt | ) |

inline

Sets the encoded reference part (everything after `'#'`)

This is considered to be encoded, i.e. characters that are not allowed as part of the reference will not be encoded.

Parameters

  _txt | the encoded reference or `QString::null` to remove it

See also
  ref()
  hasRef()

Definition at line 746 of file kurl.h.

void KURL::setUser | ( | const QString & | _txt | ) |

Sets the user name (login, user id, etc) to include in the URL.

Special characters in the user name will appear encoded in the URL. If there is a password associated with the user, it can be set using setPass().

Parameters

  _txt | the name of the user or `QString::null` to remove the user

See also
  user()
  hasUser()
  hasPass()

Definition at line 1945 of file kurl.cpp.

KURL::List KURL::split | ( | const QString & | _url | ) |

static

Splits nested URLs into a list of URLs.

Example for a nested URL:

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#ref1"` 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.

Parameters

  _url | the URL that has to be split

Returns
  an empty list on error or the list of split URLs

See also
  hasSubURL()
  KURL(const QString&, int)
  join()

Definition at line 1649 of file kurl.cpp.

KURL::List KURL::split | ( | const KURL & | _url | ) |

static

Splits nested URLs into a list of URLs.

Example for a nested URL:

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#ref1"` 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.

Parameters

  _url | the URL that has to be split

Returns
  an empty list on error or the list of split URLs

See also
  hasSubURL()
  join()

Definition at line 1617 of file kurl.cpp.

KURL KURL::upURL | ( |  | ) | const

Returns the URL that is the best possible candidate for on level higher in the path hierachy.

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 until it can go up.

Returns
  a URL that is a level higher

See also
  cd()
  split()
  hasSubURL()
  path()

Definition at line 1852 of file kurl.cpp.

int KURL::uriMode | ( |  | ) | const

Returns the URI processing mode for the URL.

Returns
  the URI processing mode set for this URL

See also
  URIMode
  uriModeForProtocol()

Since
  3.2

Definition at line 2332 of file kurl.cpp.

KURL::URIMode KURL::uriModeForProtocol | ( | const QString & | protocol | ) |

static

Determines which URI mode is suitable for processing URIs of a given protocol.

Parameters

  protocol | the protocol name. See protocol()

Returns
  the URIMode suitable for the given protocol

See also
  uriMode()

Since
  3.2

Definition at line 2337 of file kurl.cpp.

QString KURL::url | ( | int | _trailing = `0`,
|  | int | encoding_hint = `0`
| ) |  | 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.

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().

The `_trailing` parameter allows to ensure the existance or absence of the last (trailing) `'/'` character in the path. If the URL has no path, then no `'/'` is added anyway. And on the other side: if the path is just `"/"`, 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 | May be ( `-1`, `0`, `+1` ). `-1` strips a trailing `'/'`, `+1` adds a trailing `'/'` if there is none yet and `0` returns the path unchanged
  encoding_hint | MIB of encoding to use. See QTextCodec::mibEnum()

Returns
  the complete URL, with all escape sequences intact, encoded in a given charset

See also
  prettyURL()
  pathOrURL()
  htmlURL()

Definition at line 1464 of file kurl.cpp.

QString KURL::user | ( |  | ) | const

inline

Returns the decoded user name (login, user id, etc) included in the URL.

Returns
  the user name or `QString::null` if there is no user name

See also
  setUser()
  hasUser()

Definition at line 401 of file kurl.h.

## Friends And Related Function Documentation

bool urlcmp | ( | const QString & | _url1,
|  | const QString & | _url2
| ) |  |

related

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 2081 of file kurl.cpp.

bool urlcmp | ( | const QString & | _url1,
|  | const QString & | _url2,
|  | bool | _ignore_trailing,
|  | bool | _ignore_ref
| ) |  |

related

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.

Parameters

  _url1 | A reference URL
  _url2 | A URL that will be compared with the reference URL
  _ignore_trailing | Described in KURL::cmp
  _ignore_ref | If true, disables comparison of HTML-style references.

Definition at line 2100 of file kurl.cpp.

The documentation for this class was generated from the following files:

- kurl.h
- kurl.cpp

KDE Home | KDE Accessibility Home | Description of Access Keys