kdecore Library API Documentation

KURL Class Reference

Represents and parses a URL. More...

#include <kurl.h>

List of all members.

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, QStringqueryItems (int options=0) const
QMap< QString, QStringqueryItems (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
KURLoperator= (const KURL &_u)
KURLoperator= (const QString &_url)
KURLoperator= (const char *_url)
KURLoperator= (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

QDataStreamoperator<< (QDataStream &s, const KURL &a)
QDataStreamoperator>> (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&).

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@kde.org>

Definition at line 118 of file kurl.h.


Member Enumeration Documentation

enum KURL::URIMode
 

Defines the type of URI we are processing.

Enumeration values:
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 130 of file kurl.h.

enum KURL::QueryItemsOptions
 

Options for queryItems.

Currently, only one option is defined:

Parameters:
CaseInsensitiveKeys normalize query keys to lowercase.
Since:
3.1

Definition at line 600 of file kurl.h.


Constructor & Destructor Documentation

KURL::KURL  ) 
 

Constructs an empty URL.

Definition at line 427 of file kurl.cpp.

Referenced by KURL::List::List(), and split().

KURL::~KURL  ) 
 

Destructs the KURL object.

Definition at line 432 of file kurl.cpp.

KURL::KURL const QString url,
int  encoding_hint = 0
 

Usual constructor, to construct from a string.

Parameters:
url A URL, not a filename. If the URL does not have a protocol part, "file:" is assumed. 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 create an empty url and set the path by using setPath().
encoding_hint MIB of original encoding of URL.
See also:
QTextCodec::mibEnum()

Definition at line 437 of file kurl.cpp.

KURL::KURL const char *  url,
int  encoding_hint = 0
 

Constructor taking a char * url, 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:
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 also:
QTextCodec::mibEnum()

Definition at line 443 of file kurl.cpp.

KURL::KURL const QCString url,
int  encoding_hint = 0
 

Constructor taking a QCString url, 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:
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 also:
QTextCodec::mibEnum()

Definition at line 449 of file kurl.cpp.

KURL::KURL const KURL u  ) 
 

Copy constructor.

Parameters:
u the KURL to copy

Definition at line 455 of file kurl.cpp.

KURL::KURL const QUrl u  ) 
 

Converts from a QUrl.

Parameters:
u the QUrl

Definition at line 494 of file kurl.cpp.

KURL::KURL const KURL _baseurl,
const QString _rel_url,
int  encoding_hint = 0
 

Constructor allowing relative URLs.

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 instead).
encoding_hint MIB of original encoding of URL.
See also:
QTextCodec::mibEnum()

Definition at line 500 of file kurl.cpp.

References cleanPath(), hasSubURL(), isRelativeURL(), join(), m_strHost, m_strPass, m_strProtocol, m_strUser, setHTMLRef(), split(), and url().


Member Function Documentation

QString KURL::protocol  )  const [inline]
 

Returns the protocol for the URL (i.e., file, http, etc.).

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

Definition at line 267 of file kurl.h.

Referenced by KApplication::allowURLAction(), KApplication::authorizeURLAction(), and KGlobalSettings::showFilePreview().

void KURL::setProtocol const QString _txt  ) 
 

Sets the protocol for the URL (i.e., file, http, etc.).

Parameters:
_txt the new protocol of the URL (without colon)

Definition at line 1873 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.
Since:
3.2

Definition at line 2262 of file kurl.cpp.

QString KURL::user  )  const [inline]
 

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

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

Definition at line 285 of file kurl.h.

void KURL::setUser const QString _txt  ) 
 

Sets the user name (login, user id, ...) included in the URL.

Special characters in the user name will appear encoded in the URL.

Parameters:
_txt the name of the user or QString::null to remove the user

Definition at line 1881 of file kurl.cpp.

bool KURL::hasUser  )  const [inline]
 

Test to see if this URL has a user name included in it.

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

Definition at line 297 of file kurl.h.

Referenced by prettyURL(), and url().

QString KURL::pass  )  const [inline]
 

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

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

Definition at line 303 of file kurl.h.

void KURL::setPass const QString _txt  ) 
 

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:
_txt the password to set or QString::null to remove the password
See also:
setUser

hasUser

Definition at line 1887 of file kurl.cpp.

bool KURL::hasPass  )  const [inline]
 

Test to see if this URL has a password included in it.

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

Definition at line 319 of file kurl.h.

Referenced by url().

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

Definition at line 325 of file kurl.h.

Referenced by KApplication::allowURLAction().

void KURL::setHost const QString _txt  ) 
 

Sets the hostname included 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

