class KURL

Represent and parse a URL. More...

Definition#include <kurl.h>
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Types

Public Methods

Public Static Methods

Protected Methods

Protected Static Methods


Detailed Description

Represent and parse a URL.

A prototypical URL looks like:

protocol:/user:password@hostname:port/path/to/file.ext#reference</pre>

  @ref KURL has some restrictions regarding the path
 encoding. @ref KURL works internally with the decoded path and
 and encoded query. For example,
 <pre>
 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 @bf not use "%00" in the path, although this is OK for the query.

KURL ()

Construct an empty URL.

KURL ( const QString& _url )

Usual constructor, to construct from a string.

Parameters:
_urlThis is considered to be encoded. You can pass strings like "/home/weis", and the protocol "file" is assumed. This is dangerous since even this simple path is assumed to be encoded. For example "/home/Torben%20Weis" will be decoded to "/home/Torben Weis". This means: If you have a usual UNIX like path, you have to use encode() first before you pass it to KURL.

KURL ( const KURL& _u )

Copy constructor

KURL ( const QUrl &u )

Convert from a QUrl.

KURL ( const KURL& _baseurl, const QString& _rel_url )

Constructor allowing relative URLs.

Example : KURL u( QDir::currentDirPath()+"/", _url ) Very useful for command-line parameters, where people tend to do "myprog myfile.ext"

Parameters:
_baseurlThe base url.
_rel_urlThis is considered to be encoded. If an absolute path/URL, then _baseurl will be ignored.

QString protocol ()
[const]

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

void setProtocol ( const QString& _txt )

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

QString user ()
[const]

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

void setUser ( const QString& _txt )

Set the user name (login, user id, ...) included the URL.

bool hasUser ()
[const]

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

QString pass ()
[const]

Retrieve the password (corresponding to user()) included in the URL.

void setPass ( const QString& _txt )

Set the password (corresponding to user()) included in the URL.

bool hasPass ()
[const]

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

QString host ()
[const]

Retrieve the hostname included in the URL.

void setHost ( const QString& _txt )

Set the hostname included in the URL.

bool hasHost ()
[const]

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

unsigned short int port ()
[const]

Retrieve the port number included in the URL.

void setPort ( unsigned short int _p )

Set the port number included in the URL.

QString path ()
[const]

Returns: The current decoded path. This does @bf not include the query.

QString path ( int _trailing )
[const]

Parameters:
_trailingMay 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.

void setPath ( const QString& path )

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. The query is not changed by this function.

bool hasPath ()
[const]

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

void cleanPath ()

Removes all multiple directory separators ('/') and resolves any "." or ".." found in the path. Calls QDir::cleanDirPath but saves the trailing slash if any.

void setEncodedPathAndQuery ( const QString& _txt )

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.

QString encodedPathAndQuery ( int _trailing = 0, bool _no_empty_path = false )

Parameters:
_no_empty_pathIf set to true then an empty path is substituted by "/".

Returns: The concatenation if the encoded path , '?' and the encoded query.

void setQuery ( const QString& _txt )

Parameters:
_txtThis is considered to be encoded. This has a good reason: The query may contain the 0 character.

QString query ()
[const]

Returns: The encoded query. This has a good reason: The query may contain the 0 character.

QString ref ()
[const]

The reference is @bf never decoded automatically.

void setRef ( const QString& _txt )

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

Parameters:
_txtis considered encoded.

bool hasRef ()
[const]

Returns: true if the reference part of the URL is not empty. In a URL like tar:/kde/README#http://www.kde.org/kdebase.tgz it would return true, too.

QString htmlRef ()
[const]

Returns: The HTML-style reference. The HTML-style reference can only be the last of all references. For example in tar:/#gzip:/decompress#file:/home/x.tgz#ref1 the return value would be ref because it is the last reference and follows a source protocol. In contrast tar:/#gzip:/decompress#file:/home/x.tgz has no HTML-style reference at all since file:/home/x.tgz is a sub URL to the filter protocol gzip. The returned string is, in contrast to ref() already decoded.

