|
|
Represents and parses 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.
| enum AdjustementFlags { NoAdjustements = 0, StripFileProtocol = 1 } | AdjustementFlags |
| List (class) | List |
| KURL ()
| KURL |
Constructs an empty URL.
| ~KURL ()
| ~KURL |
Destructs the KURL object.
| KURL ( const QString& url, int encoding_hint = 0 )
| KURL |
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()
| KURL ( const char * url, int encoding_hint = 0 )
| KURL |
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 QCString& url, int encoding_hint = 0 )
| KURL |
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.
| KURL ( const KURL& u )
| KURL |
Copy constructor.
| KURL ( const QUrl &u )
| KURL |
Converts from a QUrl.
| KURL ( const KURL& _baseurl, const QString& _rel_url, int encoding_hint=0 )
| KURL |
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()
| QString protocol ()
| protocol |
[const]
Returns the protocol for the URL (i.e., file, http, etc.).
| void setProtocol ( const QString& _txt )
| setProtocol |
Sets the protocol for the URL (i.e., file, http, etc.)
| QString user ()
| user |
[const]
Returns the decoded user name (login, user id, ...) included in the URL.
| void setUser ( const QString& _txt )
| setUser |
Sets the user name (login, user id, ...) included in the URL.
Special characters in the user name will appear encoded in the URL.
| bool hasUser ()
| hasUser |
[const]
Test to see if this URL has a user name included in it.
| QString pass ()
| pass |
[const]
Returns the decoded password (corresponding to user()) included in the URL.
| void setPass ( const QString& _txt )
| setPass |
Sets the password (corresponding to user()) included in the URL.
Special characters in the password will appear encoded in the URL.
| bool hasPass ()
| hasPass |
[const]
Test to see if this URL has a password included in it.
| QString host ()
| host |
[const]
Returns the decoded hostname included in the URL.
| void setHost ( const QString& _txt )
| setHost |
Sets the hostname included in the URL.
Special characters in the hostname will appear encoded in the URL.
| bool hasHost ()
| hasHost |
[const]
Test to see if this URL has a hostname included in it.
| unsigned short int port ()
| port |
[const]
Returns the port number included in the URL. If there is no port number specified in the URL, returns 0.
| void setPort ( unsigned short int _p )
| setPort |
Sets the port number included in the URL.
| QString path ()
| path |
[const]
Returns the current decoded path. This does not include the query.
| QString path ( int _trailing )
| path |
[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.
| void setPath ( const QString& path )
| setPath |
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 ()
| hasPath |
[const]
Test to see if this URL has a path is included in it.
| void cleanPath (bool cleanDirSeparator = true)
| cleanPath |
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, occurrances of consecutive directory separators (e.g. /foo//bar) are cleaned up as well. |
| void adjustPath (int _trailing)
| adjustPath |
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. |
| void setEncodedPathAndQuery ( const QString& _txt, int encoding_hint = 0 )
| setEncodedPathAndQuery |
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:
| encoding_hint | MIB of original encoding of _txt .
|
See also: QTextCodec::mibEnum()
| void setEncodedPath (const QString& _txt, int encoding_hint = 0 )
| setEncodedPath |
| QString encodedPathAndQuery ( int _trailing = 0, bool _no_empty_path = false, int encoding_hint = 0)
| encodedPathAndQuery |
[const]
Parameters:
| _no_empty_path | If set to true then an empty path is substituted by "/". |
| encoding_hint | MIB of desired encoding of URL. |
Returns: The concatenation if the encoded path , '?' and the encoded query.
See also: QTextCodec::mibEnum()
| void setQuery ( const QString& _txt, int encoding_hint = 0)
| setQuery |
The query should start with a '?'. If it doesn't '?' is prepended.
Parameters:
| _txt | This is considered to be encoded. This has a good reason: The query may contain the 0 character. |
| encoding_hint | MIB of original encoding of _txt. |
| encoding_hint | Reserved, should be 0. |
See also: QTextCodec::mibEnum()
| QString query ()
| 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 ()
| ref |
[const]
The reference is never decoded automatically.
| void setRef ( const QString& _txt )
| setRef |
Sets the reference part (everything after '#').
Parameters:
| _txt | is considered encoded. |
| bool hasRef ()
| hasRef |
[const]
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.
| QString htmlRef ()
| htmlRef |
[const]
Returns: The HTML-style reference.
| QString encodedHtmlRef ()
| encodedHtmlRef |
[const]
Returns: The HTML-style reference in its original form.
| void setHTMLRef ( const QString& _ref )
| setHTMLRef |
Sets the HTML-style reference.
Parameters:
| _ref | This is considered to be not encoded in contrast to setRef() |
See also: htmlRef()
| bool hasHTMLRef ()
| hasHTMLRef |
[const]
Returns: true if the URL has an HTML-style reference.
See also: htmlRef()
| bool isValid ()
| isValid |
[const]
Returns: false if the URL is malformed. This function does not test
whether sub URLs are well-formed, too.
| bool isMalformed ()
| isMalformed |
[const]
| bool isLocalFile ()
| isLocalFile |
[const]
Returns: true if the file is a plain local file and has no filter protocols
attached to it.
| void setFileEncoding (const QString &encoding)
| setFileEncoding |
Adds encoding information to url.
| QString fileEncoding ()
| fileEncoding |
[const]
Returns encoding information from url.
Returns: An encoding suitable for QTextCodec::codecForName() or an empty string if not encoding was specified.
| bool hasSubURL ()
| 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 )
| addPath |
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 | This is considered to be decoded |
| QString queryItem ( const QString& _item )
| queryItem |
[const]
Returns the value of a certain query item.
Parameters:
| _item | Item whose value we want |
Returns: the value of the given query item name or QString::null if the specified item does not exist.
| void setFileName ( const QString&_txt )
| setFileName |
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 | This 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.
|
| QString fileName ( bool _ignore_trailing_slash_in_path = true )
| fileName |
[const]
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.
| QString directory ( bool _strip_trailing_slash_from_result = true,
bool _ignore_trailing_slash_in_path = true )
| directory |
[const]
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.
| bool cd ( const QString& _dir )
| cd |
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:/
Returns: true
| QString url ( int _trailing = 0, int encoding_hint = 0)
| url |
[const]
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. This is used in particular for encoding URLs in UTF-8 before using them in a drag and drop operation.
See also: QTextCodec::mibEnum()
| QString prettyURL ( int _trailing = 0)
| prettyURL |
[const]
Returns: A human readable URL, with no non-necessary encodings/escaped characters. Example: http://localhost:8080/test.cgi?test=hello world&name=fred
| QString prettyURL ( int _trailing, AdjustementFlags _flags)
| prettyURL |
[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 ()
| isEmpty |
[const]
Test to see if the KURL is empty.
| KURL upURL ( )
| 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 )
| operator= |
| KURL& operator= ( const QString& _url )
| operator= |
| KURL& operator= ( const char * _url )
| operator= |
| KURL& operator= ( const QUrl & u )
| operator= |
| bool operator== ( const KURL& _u )
| operator== |
[const]
| bool operator== ( const QString& _u )
| operator== |
[const]
| bool operator!= ( const KURL& _u )
| operator!= |
[const]
| bool operator!= ( const QString& _u )
| operator!= |
[const]
| bool cmp ( const KURL &u, bool ignore_trailing = false )
| cmp |
[const]
Compares this url with u.
Parameters:
| 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.
| bool isParentOf ( const KURL& u )
| isParentOf |
[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 )
| split |
[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.
| List split ( const KURL& _url )
| split |
[static]
A convenience function.
| KURL join ( const List& _list )
| join |
[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)
| encode_string |
[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 |
| encoding_hint | MIB of encoding to use. |
See also: QTextCodec::mibEnum()
| QString encode_string_no_slash (const QString &str, int encoding_hint = 0)
| encode_string_no_slash |
[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()
| QString decode_string (const QString &str, int encoding_hint = 0)
| decode_string |
[static]
Convenience function.
Decode %-style encoding and convert from local encoding to unicode.
Reverse of encode_string()
Parameters:
| str | String to decode |
| encoding_hint | MIB of original encoding of str .
|
See also: QTextCodec::mibEnum()
| bool isRelativeURL (const QString &_url)
| isRelativeURL |
[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.
| void reset ()
| reset |
[protected]
| void parse ( const QString& _url, int encoding_hint = 0)
| parse |
[protected]