Definition at line 1893 of file kurl.cpp.

bool KURL::hasHost  )  const [inline]
 

Test to see if this URL has a hostname included in it.

Returns:
true if the URL has a host

Definition at line 338 of file kurl.h.

Referenced by url().

unsigned short int KURL::port  )  const [inline]
 

Returns the port number included in the URL.

Returns:
the port number. If there is no port number specified in the URL, returns 0.

Definition at line 345 of file kurl.h.

void KURL::setPort unsigned short int  _p  ) 
 

Sets the port number included in the URL.

Parameters:
_p the new port number or 0 to have no port number

Definition at line 1915 of file kurl.cpp.

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

Definition at line 357 of file kurl.h.

Referenced by KApplication::allowURLAction(), KApplication::authorizeURLAction(), encodedPathAndQuery(), equals(), KApplication::invokeMailer(), isParentOf(), and path().

QString KURL::path int  _trailing  )  const
 

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. 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.
Returns:
The current decoded path. This does not include the query. Can be QString::null if no path is set.

Definition at line 1314 of file kurl.cpp.

References path().

void KURL::setPath const QString path  ) 
 

Sets the path of the URL.

The query is not changed by this function.

Parameters:
path The new path. This is considered to be decoded. This means: 3f does not become decoded and the ? does not indicate the start of the query part. Can be QString::null to delete the path.

Definition at line 1920 of file kurl.cpp.

Referenced by KApplication::authorizeURLAction(), KCmdLineArgs::makeURL(), KConfigINIBackEnd::parseConfigFiles(), KDesktopFile::readURL(), setFileName(), and KConfigINIBackEnd::sync().

bool KURL::hasPath  )  const [inline]
 

Test to see if this URL has a path is included in it.

Returns:
true if there is a path

Definition at line 388 of file kurl.h.

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.

Definition at line 1211 of file kurl.cpp.

References URL.

Referenced by KURL(), KCmdLineArgs::makeURL(), and setFileName().

void KURL::adjustPath int  _trailing  ) 
 

Add or remove a trailing slash to/from the path.

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

Definition at line 1247 of file kurl.cpp.

void KURL::setEncodedPathAndQuery const QString _txt,
int  encoding_hint = 0
 

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.

Parameters:
_txt the new path and query.
encoding_hint MIB of original encoding of _txt .
See also:
QTextCodec::mibEnum()

Definition at line 1299 of file kurl.cpp.

References setEncodedPath().

void KURL::setEncodedPath const QString _txt,
int  encoding_hint = 0
 

Sets the (already encoded) path.

Parameters:
_txt the new path
encoding_hint MIB of original encoding of _txt .
See also:
QTextCodec::mibEnum()

Definition at line 1285 of file kurl.cpp.

References Auto, and URL.

Referenced by setEncodedPathAndQuery(), and setFileName().

QString KURL::encodedPathAndQuery int  _trailing = 0,
bool  _no_empty_path = false,
int  encoding_hint = 0
const
 

Returns the encoded path and the query.

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. 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.
_no_empty_path If set to true then an empty path is substituted by "/".
encoding_hint MIB of desired encoding of URL.
See also:
QTextCodec::mibEnum()
Returns:
The concatenation if the encoded path , '?' and the encoded query.

Definition at line 1257 of file kurl.cpp.

References Mailto, and path().

void KURL::setQuery const QString _txt,
int  encoding_hint = 0
 

Parameters:
_txt This is considered to be encoded. This has a good reason: The query may contain the 0 character.
The query should start with a '?'. If it doesn't '?' is prepended.
Parameters:
encoding_hint Reserved, should be 0.
See also:
QTextCodec::mibEnum()

Definition at line 1942 of file kurl.cpp.

QString KURL::query  )  const
 

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.

Returns:
The encoded query, or QString::null if there is none.

Definition at line 1989 of file kurl.cpp.

Referenced by fileEncoding(), KApplication::invokeMailer(), and setFileEncoding().

QString KURL::ref  )  const [inline]
 

The reference is never decoded automatically.

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

Definition at line 473 of file kurl.h.

void KURL::setRef const QString _txt  )  [inline]
 

Sets the reference part (everything after '#').

Parameters:
_txt The encoded reference (or QString::null to remove it).

Definition at line 479 of file kurl.h.

bool KURL::hasRef  )  const [inline]
 

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.

Definition at line 487 of file kurl.h.

QString KURL::htmlRef  )  const
 

Returns the HTML reference (the part of the URL after "#").

Returns:
The HTML-style reference.
See also:
split

hasSubURL

encodedHtmlRef

