org.kde.koala

Class KURL

public class KURL extends Object implements QtSupport

Author: Torben Weis

UNKNOWN: 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 @c '#' is used to specify a "reference", i.e. the position within a document) - space . "%20" The constructor KURL(String) 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(String): KURL kurl; kurl.setPath( "/bar/#foo#" ); String 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() ) String 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: String dirUrl = "file:///bar/"; String fileName = "#foo#"; String invalidURL = dirUrl + fileName; // . "file:///bar/#foo#" won't behave like you would expect. Instead you should use addPath(). Right: KURL url( "file:///bar/" ); String fileName = "#foo#"; url.addPath( fileName ); String 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"); String 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. @brief Represents and parses a URL

Field Summary
static intAuto
Defines the type of URI we are processing.
static intCaseInsensitiveKeys
Options for queryItems()
static intInvalid
static intMailto
static intNoAdjustements
Flags to choose how file: URLs are treated when creating their String representation with prettyURL(int,AdjustementFlags) However it is recommended to use pathOrURL() instead of this variant of prettyURL()
static intRawURI
static intStripFileProtocol
static intURL
Constructor Summary
protected KURL(Class dummy)
KURL()
KURL(String url, int encoding_hint)
KURL(String url)
KURL(KURL u)
KURL(QUrlInterface u)
KURL(KURL _baseurl, String _rel_url, int encoding_hint)
KURL(KURL _baseurl, String _rel_url)
Method Summary
voidaddPath(String txt)
voidaddQueryItem(String _item, String _value, int encoding_hint)
voidaddQueryItem(String _item, String _value)
voidadjustPath(int _trailing)
booleancd(String _dir)
voidcleanPath(boolean cleanDirSeparator)
voidcleanPath()
static Stringdecode_string(String str, int encoding_hint)
static Stringdecode_string(String str)
Stringdirectory(boolean _strip_trailing_slash_from_result, boolean _ignore_trailing_slash_in_path)
Stringdirectory(boolean _strip_trailing_slash_from_result)
Stringdirectory()
voiddispose()
Delete the wrapped C++ instance ahead of finalize()
StringencodedHtmlRef()
StringencodedPathAndQuery(int _trailing, boolean _no_empty_path, int encoding_hint)
StringencodedPathAndQuery(int _trailing, boolean _no_empty_path)
StringencodedPathAndQuery(int _trailing)
StringencodedPathAndQuery()
static Stringencode_string(String str, int encoding_hint)
static Stringencode_string(String str)
static Stringencode_string_no_slash(String str, int encoding_hint)
static Stringencode_string_no_slash(String str)
booleanequals(KURL u, boolean ignore_trailing)
booleanequals(KURL u)
StringfileEncoding()
StringfileName(boolean _ignore_trailing_slash_in_path)
StringfileName()
protected voidfinalize()
Deletes the wrapped C++ instance
static KURLfromPathOrURL(String text)
booleanhasHost()
booleanhasHTMLRef()
booleanhasPass()
booleanhasPath()
booleanhasRef()
booleanhasSubURL()
booleanhasUser()
Stringhost()
StringhtmlRef()
StringhtmlURL()
booleanisDisposed()
Has the wrapped C++ instance been deleted?
booleanisEmpty()
booleanisLocalFile()
booleanisParentOf(KURL u)
static booleanisRelativeURL(String _url)
booleanisValid()
static KURLjoin(ArrayList _list)
booleanop_equals(KURL _u)
booleanop_equals(String _u)
booleanop_lt(KURL _u)
booleanop_not_equals(KURL _u)
booleanop_not_equals(String _u)
protected voidparse(String _url, int encoding_hint)
protected voidparse(String _url)
protected voidparseMailto(String _url, int encoding_hint)
protected voidparseMailto(String _url)
protected voidparseRawURI(String _url, int encoding_hint)
protected voidparseRawURI(String _url)
protected voidparseURL(String _url, int encoding_hint)
protected voidparseURL(String _url)
Stringpass()
Stringpath()
Stringpath(int _trailing)
StringpathOrURL()
shortport()
StringprettyURL(int _trailing)
StringprettyURL()
StringprettyURL(int _trailing, int _flags)
Stringprotocol()
Stringquery()
StringqueryItem(String item)
StringqueryItem(String item, int encoding_hint)
Stringref()
static StringrelativePath(String base_dir, String path, boolean[] isParent)
static StringrelativePath(String base_dir, String path)
static StringrelativeURL(KURL base_url, KURL url, int encoding_hint)
static StringrelativeURL(KURL base_url, KURL url)
voidremoveQueryItem(String _item)
protected voidreset()
voidsetDirectory(String dir)
voidsetEncodedPath(String _txt, int encoding_hint)
voidsetEncodedPath(String _txt)
voidsetEncodedPathAndQuery(String _txt, int encoding_hint)
voidsetEncodedPathAndQuery(String _txt)
voidsetFileEncoding(String encoding)
voidsetFileName(String _txt)
voidsetHost(String _txt)
voidsetHTMLRef(String _ref)
voidsetPass(String _txt)
voidsetPath(String path)
voidsetPort(short _p)
voidsetProtocol(String _txt)
voidsetQuery(String _txt, int encoding_hint)
voidsetQuery(String _txt)
voidsetRef(String _txt)
voidsetUser(String _txt)
static ArrayListsplit(String _url)
static ArrayListsplit(KURL _url)
KURLupURL()
inturiMode()
static inturiModeForProtocol(String protocol)
Stringurl(int _trailing, int encoding_hint)
Stringurl(int _trailing)
Stringurl()
Stringuser()