void setHTMLRef ( const QString& _ref )

Set the HTML-style reference.

Parameters:
_refThis is considered to be @bf not encoded in contrast to setRef()

bool hasHTMLRef ()
[const]

Returns: true if the URL has an HTML-style reference.

bool isMalformed ()
[const]

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

bool isLocalFile ()
[const]

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

bool hasSubURL ()
[const]

The function tests whether the protocol is a filter protocol and whether the reference is not empty. For performance reasons it does @bf not test whether the reference is in turn a well-formed URL.

Returns: true if the file has at least one sub URL. Use split() to get the sub URLs.

void addPath ( const QString& _txt )

Add 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:
_txtThis is considered to be decoded

void setFileName ( const QString&_txt )

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

Parameters:
_txtThis is considered to be decoded. If the current path ends with '/' then _txt ist 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.

QString filename ( bool _ignore_trailing_slash_in_path = true )
[const]

Parameters:
_ignore_trailing_slash_in_pathThis tells whether a trailing '/' should be ignored. This means that the function would return "torben" for <tt>file:/hallo/torben/</tt> and <tt>file:/hallo/torben</tt>. 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.

QString directory ( bool _strip_trailing_slash_from_result = true, bool _ignore_trailing_slash_in_path = true )
[const]

Parameters:
_strip_trailing_slash_from_resulttells 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_pathmeans that <tt>file:/hallo/torben</tt> and <tt>file:/hallo/torben/"</tt> would both return <tt>/hallo/</tt> or <tt>/hallo</tt> 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 <tt>file:/hallo/torben/</tt> would return "/hallo/torben/" while <tt>file:/hallo/torben</tt> would return "hallo/". The returned string is decoded.

bool cd ( const QString& _dir, bool zapRef = true )

Change 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 tar:/#file:/dir/dir2/my.tgz and you do cd("..") you will still be in tar:/#file:/dir/dir2/my.tgz.

Parameters:
zapRefIf true, delete the HTML-style reference.

QString url ()
[const]

Returns: The complete encoded URL.

QString url ( int _trailing )
[const]

Parameters:
_trailingThis 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.

Returns: The complete encoded URL.

bool isEmpty ()
[const]

Test to see if the KURL is empty.

KURL upURL ( bool _zapRef = true )
[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 tar:/#gzip:/decompress#file:/home/x.tgz and hit the up button you expect to see file:/home. The algorithm tries to go up on the left-most URL. If that is not possible it strips the left most URL. It continues stripping URLs as they use stream protocols. If it finds the first protocol implementing a directory structure, in this case "file", it tries to step up there, and so on. One more example: tar:/#gzip:/decompress#tar:/dir/x.tgz#gzip:/decompress#http://www/my.tgz will be returned as tar:/dir#gzip:/decompress#http://www/my.tgz.

Parameters:
_zapRefThis tells whether the HTML-style reference should be stripped.

bool cmp ( const KURL &_u, bool _ignore_trailing = false )

This function should be used if you want to ignore trailing '/' characters.

List split ( const QString& _url )
[static]

Splits nested URLs like tar:/kdebase#gzip:/decompress#file:/home/weis/kde.tgz. A URL like tar:/kde/README.html#http://www.kde.org#ref1 will be split in tar:/kde/README.html#ref1 and http://www.kde.org. That is because http is a source protocol and not a filter protocol. 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 the first 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:
_urlThe URL that has to be split.

Returns: An empty list on error or the list of split URLs.

List split ( const KURL& _url )
[static]

A convenience function.

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

void decode ( QString& _url )
[static]

Decode the string, this means decoding "%20" into a space for example. Note that "%00" is not handled correctly here.

void encode ( QString& _url )
[static]

Reverse of decode()


Generated by: root@tantive.terraplex.com on Sun Feb 27 17:39:19 2000, using kdoc 2.0a33.