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


Detailed Description

Represent and parse a URL.

A prototypical URL looks like:


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

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.

List (class)

 KURL ()

Construct an empty URL.

KURL ()

destruktor

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

Usual constructor, to construct from a string.

Parameters:

 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.

 KURL ( const KURL& u )

Copy constructor

 KURL ( const QUrl &u )

Convert from a QUrl.

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

Constructor allowing relative URLs.

Parameters:

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 decoded user name (login, user id, ...) included in the URL.

void  setUser ( const QString& _txt )

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

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

bool  hasUser ()

[const]

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

QString  pass ()

[const]

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

void  setPass ( const QString& _txt )

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

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

bool  hasPass ()

[const]

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

QString  host ()

[const]

Retrieve the decoded hostname included in the URL.

void  setHost ( const QString& _txt )

Set the hostname included in the URL.

Special characters in the hostname will appear encoded 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 not include the query.

QString  path ( int _trailing )

[const]

Parameters:

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, 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:

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

[const]

Parameters:

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

void  setQuery ( const QString& _txt, int encoding_hint = 0)

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

Parameters:

QString  query ()

[const]

Returns: The encoded query. This has a good reason: 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.

QString  ref ()

[const]

The reference is never decoded automatically.

void  setRef ( const QString& _txt )

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

Parameters:

bool  hasRef ()

[const]

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

QString  htmlRef ()

[const]

Returns: The HTML-style reference.

void  setHTMLRef ( const QString& _ref )

Set the HTML-style reference.

Parameters:

bool  hasHTMLRef ()

[const]

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

bool  isValid ()

[const]

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

bool  isMalformed ()

[const]

bool  isLocalFile ()

[const]

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

bool  hasSubURL ()

[const]

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:

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

Any reference is reset.

Parameters:

QString  fileName ( bool _ignore_trailing_slash_in_path = true )

[const]

Parameters:

Returns: The filename of the current path. The returned string is decoded.

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]

Parameters:

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 )

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

Returns: true

QString  url ( int _trailing = 0 )

[const]

Parameters:

Returns: The complete URL, with all escape sequences intact. Example: http://localhost:8080/test.cgi?test=hello%20world&name=fred

QString  url ( int _trailing, int encoding_hint )

[const]

Parameters:

Returns: The complete URL, 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.

QString  prettyURL ( int _trailing = 0)

[const]

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

bool  isEmpty ()

[const]

Test to see if the KURL is empty.

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.

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]

Compare this url with u

Parameters:

Returns: true if both urls are the same

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

bool  isParentOf ( const KURL& u )

[const]

Returns: true if this url is a parent of u (or the same URL as u) For instance, ftp://host/dir/ is a parent of ftp://host/dir/subdir/subsubdir/.

List  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:

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

List  split ( const KURL& _url )

[static]

A convenience function.

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.

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

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

QString  decode_string (const QString &str, int encoding_hint = 0)

[static]

Convenience function

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

Revers of encode_string()

Parameters:

bool  isRelativeURL (const QString &_url)

[static]

Convenience function

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

Parameters:

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

void  reset ()

[protected]

void  parse ( const QString& _url, int encoding_hint = 0)

[protected]