Field Detail

Auto

public static final int Auto
Defines the type of URI we are processing.

UNKNOWN: Defines the type of URI we are processing.

CaseInsensitiveKeys

public static final int CaseInsensitiveKeys
Options for queryItems()

UNKNOWN: Options for queryItems()

Invalid

public static final int Invalid

Mailto

public static final int Mailto

NoAdjustements

public static final int NoAdjustements
Flags to choose how file: URLs are treated when creating their String representation with prettyURL(int,AdjustementFlags) However it is recommended to use pathOrURL() instead of this variant of prettyURL()

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

RawURI

public static final int RawURI

StripFileProtocol

public static final int StripFileProtocol

URL

public static final int URL

Constructor Detail

KURL

protected KURL(Class dummy)

KURL

public KURL()

UNKNOWN: Constructs an empty URL The created instance will also be invalid, see isValid() @brief Constructs an empty URL

KURL

public KURL(String url, int encoding_hint)

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

See Also: KURL

UNKNOWN: Usual constructor, to construct from a string 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() @brief Usual constructor, to construct from a string

KURL

public KURL(String url)

KURL

public KURL(KURL u)

Parameters: u the KURL to copy

UNKNOWN: Copy constructor @brief Copy constructor

KURL

public KURL(QUrlInterface u)

Parameters: u the QUrl

UNKNOWN: Constructor taking a Qt URL Converts from a Qt URL. @brief Constructor taking a Qt URL

KURL

public KURL(KURL _baseurl, String _rel_url, int encoding_hint)

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

UNKNOWN: Constructor allowing relative URLs 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() @brief Constructor allowing relative URLs

KURL

public KURL(KURL _baseurl, String _rel_url)

Method Detail

addPath

public void addPath(String txt)

Parameters: txt the text to add. It is considered to be decoded

See Also: KURL KURL

UNKNOWN: Adds to the current path Assumes that the current path is a directory. _txt is appended to the current path. The function adds @c '/' 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 @c '/' then this one is stripped. @brief Adds to the current path

addQueryItem

public void addQueryItem(String _item, String _value, int encoding_hint)

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

UNKNOWN: Adds an additional query item To replace an existing query item, the item should first be removed with removeQueryItem() @brief Adds an additional query item

addQueryItem

public void addQueryItem(String _item, String _value)

adjustPath

public void adjustPath(int _trailing)

Parameters: _trailing May be ( @c -1, 0, @c +1 ). @c -1 strips a trailing

See Also: KURL KURL

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

cd

public boolean cd(String _dir)

Parameters: _dir the directory to change to

Returns: @c true if successful

See Also: KURL KURL

UNKNOWN: Changes the directory by descending into the given directory It is assumed the current URL represents a directory. If _dir starts with a @c '/' the current URL will be "protocol://host/dir" otherwise _dir will be appended to the path. _dir can be @c ".." 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:/" @brief Changes the directory by descending into the given directory

cleanPath