Definition at line 1824 of file kurl.cpp.

QString KURL::encodedHtmlRef  )  const
 

Returns the HTML reference (the part of the URL after "#") in encoded form.

Returns:
The HTML-style reference in its original form.

Definition at line 1835 of file kurl.cpp.

void KURL::setHTMLRef const QString _ref  ) 
 

Sets the 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()

Definition at line 1846 of file kurl.cpp.

Referenced by KURL().

bool KURL::hasHTMLRef  )  const
 

Checks whether there is a HTML reference.

Returns:
true if the URL has an HTML-style reference.
See also:
htmlRef()

Definition at line 1861 of file kurl.cpp.

References Auto, and URL.

bool KURL::isValid  )  const [inline]
 

Checks whether the URL is well formed.

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

Definition at line 526 of file kurl.h.

Referenced by KURLDrag::decode(), equals(), isMalformed(), and isParentOf().

KDE_DEPRECATED bool KURL::isMalformed  )  const [inline]
 

Deprecated:
Use !isValid() instead.

Definition at line 530 of file kurl.h.

References isValid().

bool KURL::isLocalFile  )  const
 

Checks whether 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 1319 of file kurl.cpp.

References hasSubURL().

Referenced by fileEncoding(), setFileEncoding(), and KURLDrag::urlToString().

void KURL::setFileEncoding const QString encoding  ) 
 

Adds encoding information to 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.

Definition at line 1338 of file kurl.cpp.

References decode_string(), encode_string(), isLocalFile(), and query().

QString KURL::fileEncoding  )  const
 

Returns encoding information from url, the content of the "charset" parameter.

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

Definition at line 1367 of file kurl.cpp.

References decode_string(), isLocalFile(), and query().

bool KURL::hasSubURL  )  const
 

Checks whether 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 1392 of file kurl.cpp.

Referenced by isLocalFile(), and KURL().

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.

Definition at line 1671 of file kurl.cpp.

QString KURL::queryItem const QString item  )  const
 

call the function below with encoding_hint = 0 (will be merged for KDE4)

Definition at line 2100 of file kurl.cpp.

Referenced by queryItems().

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.
Returns:
the value of the given query item name or QString::null if the specified item does not exist.

Definition at line 2105 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.
Returns:
the map of query items or the empty map if the url has no query items.
Since:
3.1

Definition at line 2069 of file kurl.cpp.

References queryItem().

void KURL::addQueryItem const QString _item,
const QString _value,
int  encoding_hint = 0
 

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

Definition at line 2154 of file kurl.cpp.

void KURL::removeQueryItem const QString _item  ) 
 

Remove an item from the query.

Parameters:
_item Item to be removed

Definition at line 2131 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 '/'.

Any reference is reset.

Parameters:
_txt The filename to be set. It is considered to be decoded. If the current path ends with '/' then _txt int 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.

Definition at line 1172 of file kurl.cpp.

References cleanPath(), encode_string(), setEncodedPath(), and setPath().

QString KURL::fileName bool  _ignore_trailing_slash_in_path = true  )  const
 

Returns the filename of the path.

Parameters:
_ignore_trailing_slash_in_path This tells whether a trailing '/' should be ignored. This means that the function would return "torben" for file:/hallo/torben/ and file:/hallo/torben. If the flag is 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. Null if there is no file (and thus no path).

Definition at line 1612 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.

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 means that file:/hallo/torben and file:/hallo/torben/" would both return /hallo/ or /hallo depending on the other flag
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/" while file:/hallo/torben would return "hallo/". The returned string is decoded. QString::null is returned when there is no path.

Definition at line 1704 of file kurl.cpp.

Referenced by KConfigINIBackEnd::parseConfigFiles(), and KConfigINIBackEnd::sync().

void KURL::setDirectory const QString dir  ) 
 

Set the directory to dir, leaving the filename empty.

Definition at line 1934 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

Definition at line 1738 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. 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 This may be ( -1, 0 +1 ). -1 strips a trailing '/' from the path, +1 adds a trailing '/' if there is none yet and 0 returns the path unchanged.
encoding_hint MIB of encoding to use.
Returns:
The complete URL, with all escape sequences intact, encoded in a given charset.
See also:
QTextCodec::mibEnum()

prettyURL()

Definition at line 1415 of file kurl.cpp.

References hasHost(), hasPass(), and hasUser().

Referenced by KURL(), KDesktopFile::readURL(), and KURLDrag::urlToString().

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
Parameters:
_trailing -1 to strip a trailing '/' from the path, +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()

Definition at line 1475 of file kurl.cpp.

