KURL Class Reference

[kdecore Index] [kdecore Hierarchy] [Headers]


A class for URL processing. More...

#include <kurl.h>

Public Members

Protected Members


Detailed Description

A class for URL processing.

The KURL class deals with uniform resource locators in a protocol independent way. It works on file:-type URLs much like QDir does on normal directories; but KURL extends the directory operations to work on general URLs. In fact, the part of KURL that only deals with syntax doesn't care about the protocol at all, so feel free to use it to format any URL-like string. NOTE: KURL doesn't support URL's that don't look like files (for example mailto:someone@somewhere). [If URL's like this were OK, there would be no reason for isMalformed() since any string with a ":" would be a valid URL. Comments please.]

First version by Torben Weis, redesigned by Steffen Hansen (stefh@mip.ou.dk), maintained by Torben Weis (weis@kde.org). Endcoding/Decoding done by Stephan Kulow (coolo@kde.org).


KURL() [public]

Construct a KURL object.

KURL( const char* _url) [public]

Construct a KURL object from _url.

A KURL object is always constructed, but if you plan to use it, you should check it with isMalformed().

if the parameter is an absolute filename, it adds a file: prefix and encodes the path.

KURL( const char* _protocol, const char* _host, const char* _path, const char* _ref) [public]

Construct a KURL object from its components.

KURL( KURL & _base_url, const char* _rel_url ) [public]

Constructs a URL.

The second argument may be a relative URL, like '/home/weis/test.txt'. If for example the first parameter is 'http://uni-frankfurt/pub/incoming' then the result will be 'http://uni-frankfurt/home/weis/test.txt'.

Of course the second argument may be a complete URL, too.

bool isMalformed() const [public]

Returns true if the URL is not a valid URL. This is only syntax-checking; whether the resource to which the URL points exists is not checked.

NOTE: Syntax checking is only done when constructing a KURL from a string.

void encodeURL( QString& url ) [public static]

Escapes some reserved characters within URLs (e.g. '#', '%').

Some characters in filenames or directory names make troubles For example '#' or '%' makes problem, if they are interpreted and not ment to be interpreted. This why we must encode them. This functions encodes the given URL and returns a reference to the result for convidence.

void decodeURL( QString& url ) [public static]

Decodes escaped characters within URLs.

This function looks for '%' within the URL and replaces this character with hexcode of the next two characters. If the next characters are not hex chararcters, 0 will be used and the character will be skipped.

QString url() const [public]

Returns the URL as a QString.

const char* protocol() const [public]

The function returns the protocolname up to, but not including the ":".

const char* host() const [public]

This function returns the host. If there is no host (i.e. the URL refers to a local file) this function returns "".

const char* path() const [public]

This function returns the path-part of the URL.

For example, path() on "tar://ftp.foo.org/bar/stuff.tar.gz#tex/doc.tex" returns "/bar/stuff.tar.gz".

const char* httpPath() const [public]

This function returns the path-part of an URL and leaves it as is.

For example, path() on "http://www.foo.org/bar/cgi%2Dbin?value=blue%3f" returns "/bar/cgi%2Dbin".

bool hasPath() const [public]

If we parse for example ftp://weis@localhost then we dont have a path. The URL means: enter the home directory of user weis, while ftp://weis@localhost/ means, login as user weis and enter the root directory. KURL returns "/" as path in both cases. This function lets you distinguish both URLs. It returns true in the first case.

See Also:
bNoPath

const char* searchPart() const [public]

The search-part.

Returns:
the search-part, or NULL if no search-part was specified.

const char* reference() const [public]

This function returns the reference.

If the URL is "http://www.nowhere/path/file.html#toc", this function will return "toc". If there is no reference it returns "". If we have some subprotocol in the URL like in file:/tmp/kde.tgz#tar:/kfm.rpm#rpm:/doc/index.html#section then only the last reference is going to be returned, in this case "section". A URL like file:/tmp/kde.tgz#tar:/kfm.rpm#rpm:/doc/index.html would return "" since there is no reference. The stuff behind the '#' is a subprotocol!

const char* user() const [public]

This function returns the user name or an empty string if no user has been specified.

const char* passwd() const [public]

The password.

Returns:
the password, or an empty string if no password was specified.

unsigned int port() const [public]

The port number.

Returns:
the port number, or 0 if none was specified.

const char * directory( bool _trailing = TRUE ) [public]

Returns the directory only.

If for example the URL is "file:/tmp/weis/file.html", then this call will return "/tmp/weis/". If you pass "file:/tmp/weis/" to this function, you will get "/tmp/weis/", because you already passed a directory. Turning the '_trailing' flag off, causes the trailing '/' to be ignored. "file:/tmp/weis/file.html" will result in "/tmp/weis/", too, but "file:/tmp/weis/" will lead to "/tmp/". As you see, this is a smart method to get the parent directory of a file/directory.

This function is supplied for convenience only.

const char * directoryURL( bool _trailing = TRUE ) [public]

Returns the URL with the directory only.

If for example the URL is "file:/tmp/weis/file.html", then this call will return "file:/tmp/weis/". For more details look at 'directory(...)'

QString parentURL() [public]

If the URL has no subprotocol, parentURL behaves like a call to url Otherwise the part of the URL left to the last subprotocol is returned. For example file:/tmp/kde.tgz#tar:/kfm.rpm#rpm:/doc/index.html#section will return file:/tmp/kde.tgz#tar:/kfm.rpm. As you can see, the last subprotocol is stripped. If the original URL is for example file:/httpd/index.html#section then exact this string is going to be returned.

QString childURL() [public]

This call returnes the other part of the URL, the part that is stripped by parentURL It returns always the right most subprotocol. If there is no subprotocol, the call to this function returns an empty string. For example a URL file:/tmp/kde.tgz#tar:/kfm.rpm#rpm:/doc/index.html#section would return rpm:/doc/index.html#section.

QString nestedURL() [public]

This function behaves like childURL but if there is no subprotocol, this function returns the same url returns instead of an empty string.

void parse( const char *_url ) [public]

Parse a string.

void setProtocol( const char* newProto) [public]

Sets the protocol to newProto. Useful for example if an app hits "file:/tmp/interesting.zip", then it might do setProtocol( "zip").

void setPath( const char *newPath) [public]

Sets the path to newPath.

void setHost( const char *host) [public]

Sets the host

void setPassword( const char *password ) [public]

Set the password.

void setUser( const char *user ) [public]

Set the user.

void setPort( const unsigned int newPort ) [public]

Set the port.

void setSearchPart( const char *_searchPart ) [public]

Set the search-part.

The search part of an URL is the part behind the '?'. Example the URL "http://www.yahoo.com/search.cgi?country=netherland" has "country=netherland" as search-part

If NULL is specified, the search-part is cleared.

bool setReference( const char* _ref) [public]

Set reference.

A reference may be removed with setRef( ""). The function returns false if it could not make a reference (if there were no path to reference from) and true on succes.

bool cd( const char* _dir, bool zapRef = true) [public]

Changes directory by descending into the given directory. If dir starts with a "/" the current URL will be "protocol://host/dir" otherwise dir will be appended to the path. If 'zapRef' is true, the reference will be deleted.

bool cdUp( bool zapRef = true) [public]

Go to parent dir. If zapRef is true, the reference is removed, otherwise it stays, but normally no one would want that.

const char* filename() [public]

Returns the filename or directory name of the URL.

If 'file:/home/weis/test.txt' is the URL, the result will be 'test.txt' If the URL us 'tar:/home/weis/test.tgz#foo/myfile' and isReference is TRUE, the function will return 'myfile'

KURL& operator=( const KURL &) [public]

Makes a copy of a URL.

KURL& operator=( const char* _url ) [public]

Initialize the URL with the given string. '_url' must be a valid URL.

bool operator==( const KURL &_url) const [public]

Compare URL's.

Returns:
true if the URLs are equal, false otherwise.

bool isLocalFile() [public]

Checks, if the URL refers to a usual file, that can be openend with usual methods.

Note: It doesn't check, if the file exist

Returns:
true, if the URL is a file, that can be opened

bool bNoPath[protected]

If we parse for example ftp://weis@localhost then we dont have a path. The URL means: enter the home directory of user weis, while ftp://weis@localhost/ means, login as user weis and enter the root directory. KURL returns "/" as path in both cases. This variable is used to distinguish both URLs. It is true in the first case.

See Also:
hasPath

  • Author: Torben Weis (weis@kde.org)
  • Version: $Id: KURL.html.in,v 1.1.1.1 2000/02/09 22:25:02 tasin Exp $
  • Documentation generated by tasin@cd1 on Die Nov 30 17:31:35 CET 1999
Kdoc