public void cleanPath(boolean cleanDirSeparator)

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

See Also: KURL KURL

UNKNOWN: Resolves @c "." and @c ".." components in path Some servers seem not to like the removal of extra @c '/' even though it is against the specification in RFC 2396. @brief Resolves @c ".

cleanPath

public void cleanPath()

decode_string

public static String decode_string(String str, int encoding_hint)

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

Returns: the decoded string

See Also: KURL KURL

UNKNOWN: Decodes a string as used in URLs Convenience function. Decode %-style encoding and convert from local encoding to unicode. Reverse of encode_string() @brief Decodes a string as used in URLs

decode_string

public static String decode_string(String str)

directory

public String directory(boolean _strip_trailing_slash_from_result, boolean _ignore_trailing_slash_in_path)

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

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

See Also: KURL KURL KURL

UNKNOWN: Returns the directory of the path The directory is everything between the last and the second last @c '/' 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 @c '/' should be ignored. This means that the function would return @c "/hallo" (or @c "/hallo" depending on _strip_trailing_slash_from_result) for "file:///hallo/torben/" and "file:///hallo/torben". @brief Returns the directory of the path

directory

public String directory(boolean _strip_trailing_slash_from_result)

directory

public String directory()

dispose

public void dispose()
Delete the wrapped C++ instance ahead of finalize()

encodedHtmlRef

public String encodedHtmlRef()

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

See Also: KURL KURL KURL

UNKNOWN: Returns the encoded HTML-style reference (the part of the URL after @c '#') @brief Returns the encoded HTML-style reference (the part of the URL after @c '#')

encodedPathAndQuery

public String encodedPathAndQuery(int _trailing, boolean _no_empty_path, int encoding_hint)

Parameters: _trailing May be ( @c -1, 0, @c +1 ). @c -1 strips a trailing _no_empty_path if set to true then an empty path is substituted by @c "/" encoding_hint MIB of desired encoding of URL. See QTextCodec.mibEnum()

Returns: the concatenation of the encoded path , @c '?' and the encoded query

See Also: KURL KURL KURL

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

encodedPathAndQuery

public String encodedPathAndQuery(int _trailing, boolean _no_empty_path)

encodedPathAndQuery

public String encodedPathAndQuery(int _trailing)

encodedPathAndQuery

public String encodedPathAndQuery()

encode_string

public static String encode_string(String str, int encoding_hint)

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

Returns: the encoded string

See Also: KURL KURL

UNKNOWN: 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. @brief Encodes a string for use in URLs

encode_string

public static String encode_string(String str)

encode_string_no_slash

public static String encode_string_no_slash(String str, int encoding_hint)

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

See Also: KURL KURL

UNKNOWN: 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 @c '/'. @brief Encodes a string for use in URLs

encode_string_no_slash

public static String encode_string_no_slash(String str)

equals

public boolean equals(KURL u, boolean ignore_trailing)

Parameters: u the URL to compare this one with ignore_trailing set to true to ignore trailing @c '/' characters

Returns: @c true if both urls are the same

See Also: ==# This KURL KURL KURL KURL KURL KURL KURL KURL KURL KURL @c KURL

UNKNOWN: Compares this URL with another one @brief Compares this URL with another one

equals

public boolean equals(KURL u)

fileEncoding

public String fileEncoding()

Returns: an encoding suitable for QTextCodec.codecForName() or @c null if not encoding was specified

UNKNOWN: Returns encoding information of the URL The encoding information is the content of the @c "charset" parameter. @brief Returns encoding information of the URL

fileName

public String fileName(boolean _ignore_trailing_slash_in_path)

Parameters: _ignore_trailing_slash_in_path if set to false, then everything behind the last @c '/' is considered to be the filename

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

See Also: KURL KURL KURL

UNKNOWN: Returns the filename of the path _ignore_trailing_slash_in_path tells whether a trailing @c '/' should be ignored. This means that the function would return @c "torben" for "file:///hallo/torben/" and "file:///hallo/torben". null if there is no file (and thus no path) @brief Returns the filename of the path

fileName

public String fileName()

finalize

protected void finalize()
Deletes the wrapped C++ instance

fromPathOrURL

public static KURL fromPathOrURL(String text)

Parameters: text the string representation of the URL to convert

Returns: the new KURL