References hasUser().

Referenced by kdbgstream::operator<<().

QString KURL::prettyURL int  _trailing,
AdjustementFlags  _flags
const
 

Returns the URL as string, escaped for HTML.

Example:

http://localhost:8080/test.cgi?test=hello world&name=fred
Returns:
A human readable URL, with no non-necessary encodings/escaped characters. Password will not be shown.

Definition at line 1542 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.

Definition at line 1550 of file kurl.cpp.

bool KURL::isEmpty  )  const
 

Test to see if the KURL is empty.

Returns:
true if the URL is empty

Definition at line 602 of file kurl.cpp.

Referenced by KApplication::authorizeURLAction().

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

Definition at line 1790 of file kurl.cpp.

bool KURL::cmp const KURL u,
bool  ignore_trailing = false
const
 

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

Compares this url with u.

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

References equals().

bool KURL::equals const KURL u,
bool  ignore_trailing = false
const
 

Compares this url with u.

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

References isValid(), m_iPort, m_strHost, m_strPass, m_strProtocol, m_strQuery_encoded, m_strRef_encoded, m_strUser, and path().

Referenced by cmp().

bool KURL::isParentOf const KURL u  )  const
 

Checks whether 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)

Definition at line 1140 of file kurl.cpp.

References isValid(), m_iPort, m_strHost, m_strPass, m_strProtocol, m_strQuery_encoded, m_strRef_encoded, m_strUser, and path().

KURL::List KURL::split const QString _url  )  [static]
 

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.

Parameters:
_url The URL that has to be split.
Returns:
An empty list on error or the list of split URLs.
See also:
hasSubURL

Definition at line 1587 of file kurl.cpp.

Referenced by KURL(), and split().

KURL::List KURL::split const KURL _url  )  [static]
 

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.

Returns:
An empty list on error or the list of split URLs.
Parameters:
_url The URL that has to be split.
See also:
hasSubURL

Definition at line 1555 of file kurl.cpp.

References KURL(), and split().

KURL KURL::join const List _list  )  [static]
 

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

Definition at line 1592 of file kurl.cpp.

Referenced by KURL().

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
Since:
3.1

Definition at line 2165 of file kurl.cpp.

QString KURL::encode_string const QString str,
int  encoding_hint = 0
[static]
 

Convenience function.

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

Parameters:
str String to encode (can be QString::null).
encoding_hint MIB of encoding to use.
See also:
QTextCodec::mibEnum()
Returns:
the encoded string

Definition at line 2001 of file kurl.cpp.

Referenced by setFileEncoding(), and setFileName().

QString KURL::encode_string_no_slash const QString str,
int  encoding_hint = 0
[static]
 

Convenience function.

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

Parameters:
str String to encode
encoding_hint MIB of encoding to use.
See also:
QTextCodec::mibEnum()

Definition at line 2006 of file kurl.cpp.

QString KURL::decode_string const QString str,
int  encoding_hint = 0
[static]
 

Convenience function.

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

Reverse of encode_string()

Parameters:
str String to decode (can be QString::null).
encoding_hint MIB of original encoding of str .
See also:
QTextCodec::mibEnum()

Definition at line 1996 of file kurl.cpp.

Referenced by fileEncoding(), KApplication::invokeMailer(), and setFileEncoding().

bool KURL::isRelativeURL const QString _url  )  [static]
 

Convenience function.

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

Parameters:
_url URL to examine
Returns:
true when the URL is likely to be "relative", false otherwise.

Definition at line 375 of file kurl.cpp.

Referenced by KURL(), and KCmdLineArgs::makeURL().

QString KURL::relativeURL const KURL base_url,
const KURL url,
int  encoding_hint = 0
[static]
 

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 that if base_url represents a directory, it should contain a trailing slash.

Parameters:
base_url the URL to derive from
url new URL
encoding_hint MIB of original encoding of str .
See also:
QTextCodec::mibEnum()

adjustPath()

Definition at line 2229 of file kurl.cpp.

QString KURL::relativePath const QString base_dir,
const QString path,
bool *  isParent = 0
[static]
 

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 A pointer to a boolean which, if provided, will be set to reflect whether path has base_dir is a parent dir.

Definition at line 2215 of file kurl.cpp.

KURL::URIMode KURL::uriModeForProtocol const QString protocol  )  [static]
 

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

Parameters:
protocol The protocol name.
Since:
3.2

Definition at line 2267 of file kurl.cpp.


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


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdecore Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Fri Jan 21 09:57:15 2005 by doxygen 1.3.6 written by Dimitri van Heesch, © 1997-2003