See Also: KURL (const )

UNKNOWN: Creates a KURL object from a String representing either an absolute path or a real URL Use this method instead of String someDir = ... KURL url = someDir; Otherwise some characters (e.g. the '#') won't be encoded properly. @brief Creates a KURL object from a String representing either an absolute path or a real URL

hasHost

public boolean hasHost()

Returns: @c true if the URL has a non-empty host

See Also: KURL KURL

UNKNOWN: Tests if this URL has a hostname included in it @brief Tests if this URL has a hostname included in it

hasHTMLRef

public boolean hasHTMLRef()

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

See Also: KURL KURL KURL KURL

UNKNOWN: Tests if there is an HTML-style reference @brief Tests if there is an HTML-style reference

hasPass

public boolean hasPass()

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

See Also: KURL KURL KURL

UNKNOWN: Tests if this URL has a password included in it a password can only appear in a URL string if you also set a user, see setUser(). @brief Tests if this URL has a password included in it

hasPath

public boolean hasPath()

Returns: @c true if there is a non-empty path

See Also: KURL KURL

UNKNOWN: Tests if this URL has a path included in it @brief Tests if this URL has a path included in it

hasRef

public boolean hasRef()

Returns: @c true if the URL has a reference part. In a URL like "http://www.kde.org/kdebase.tar#tar:/README" it would return @c true as well

See Also: KURL KURL

UNKNOWN: Tests if the URL has a reference part @brief Tests if the URL has a reference part

hasSubURL

public boolean hasSubURL()

Returns: @c true if the file has at least one sub URL

See Also: KURL

UNKNOWN: Tests if the URL has any sub URLs See split() for examples for sub URLs. @brief Tests if the URL has any sub URLs

hasUser

public boolean hasUser()

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

See Also: KURL KURL KURL

UNKNOWN: Tests if this URL has a user name included in it @brief Tests if this URL has a user name included in it

host

public String host()

Returns: the name of the host or @c null if no host is set

See Also: KURL KURL

UNKNOWN: Returns the decoded hostname included in the URL @brief Returns the decoded hostname included in the URL

htmlRef

public String htmlRef()

Returns: the HTML-style reference

See Also: KURL KURL KURL KURL KURL KURL

UNKNOWN: Returns decoded the HTML-style reference (the part of the URL after @c '#') @brief Returns decoded the HTML-style reference (the part of the URL after @c '#')

htmlURL

public String htmlURL()

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

UNKNOWN: Returns the URL as string, escaped for HTML @brief Returns the URL as string, escaped for HTML

isDisposed

public boolean isDisposed()
Has the wrapped C++ instance been deleted?

isEmpty

public boolean isEmpty()

Returns: @c true if the URL is empty

See Also: KURL KURL KURL

UNKNOWN: Tests if the KURL is empty An empty URL has neither path nor protocol set. @brief Tests if the KURL is empty

isLocalFile

public boolean isLocalFile()

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

UNKNOWN: Tests if the file is local @brief Tests if the file is local

isParentOf

public boolean isParentOf(KURL u)

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

See Also: KURL KURL

UNKNOWN: Tests if the given URL is parent of this URL For instance, "ftp://host/dir/" is a parent of "ftp://host/dir/subdir/subsubdir/". @brief Tests if the given URL is parent of this URL

isRelativeURL

public static boolean isRelativeURL(String _url)

Parameters: _url the URL to examine

Returns: @c true when the URL is likely to be "relative",

See Also: KURL

UNKNOWN: 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. false otherwise @brief Tests if a given URL is a relative as opposed to an absolute URL

isValid

public boolean isValid()

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

UNKNOWN: Tests if the URL is well formed @brief Tests if the URL is well formed

join

public static KURL join(ArrayList _list)

Parameters: _list the list to join

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

See Also: KURL

UNKNOWN: 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. @brief Joins a list of URLs into a single URL with sub URLs

op_equals

public boolean op_equals(KURL _u)

Parameters: _u the URL to compare to

Returns: @c true if equal and neither this URL nor _u is malformed. Otherwise @c false

See Also: KURL KURL != <

UNKNOWN: 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) @brief Tests if this URL is equal to the given one

op_equals

public boolean op_equals(String _u)

Parameters: _u the string to compare to

Returns: @c true if equal and neither this URL nor _u is malformed. Otherwise @c false

See Also: (const ) ==(const KURL KURL KURL != <

UNKNOWN: 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. @brief Tests if this URL is equal to the one given as a string

op_lt

public boolean op_lt(KURL _u)

Parameters: _u the URL to compare to

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

See Also: ==

UNKNOWN: 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; boolean lessThan = url1 < url2; // false. Both invalid, no protocols url2.setProtocol( null ); lessThan = url1 < url2; // true. url2 is valid because of setProtocol() url1.setProtocol( 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 @brief Tests if this URL is less than the given URL

op_not_equals

public boolean op_not_equals(KURL _u)

Parameters: _u the URL to compare to

Returns: the negated result of operator==()

See Also: == <

UNKNOWN: Tests if this URL is different from the given one Tests by negating the result of operator==() @brief Tests if this URL is different from the given one

op_not_equals

public boolean op_not_equals(String _u)

Parameters: _u the URL to compare to

Returns: the negated result of operator==(String)

See Also: ==(const <

UNKNOWN: Tests if this URL is different from the one given as a string Tests by negating the result of operator==(String) @brief Tests if this URL is different from the one given as a string

parse

protected void parse(String _url, int encoding_hint)

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

UNKNOWN: Parses the given string and fills the URL's values on success @brief Parses the given string and fills the URL's values on success

parse

protected void parse(String _url)

parseMailto

protected void parseMailto(String _url, int encoding_hint)

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

UNKNOWN: Parses the given string and fills the URL's values on success Treats the string as a @c "mailto:" URI. @brief Parses the given string and fills the URL's values on success

parseMailto

protected void parseMailto(String _url)

parseRawURI

protected void parseRawURI(String _url, int encoding_hint)

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

UNKNOWN: Parses the given string and fills the URL's values on success Treats the string as a generic URI. @brief Parses the given string and fills the URL's values on success

parseRawURI

protected void parseRawURI(String _url)

parseURL

protected void parseURL(String _url, int encoding_hint)

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

UNKNOWN: Parses the given string and fills the URL's values on success Treats the string as an URL. @brief Parses the given string and fills the URL's values on success

parseURL

protected void parseURL(String _url)

pass

public String pass()

Returns: the password or @c null if it does not exist

See Also: KURL KURL KURL

UNKNOWN: Returns the decoded password (corresponding to user()) included in the URL a password can only appear in a URL string if you also set a user, see setUser(). @brief Returns the decoded password (corresponding to user()) included in the URL

path

public String path()

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

See Also: KURL KURL KURL

UNKNOWN: Returns the current decoded path This does not include the query. @brief Returns the current decoded path

path

public String path(int _trailing)

Parameters: _trailing May be ( @c -1, 0, @c +1 ). @c -1 strips a trailing

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

See Also: KURL KURL KURL KURL

UNKNOWN: 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) @c '/' character in the path. If the URL has no path, then no @c '/' is added anyway. And on the other side: if the path is just @c "/", 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. '/', @c +1 adds a trailing @c '/' if there is none yet and 0 returns the path unchanged @brief Returns the current decoded path

pathOrURL

public String pathOrURL()

Returns: the path or URL string depending on its properties

See Also: KURL KURL KURL KURL

UNKNOWN: 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. @brief Returns the URL as a string depending if it is a local file

port

public short port()

Returns: the port number or @c 0 if there is no port number specified in the URL

See Also: KURL KURL

UNKNOWN: Returns the port number included in the URL @brief Returns the port number included in the URL

prettyURL

public String prettyURL(int _trailing)

Parameters: _trailing May be ( @c -1, 0, @c +1 ). @c -1 strips a trailing

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

See Also: KURL KURL

UNKNOWN: 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) @c '/' character in the path. If the URL has no path, then no @c '/' is added anyway. And on the other side: if the path is just @c "/", 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. '/', @c +1 adds a trailing @c '/' if there is none yet and 0 returns the path unchanged @brief Returns the URL as string in human-friendly format

prettyURL

public String prettyURL()

prettyURL

public String prettyURL(int _trailing, int _flags)

Parameters: _trailing May be ( @c -1, 0, @c +1 ). @c -1 strips a trailing _flags if StripFileProtocol, @c "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: KURL KURL KURL

UNKNOWN: 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) @c '/' character in the path. If the URL has no path, then no @c '/' is added anyway. And on the other side: if the path is just @c "/", 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. '/', @c +1 adds a trailing @c '/' if there is none yet and 0 returns the path unchanged @brief Returns the URL as string in human-friendly format Example: @code http://localhost:8080/test.

protocol

public String protocol()

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

See Also: KURL KURL

UNKNOWN: Returns the protocol for the URL Examples for a protocol string are @c "file", @c "http", etc. but also "mailto:" and other pseudo protocols. @brief Returns the protocol for the URL

query

public String query()

Returns: the encoded query or @c null if there is none

See Also: KURL

UNKNOWN: Returns the encoded query of the URL The query may contain the @c '0' character. If a query is present it always starts with a @c '?'. A single @c '?' means an empty query. An empty string means no query. @brief Returns the encoded query of the URL

queryItem

public String queryItem(String item)

Parameters: item item whose value we want

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

See Also: KURL KURL KURL KURL

UNKNOWN: Returns the value of a certain query item @brief Returns the value of a certain query item

queryItem

public String queryItem(String item, int encoding_hint)

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 @c null if the specified item does not exist

See Also: KURL KURL KURL KURL

UNKNOWN: Returns the value of a certain query item @brief Returns the value of a certain query item

ref

public String ref()

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

See Also: KURL KURL KURL

UNKNOWN: Returns the encoded reference of the URL The reference is never decoded automatically. @brief Returns the encoded reference of the URL

relativePath

public static String relativePath(String base_dir, String path, boolean[] isParent)

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

See Also: KURL

UNKNOWN: 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. @brief Creates a path relative to a base path for a given input path

relativePath

public static String relativePath(String base_dir, String path)

relativeURL

public static String relativeURL(KURL base_url, KURL url, int encoding_hint)

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

UNKNOWN: 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. if base_url represents a directory, it should contain a trailing slash @brief Creates an URL relative to a base URL for a given input URL

relativeURL

public static String relativeURL(KURL base_url, KURL url)

removeQueryItem

public void removeQueryItem(String _item)

Parameters: _item name of item to remove

See Also: KURL KURL KURL KURL

UNKNOWN: Removea an item from the query @brief Removea an item from the query

reset

protected void reset()

See Also: KURL KURL

UNKNOWN: Resets the members to their "null" state All String members get reset to 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. @brief Resets the members to their "null" state

setDirectory

public void setDirectory(String dir)

Parameters: dir the decoded directory to set

See Also: KURL KURL KURL

UNKNOWN: Sets the directory of the path, leaving the filename empty @brief Sets the directory of the path, leaving the filename empty

setEncodedPath

public void setEncodedPath(String _txt, int encoding_hint)

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

See Also: KURL KURL

UNKNOWN: Sets the (already encoded) path of the URL @brief Sets the (already encoded) path of the URL

setEncodedPath

public void setEncodedPath(String _txt)

setEncodedPathAndQuery

public void setEncodedPathAndQuery(String _txt, int encoding_hint)

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

See Also: KURL KURL KURL

UNKNOWN: Sets both path and query of the URL in their encoded form This is useful for HTTP. It looks first for @c '?' and decodes then, see setEncodedPath(). The encoded path is the concatenation of the current path and the query. @brief Sets both path and query of the URL in their encoded form

setEncodedPathAndQuery

public void setEncodedPathAndQuery(String _txt)

setFileEncoding

public void setFileEncoding(String encoding)

Parameters: encoding the encoding to add or null to remove the encoding

See Also: KURL org.kde.qt.QTextCodec#codecForName

UNKNOWN: Adds file encoding information Adds encoding information to the URL by adding a @c "charset" parameter. If there is already a charset parameter, it will be replaced. @brief Adds file encoding information

setFileName

public void setFileName(String _txt)

Parameters: _txt the filename to be set. It is considered to be decoded

See Also: KURL KURL KURL

UNKNOWN: 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 @c '/'. If the current path ends with @c '/' then _txt is just appended, otherwise all text behind the last @c '/' in the current path is erased and _txt is appended then. It does not matter whether _txt starts with @c '/' or not. Any reference is reset. @brief Sets the filename of the path

setHost

public void setHost(String _txt)

Parameters: _txt the new name of the host or null to remove the host

See Also: KURL KURL

UNKNOWN: Sets the hostname to include in the URL Special characters in the hostname will appear encoded in the URL. @brief Sets the hostname to include in the URL

setHTMLRef

public void setHTMLRef(String _ref)

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

See Also: KURL KURL

UNKNOWN: Sets the decoded HTML-style reference @brief Sets the decoded HTML-style reference

setPass

public void setPass(String _txt)

Parameters: _txt the password to set or null to remove the password

See Also: KURL KURL KURL

UNKNOWN: Sets the password (corresponding to user()) to include in the URL Special characters in the password will appear encoded in the URL. a password can only appear in a URL string if you also set a user, see setUser(). @brief Sets the password (corresponding to user()) to include in the URL

setPath

public void setPath(String path)

Parameters: path the new, decoded, path or null to remove the path

See Also: KURL KURL KURL

UNKNOWN: 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 @c '?' will be encoded and does not indicate the beginning of the query part. Something that might look encoded, like @c "%3f" will not become decoded. @brief Sets the decoded path of the URL

setPort

public void setPort(short _p)

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

See Also: KURL KURL

UNKNOWN: Sets the port number to include in the URL @brief Sets the port number to include in the URL

setProtocol

public void setProtocol(String _txt)

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

See Also: KURL

UNKNOWN: Sets the protocol for the URL Examples for a protocol string are @c "file", @c "http", etc. but also "mailto:" and other pseudo protocols. @brief Sets the protocol for the URL

setQuery

public void setQuery(String _txt, int encoding_hint)

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

See Also: KURL

UNKNOWN: Sets the encoded query of the URL The query should start with a @c '?'. If it doesn't @c '?' is prepended. @brief Sets the encoded query of the URL

setQuery

public void setQuery(String _txt)

setRef

public void setRef(String _txt)

Parameters: _txt the encoded reference or null to remove it

See Also: KURL KURL

UNKNOWN: Sets the encoded reference part (everything after @c '#') This is considered to be encoded, i.e. characters that are not allowed as part of the reference will not be encoded. @brief Sets the encoded reference part (everything after @c '#')

setUser

public void setUser(String _txt)

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

See Also: KURL KURL KURL

UNKNOWN: 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(). @brief Sets the user name (login, user id, etc) to include in the URL

split

public static ArrayList split(String _url)

Parameters: _url the URL that has to be split

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

See Also: KURL (const ) KURL

UNKNOWN: 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 @c "#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. @brief Splits nested URLs into a list of URLs

split

public static ArrayList split(KURL _url)

Parameters: _url the URL that has to be split

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

See Also: KURL KURL

UNKNOWN: 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 @c "#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. @brief Splits nested URLs into a list of URLs

upURL

public KURL upURL()

Returns: a URL that is a level higher

See Also: KURL KURL KURL KURL

UNKNOWN: 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. @brief Returns the URL that is the best possible candidate for on level higher in the path hierachy

uriMode

public int uriMode()

Returns: the URI processing mode set for this URL

See Also: URIMode KURL

UNKNOWN: Returns the URI processing mode for the URL @brief Returns the URI processing mode for the URL

uriModeForProtocol

public static int uriModeForProtocol(String protocol)

Parameters: protocol the protocol name. See protocol()

Returns: the URIMode suitable for the given protocol

See Also: KURL

UNKNOWN: Determines which URI mode is suitable for processing URIs of a given protocol @brief Determines which URI mode is suitable for processing URIs of a given protocol

url

public String url(int _trailing, int encoding_hint)

Parameters: _trailing May be ( @c -1, 0, @c +1 ). @c -1 strips a trailing 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: KURL KURL KURL

UNKNOWN: 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. 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) @c '/' character in the path. If the URL has no path, then no @c '/' is added anyway. And on the other side: if the path is just @c "/", 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. '/', @c +1 adds a trailing @c '/' if there is none yet and 0 returns the path unchanged @brief Returns the URL as string, with all escape sequences intact, encoded in a given charset

url

public String url(int _trailing)

url

public String url()

user

public String user()

Returns: the user name or @c null if there is no user name

See Also: KURL KURL

UNKNOWN: Returns the decoded user name (login, user id, etc) included in the URL @brief Returns the decoded user name (login, user id, etc) included in the URL