diff options
Diffstat (limited to 'kdecore/kurl.h')
-rw-r--r-- | kdecore/kurl.h | 1828 |
1 files changed, 0 insertions, 1828 deletions
diff --git a/kdecore/kurl.h b/kdecore/kurl.h deleted file mode 100644 index eaa0291b9..000000000 --- a/kdecore/kurl.h +++ /dev/null @@ -1,1828 +0,0 @@ -/* This file is part of the KDE libraries - * Copyright (C) 1999 Torben Weis <weis@kde.org> - * - * This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU Library General Public - * License as published by the Free Software Foundation; either - * version 2 of the License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Library General Public License for more details. - * - * You should have received a copy of the GNU Library General Public License - * along with this library; see the file COPYING.LIB. If not, write to - * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - * Boston, MA 02110-1301, USA. - **/ - -#ifndef __kurl_h__ -#define __kurl_h__ - -#include <tqstring.h> -#include <tqvaluelist.h> -#include "kdelibs_export.h" - -class TQUrl; -class TQStringList; -template <typename K, typename V> class TQMap; - -class KURLPrivate; - -// Defines that file-urls look like file:///path/file instead of file:/path/file -#define KURL_TRIPLE_SLASH_FILE_PROT - -/** - * @brief Represents and parses a URL - * - * A prototypical URL looks like: - * @code - * protocol://user:password@hostname:port/path/to/file.ext#reference - * @endcode - * - * 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(const TQString&) expects a string properly escaped, - * or at least non-ambiguous. - * For instance a local file or directory <tt>"/bar/#foo#"</tt> would have the - * URL <tt>"file:///bar/%23foo%23"</tt>. - * If you have the absolute path and need the URL-escaping you should create - * KURL via the default-constructor and then call setPath(const TQString&): - * @code - * KURL kurl; - * kurl.setPath( "/bar/#foo#" ); - * TQString url = kurl.url(); // -> "file:///bar/%23foo%23" - * @endcode - * - * If you have the URL of a local file or directory and need the absolute path, - * you would use path(). - * @code - * KURL url( "file:///bar/%23foo%23" ); - * ... - * if ( url.isLocalFile() ) - * TQString path = url.path(); // -> "/bar/#foo#" - * @endcode - * - * 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: - * @code - * TQString dirUrl = "file:///bar/"; - * TQString fileName = "#foo#"; - * TQString invalidURL = dirUrl + fileName; // -> "file:///bar/#foo#" won't behave like you would expect. - * @endcode - * Instead you should use addPath(). - * - * Right: - * @code - * KURL url( "file:///bar/" ); - * TQString fileName = "#foo#"; - * url.addPath( fileName ); - * TQString validURL = url.url(); // -> "file:///bar/%23foo%23" - * @endcode - * - * 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... - * - * @code - * KURL url( "ftp://name:password@ftp.faraway.org/bar/%23foo%23"); - * TQString visibleURL = url.prettyURL(); // -> "ftp://name@ftp.faraway.org/bar/%23foo%23" - * @endcode - * Note that prettyURL() doesn't change the character escapes (like <tt>"%23"</tt>). - * 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, - * @code - * http://localhost/cgi-bin/test%20me.pl?cmd=Hello%20you - * @endcode - * would result in a decoded path <tt>"/cgi-bin/test me.pl"</tt> - * and in the encoded query <tt>"?cmd=Hello%20you"</tt>. - * Since path is internally always encoded you may @em not use - * <tt>"%00"</tt> in the path, although this is OK for the query. - * - * @author Torben Weis <weis@kde.org> - */ -class KDECORE_EXPORT KURL -{ -public: - /** - * Flags to choose how file: URLs are treated when creating their QString - * representation with prettyURL(int,AdjustementFlags) - * - * However it is recommended to use pathOrURL() instead of this variant of prettyURL() - */ - enum AdjustementFlags - { - /** - * Do not treat file: URLs differently - */ - NoAdjustements = 0, - /** - * Strip the file: protocol from the string, i.e. return only the path and - * filename as a local path - */ - StripFileProtocol = 1 - }; - - /** - * Defines the type of URI we are processing. - */ - enum URIMode - { - /** - * Automatically detected. Using this mode, an appropriate processing - * mode will be selected when the URI is first processed. - */ - Auto, - /** - * Invalid URI. This is something that can't be parsed as a URI at all. - * The contents are accessible through the protocol() method. - */ - Invalid, - /** - * Raw URI. This type of URI should not be processed in any way. - * Contents are accessible through the path() method. - */ - RawURI, - /** - * Standards compliant URL. Process as a syntactically correct URL. - */ - URL, - /** - * Mailto URI. path() contains an email address which should have its - * domain part processed as a DNS name. The email address is accessible - * through the path() method. - */ - Mailto - }; - - /** - * KURL::List is a TQValueList that contains KURLs with a few - * convenience methods. - * @see KURL - * @see QValueList - */ - class KDECORE_EXPORT List : public TQValueList<KURL> - { - public: - /** - * Creates an empty List. - */ - List() { } - /** - * @brief Creates a list that contains the given URL as only item - * - * @param url the URL to add - */ - List(const KURL &url); - /** - * @brief Creates a list that contains the URLs from the given list - * - * This equivalent to iterating over the input list and using each item - * as the argument to KURL's constructor, i.e. the resulting list will - * have as many elements as the input list, but not all entries might - * be valid. - * - * @param list the list containing the URLs as strings - * - * @see KURL(const TQString &, int) - */ - List(const TQStringList &list); - /** - * @brief Converts the URLs of this list to a list of strings - * - * This is equivalent to iterating over the list and calling url() on - * each item. - * If you need a list of user visible URLs, i.e. not containing password - * information, iterate over the list yourself and call prettyURL() on - * each item instead. - * - * @return the list of strings - * - * @see KURL::url() - */ - TQStringList toStringList() const; - }; - /** - * @brief Constructs an empty URL - * - * The created instance will also be invalid, see isValid() - */ - KURL(); - - /** - * @brief Destructs the KURL object - */ - ~KURL(); - - /** - * @brief Usual constructor, to construct from a string - * - * @warning It is dangerous to feed UNIX filenames into this function, - * this will work most of the time but not always. - * - * For example <tt>"/home/Torben%20Weis"</tt> will be considered a URL - * pointing to the file <tt>"/home/Torben Weis"</tt> instead - * of to the file <tt>"/home/Torben%20Weis"</tt>. - * - * This means that if you have a usual UNIX like path you should not use - * this constructor. Instead use fromPathOrURL() - * - * @param url a URL, not a filename. If the URL does not have a protocol - * part, @c "file:" is assumed - * @param encoding_hint MIB of original encoding of URL. - * See TQTextCodec::mibEnum() - * - * @see fromPathOrURL() - */ - KURL( const TQString& url, int encoding_hint = 0 ); - /** - * @brief Constructor taking an URL encoded in a C string - * - * Constructor taking a char * @p url, which is an @em encoded representation - * of the URL, exactly like the usual constructor. This is useful when - * the URL, in its encoded form, is strictly ASCII. - * - * @warning It is dangerous to feed UNIX filenames into this function, - * this will work most of the time but not always. - * - * For example <tt>"/home/Torben%20Weis"</tt> will be considered a URL - * pointing to the file <tt>"/home/Torben Weis"</tt> instead - * of to the file <tt>"/home/Torben%20Weis"</tt>. - * - * This means that if you have a usual UNIX like path you should not use - * this constructor. Instead use fromPathOrURL() - * - * @param url an encoded URL. If the URL does not have a protocol part, - * @c "file:" is assumed - * @param encoding_hint MIB of original encoding of URL. - * See TQTextCodec::mibEnum() - * - * @see fromPathOrURL() - * @see TQString::tqfromLatin1() - */ - KURL( const char * url, int encoding_hint = 0 ); - /** - * @brief Constructor taking an URL encoded in a QCString - * - * Constructor taking a TQCString @p url, which is an @em encoded - * representation of the URL, exactly like the usual constructor. This is - * useful when the URL, in its encoded form, is strictly ASCII. - * - * @warning It is dangerous to feed UNIX filenames into this function, - * this will work most of the time but not always. - * - * For example <tt>"/home/Torben%20Weis"</tt> will be considered a URL - * pointing to the file <tt>"/home/Torben Weis"</tt> instead - * of to the file <tt>"/home/Torben%20Weis"</tt>. - * - * This means that if you have a usual UNIX like path you should not use - * this constructor. Instead use fromPathOrURL() - * - * @param url A encoded URL. If the URL does not have a protocol part, - * @c "file:" is assumed - * @param encoding_hint MIB of original encoding of URL. - * See TQTextCodec::mibEnum() - * - * @see fromPathOrURL() - * @see TQString::tqfromLatin1() - */ - KURL( const TQCString& url, int encoding_hint = 0 ); - - /** - * @brief Copy constructor - * - * @param u the KURL to copy - */ - KURL( const KURL& u ); - /** - * @brief Constructor taking a Qt URL - * - * Converts from a Qt URL. - * - * @param u the QUrl - */ - KURL( const TQUrl &u ); - /** - * @brief Constructor allowing relative URLs - * - * @warning It is dangerous to feed UNIX filenames into this function, - * this will work most of the time but not always. - * - * For example <tt>"/home/Torben%20Weis"</tt> will be considered a URL - * pointing to the file <tt>"/home/Torben Weis"</tt> instead - * of to the file <tt>"/home/Torben%20Weis"</tt>. - * - * This means that if you have a usual UNIX like path you should not use - * this constructor. Instead use fromPathOrURL() - * - * @param _baseurl The base url. - * @param _rel_url A relative or absolute URL. - * If this is an absolute URL then @p _baseurl will be ignored. - * If this is a relative URL it will be combined with @p _baseurl. - * Note that @p _rel_url should be encoded too, in any case. - * So do NOT pass a path here (use setPath() or addPath() or - * fromPathOrURL() instead) - * @param encoding_hint MIB of original encoding of URL. - * See TQTextCodec::mibEnum() - * - * @see fromPathOrURL() - */ - KURL( const KURL& _baseurl, const TQString& _rel_url, int encoding_hint=0 ); - - /** - * @brief Returns the protocol for the URL - * - * Examples for a protocol string are @c "file", @c "http", etc. but also - * @c "mailto:" and other pseudo protocols. - * - * @return the protocol of the URL, does not include the colon. If the - * URL is malformed, @c TQString::null will be returned - * - * @see setProtocol() - * @see isValid() - */ - TQString protocol() const { return m_bIsMalformed ? TQString::null : m_strProtocol; } - /** - * @brief Sets the protocol for the URL - * - * Examples for a protocol string are @c "file", @c "http", etc. but also - * @c "mailto:" and other pseudo protocols. - * - * @param _txt the new protocol of the URL (without colon) - * - * @see protocol() - */ - void setProtocol( const TQString& _txt ); - - /** - * @brief Returns the URI processing mode for the URL - * - * @return the URI processing mode set for this URL - * - * @see URIMode - * @see uriModeForProtocol() - * - * @since 3.2 - */ - int uriMode() const; - - /** - * @brief Returns the decoded user name (login, user id, etc) included in - * the URL - * - * @return the user name or @c TQString::null if there is no user name - * - * @see setUser() - * @see hasUser() - */ - TQString user() const { return m_strUser; } - /** - * @brief 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(). - * - * @param _txt the name of the user or @c TQString::null to remove the user - * - * @see user() - * @see hasUser() - * @see hasPass() - */ - void setUser( const TQString& _txt ); - /** - * @brief Tests if this URL has a user name included in it - * - * @return @c true if the URL has an non-empty user name - * - * @see user() - * @see setUser() - * @see hasPass() - */ - bool hasUser() const { return !m_strUser.isEmpty(); } - - /** - * @brief Returns the decoded password (corresponding to user()) included - * in the URL - * - * @note a password can only appear in a URL string if you also set - * a user, see setUser(). - * - * @return the password or @c TQString::null if it does not exist - * - * @see setPass() - * @see hasPass() - * @see hasUser() - */ - TQString pass() const { return m_strPass; } - /** - * @brief Sets the password (corresponding to user()) to include in the URL - * - * Special characters in the password will appear encoded in the URL. - * @note a password can only appear in a URL string if you also set - * a user, see setUser(). - * - * @param _txt the password to set or @c TQString::null to remove the password - * - * @see pass() - * @see hasPass() - * @see hasUser() - */ - void setPass( const TQString& _txt ); - /** - * @brief Tests if this URL has a password included in it - * - * @note a password can only appear in a URL string if you also set - * a user, see setUser(). - * - * @return @c true if there is a non-empty password set - * - * @see pass() - * @see setPass() - * @see hasUser() - */ - bool hasPass() const { return !m_strPass.isEmpty(); } - - /** - * @brief Returns the decoded hostname included in the URL - * - * @return the name of the host or @c TQString::null if no host is set - * - * @see setHost() - * @see hasHost() - */ - TQString host() const { return m_strHost; } - - /** - * @brief Sets the hostname to include in the URL - * - * Special characters in the hostname will appear encoded in the URL. - * - * @param _txt the new name of the host or TQString::null to remove the host - * - * @see host() - * @see hasHost() - */ - void setHost( const TQString& _txt ); - /** - * @brief Tests if this URL has a hostname included in it - * - * @return @c true if the URL has a non-empty host - * - * @see host() - * @see setHost() - */ - bool hasHost() const { return !m_strHost.isEmpty(); } - - /** - * @brief Returns the port number included in the URL - * - * @return the port number or @c 0 if there is no port number specified in - * the URL - * - * @see setPort() - * @see host() - */ - unsigned short int port() const { return m_iPort; } - /** - * @brief Sets the port number to include in the URL - * - * @param _p the new port number or @c 0 to have no port number - * - * @see port() - * @see setHost() - */ - void setPort( unsigned short int _p ); - - /** - * @brief Returns the current decoded path - * - * This does @em not include the query. - * - * @return the path of the URL (without query), or @c TQString::null if no - * path is set - * - * @see path(int) - * @see setPath() - * @see hasPath() - */ - TQString path() const { return m_strPath; } - - /** - * @brief Returns the current decoded path - * - * This does @em not include the query, see query() for accessing it. - * - * The @p _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: <tt>"ftp://weis@host"</tt> means something completely different - * than <tt>"ftp://weis@host/"</tt>. - * So adding or stripping the '/' would really alter the URL, while - * <tt>"ftp://host/path"</tt> and <tt>"ftp://host/path/"</tt> mean the same - * directory. - * - * @param _trailing May be ( @c -1, @c 0, @c +1 ). @c -1 strips a trailing - * @c '/', @c +1 adds a trailing @c '/' if there is none yet - * and @c 0 returns the path unchanged - * - * @return the path of the URL (without query), or @c TQString::null if no - * path is set - * - * @see path() - * @see setPath() - * @see hasPath() - * @see adjustPath() - */ - TQString path( int _trailing ) const; - - /** - * @brief Sets the decoded path of the URL - * - * This does @em not changed the query, see setQuery() for that. - * - * The @p 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. - * - * @param path the new, decoded, path or @c TQString::null to remove the path - * - * @see path() - * @see path(int) - * @see hasPath() - */ - void setPath( const TQString& path ); - - /** - * @brief Tests if this URL has a path included in it - * - * @return @c true if there is a non-empty path - * - * @see path() - * @see setPath() - */ - bool hasPath() const { return !m_strPath.isEmpty(); } - - /** - * @brief 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. - * - * @param cleanDirSeparator if @c true, occurrences of consecutive - * directory separators (e.g. <tt>"/foo//bar"</tt>) are cleaned up as - * well - * - * @see hasPath() - * @see adjustPath() - */ - void cleanPath(bool cleanDirSeparator = true); - - /** - * @brief Adds or removes a trailing slash to/from the path - * - * The @p _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: <tt>"ftp://weis@host"</tt> means something completely different - * than <tt>"ftp://weis@host/"</tt>. - * So adding or stripping the '/' would really alter the URL, while - * <tt>"ftp://host/path"</tt> and <tt>"ftp://host/path/"</tt> mean the same - * directory. - * - * @param _trailing May be ( @c -1, @c 0, @c +1 ). @c -1 strips a trailing - * @c '/', @c +1 adds a trailing @c '/' if there is none yet - * and @c 0 returns the path unchanged - * - * @see hasPath() - * @see cleanPath() - */ - void adjustPath(int _trailing); - - /** - * @brief 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. - * - * @param _txt the new encoded path and encoded query - * @param encoding_hint MIB of original encoding of @p _txt . - * See TQTextCodec::mibEnum() - * - * @see encodedPathAndQuery() - * @see setPath() - * @see setQuery() - */ - void setEncodedPathAndQuery( const TQString& _txt, int encoding_hint = 0 ); - - /** - * @brief Sets the (already encoded) path of the URL - * - * @param _txt the new encoded path - * @param encoding_hint MIB of original encoding of @p _txt . - * See TQTextCodec::mibEnum() - * - * @see setEncodedPathAndQuery() - * @see setPath() - */ - void setEncodedPath(const TQString& _txt, int encoding_hint = 0 ); - - /** - * @brief Returns the encoded path and the query - * - * The @p _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: <tt>"ftp://weis@host"</tt> means something completely different - * than <tt>"ftp://weis@host/"</tt>. - * So adding or stripping the '/' would really alter the URL, while - * <tt>"ftp://host/path"</tt> and <tt>"ftp://host/path/"</tt> mean the same - * directory. - * - * @param _trailing May be ( @c -1, @c 0, @c +1 ). @c -1 strips a trailing - * @c '/', @c +1 adds a trailing @c '/' if there is none yet - * and @c 0 returns the path unchanged - * @param _no_empty_path if set to @c true then an empty path is substituted - * by @c "/" - * @param encoding_hint MIB of desired encoding of URL. - * See TQTextCodec::mibEnum() - * - * @return the concatenation of the encoded path , @c '?' and the - * encoded query - * - * @see setEncodedPathAndQuery() - * @see path() - * @see query() - */ - TQString encodedPathAndQuery( int _trailing = 0, bool _no_empty_path = false, int encoding_hint = 0) const; - - /** - * @brief Sets the encoded query of the URL - * - * The query should start with a @c '?'. If it doesn't @c '?' is prepended. - * - * @param _txt this is considered to be encoded. This has a good reason: - * the query may contain the @c '0' character - * - * @param encoding_hint MIB of the encoding. Reserved, should be @c 0 . - * See TQTextCodec::mibEnum() - * - * @see query() - */ - void setQuery( const TQString& _txt, int encoding_hint = 0); - - /** - * @brief 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. - * - * @return the encoded query or @c TQString::null if there is none - * - * @see setQuery() - */ - TQString query() const; - - /** - * @brief Returns the encoded reference of the URL - * - * The reference is @em never decoded automatically. - * - * @return the undecoded reference, or @c TQString::null if there is none - * - * @see setRef() - * @see hasRef() - * @see htmlRef() - */ - TQString ref() const { return m_strRef_encoded; } - - /** - * @brief 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 @em not be encoded. - * - * @param _txt the encoded reference or @c TQString::null to remove it - * - * @see ref() - * @see hasRef() - */ - void setRef( const TQString& _txt ) { m_strRef_encoded = _txt; } - - /** - * @brief Tests if the URL has a reference part - * - * @return @c true if the URL has a reference part. In a URL like - * <tt>"http://www.kde.org/kdebase.tar#tar:/README"</tt> it would - * return @c true as well - * - * @see ref() - * @see setRef() - */ - bool hasRef() const { return !m_strRef_encoded.isNull(); } - - /** - * @brief Returns decoded the HTML-style reference - * (the part of the URL after @c '#') - * - * @return the HTML-style reference - * - * @see encodedHtmlRef() - * @see setHTMLRef() - * @see hasHTMLRef() - * @see split() - * @see hasSubURL() - * @see ref() - */ - TQString htmlRef() const; - - /** - * @brief Returns the encoded HTML-style reference - * (the part of the URL after @c '#') - * - * @return the HTML-style reference in its original, encoded, form - * - * @see htmlRef() - * @see setHTMLRef() - * @see hasHTMLRef() - */ - TQString encodedHtmlRef() const; - - /** - * @brief Sets the decoded HTML-style reference - * - * @param _ref the new reference. This is considered to be @em not encoded in - * contrast to setRef(). Use @c TQString::null to remove it - * - * @see htmlRef() - * @see hasHTMLRef() - */ - void setHTMLRef( const TQString& _ref ); - - /** - * @brief Tests if there is an HTML-style reference - * - * @return @c true if the URL has an HTML-style reference - * - * @see htmlRef() - * @see encodedHtmlRef() - * @see setHTMLRef() - * @see hasRef() - */ - bool hasHTMLRef() const; - - /** - * @brief Tests if the URL is well formed - * - * @return @c false if the URL is malformed. This function does @em not test - * whether sub URLs are well-formed as well - */ - bool isValid() const { return !m_bIsMalformed; } - /** - * @brief Tests if the URL is malformed - * - * @return @c true if the URL is malformed. This function does @em not test - * whether sub URLs are well-formed as well - * - * @deprecated Use !isValid() instead - * - * @see isValid() - */ - KDE_DEPRECATED bool isMalformed() const { return !isValid(); } - - /** - * @brief Tests if the file is local - * - * @return @c true if the file is a plain local file and has no filter - * protocols attached to it - */ - bool isLocalFile() const; - - /** - * @brief 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. - * - * @param encoding the encoding to add or @c TQString::null to remove the - * encoding - * - * @see fileEncoding() - * @see TQTextCodec::codecForName() - */ - void setFileEncoding(const TQString &encoding); - - /** - * @brief Returns encoding information of the URL - * - * The encoding information is the content of the @c "charset" parameter. - * - * @return an encoding suitable for TQTextCodec::codecForName() - * or @c TQString::null if not encoding was specified - */ - TQString fileEncoding() const; - - /** - * @brief Tests if the URL has any sub URLs - * - * See split() for examples for sub URLs. - * - * @return @c true if the file has at least one sub URL - * - * @see split() - */ - bool hasSubURL() const; - - /** - * @brief Adds to the current path - * - * Assumes that the current path is a directory. @p _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 - * @c '/' or not. If there is none, it becomes appended. If @p _txt - * has a leading @c '/' then this one is stripped. - * - * @param txt the text to add. It is considered to be decoded - * - * @see setPath() - * @see hasPath() - */ - void addPath( const TQString& txt ); - - /** - * @brief Returns the value of a certain query item - * - * @param item item whose value we want - * - * @return the value of the given query item name or @c TQString::null if the - * specified item does not exist - * - * @see addQueryItem() - * @see removeQueryItem() - * @see queryItems() - * @see query() - */ - TQString queryItem( const TQString& item ) const; - - /** - * @brief Returns the value of a certain query item - * - * @param item item whose value we want - * @param encoding_hint MIB of encoding of query. - * See TQTextCodec::mibEnum() - * - * @return the value of the given query item name or @c TQString::null if the - * specified item does not exist - * - * @see addQueryItem() - * @see removeQueryItem() - * @see queryItems() - * @see query() - */ - TQString queryItem( const TQString& item, int encoding_hint ) const; - - /** - * Options for queryItems() - * - * @since 3.1 - */ - enum QueryItemsOptions - { - /** - * Normalize query keys to lowercase - */ - CaseInsensitiveKeys = 1 - }; - - /** - * @internal, override for the below function - */ - TQMap< TQString, TQString > queryItems( int options=0 ) const; - - /** - * @brief Returns the list of query items as a map mapping keys to values - * - * @param options any of QueryItemsOptions <em>OR</em>ed together - * @param encoding_hint MIB of encoding of query. - * See TQTextCodec::mibEnum() - * - * @return the map of query items or the empty map if the URL has no - * query items - * - * @see queryItem() - * @see addQueryItem() - * @see removeQueryItem() - * @see query() - * - * @since 3.1 - */ - TQMap< TQString, TQString > queryItems( int options, int encoding_hint ) const; - - /** - * @brief Adds an additional query item - * - * To replace an existing query item, the item should first be - * removed with removeQueryItem() - * - * @param _item name of item to add - * @param _value value of item to add - * @param encoding_hint MIB of encoding to use for _value. - * See TQTextCodec::mibEnum() - * - * @see queryItem() - * @see queryItems() - * @see query() - */ - void addQueryItem( const TQString& _item, const TQString& _value, int encoding_hint = 0 ); - - /** - * @brief Removea an item from the query - * - * @param _item name of item to remove - * - * @see addQueryItem() - * @see queryItem() - * @see queryItems() - * @see query() - */ - void removeQueryItem( const TQString& _item ); - - /** - * @brief 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 @p _txt is just appended, - * otherwise all text behind the last @c '/' in the current path is erased - * and @p _txt is appended then. It does not matter whether @p _txt starts - * with @c '/' or not. - * - * Any reference is reset. - * - * @param _txt the filename to be set. It is considered to be decoded - * - * @see fileName() - * @see setDirectory() - * @see setPath() - */ - void setFileName( const TQString&_txt ); - - /** - * @brief Returns the filename of the path - * - * @p _ignore_trailing_slash_in_path tells whether a trailing @c '/' should - * be ignored. This means that the function would return @c "torben" for - * <tt>"file:///hallo/torben/"</tt> and <tt>"file:///hallo/torben"</tt>. - * - * @param _ignore_trailing_slash_in_path if set to @c false, then everything - * behind the last @c '/' is considered to be the filename - * - * @return the filename of the current path. The returned string is decoded. - * @c TQString::null if there is no file (and thus no path) - * - * @see setFileName() - * @see directory() - * @see path() - */ - TQString fileName( bool _ignore_trailing_slash_in_path = true ) const; - - /** - * @brief Returns the directory of the path - * - * The directory is everything between the last and the second last @c '/' - * is returned. For example <tt>"file:///hallo/torben/"</tt> would return - * <tt>"/hallo/torben/"</tt> while <tt>"file:///hallo/torben"</tt> would - * return <tt>"hallo/"</tt>. - * - * @p _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 @p _strip_trailing_slash_from_result) for - * <tt>"file:///hallo/torben/"</tt> and <tt>"file:///hallo/torben"</tt>. - * - * @param _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 - * @param _ignore_trailing_slash_in_path if set to @c false, then everything - * behind the last @c '/' is considered to be the filename - * - * @return the directory part of the current path or @c TQString::null when - * there is no path. The returned string is decoded - * - * @see setDirectory() - * @see fileName() - * @see path() - */ - TQString directory( bool _strip_trailing_slash_from_result = true, - bool _ignore_trailing_slash_in_path = true ) const; - - /** - * @brief Sets the directory of the path, leaving the filename empty - * - * @param dir the decoded directory to set - * - * @see directory() - * @see setFileName() - * @see setPath() - */ - void setDirectory(const TQString &dir); - - /** - * @brief Changes the directory by descending into the given directory - * - * It is assumed the current URL represents a directory. - * If @p _dir starts with a @c '/' the current URL will be - * <tt>"protocol://host/dir"</tt> otherwise @p _dir will be appended to the - * path. @p _dir can be @c ".." - * - * This function won't strip protocols. That means that when you are in - * <tt>"file:///dir/dir2/my.tgz#tar:/"</tt> and you do <tt>cd("..")</tt> you - * will still be in <tt>"file:///dir/dir2/my.tgz#tar:/"</tt> - * - * @param _dir the directory to change to - * @return @c true if successful - * - * @see directory() - * @see path() - */ - bool cd( const TQString& _dir ); - - /** - * @brief 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. - * - * @note 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 @p _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: <tt>"ftp://weis@host"</tt> means something completely different - * than <tt>"ftp://weis@host/"</tt>. - * So adding or stripping the '/' would really alter the URL, while - * <tt>"ftp://host/path"</tt> and <tt>"ftp://host/path/"</tt> mean the same - * directory. - * - * @param _trailing May be ( @c -1, @c 0, @c +1 ). @c -1 strips a trailing - * @c '/', @c +1 adds a trailing @c '/' if there is none yet - * and @c 0 returns the path unchanged - * @param encoding_hint MIB of encoding to use. - * See TQTextCodec::mibEnum() - * - * @return the complete URL, with all escape sequences intact, encoded - * in a given charset - * - * @see prettyURL() - * @see pathOrURL() - * @see htmlURL() - */ - TQString url( int _trailing = 0, int encoding_hint = 0) const; - - /** - * @brief Returns the URL as string in human-friendly format - * - * Example: - * @code - * http://localhost:8080/test.cgi?test=hello world&name=fred - * @endcode - * - * Does @em not contain the password if the URL has one, use url() if you - * need to have it in the string. - * - * The @p _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: <tt>"ftp://weis@host"</tt> means something completely different - * than <tt>"ftp://weis@host/"</tt>. - * So adding or stripping the '/' would really alter the URL, while - * <tt>"ftp://host/path"</tt> and <tt>"ftp://host/path/"</tt> mean the same - * directory. - * - * @param _trailing May be ( @c -1, @c 0, @c +1 ). @c -1 strips a trailing - * @c '/', @c +1 adds a trailing @c '/' if there is none yet - * and @c 0 returns the path unchanged - * @return a human readable URL, with no non-necessary encodings/escaped - * characters. Password will not be shown - * - * @see url() - * @see pathOrURL() - */ - TQString prettyURL( int _trailing = 0) const; - - /** - * @brief Returns the URL as string in human-friendly format - * Example: - * @code - * http://localhost:8080/test.cgi?test=hello world&name=fred - * @endcode - * - * Does @em not contain the password if the URL has one, use url() if you - * need to have it in the string. - * - * The @p _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: <tt>"ftp://weis@host"</tt> means something completely different - * than <tt>"ftp://weis@host/"</tt>. - * So adding or stripping the '/' would really alter the URL, while - * <tt>"ftp://host/path"</tt> and <tt>"ftp://host/path/"</tt> mean the same - * directory. - * - * @param _trailing May be ( @c -1, @c 0, @c +1 ). @c -1 strips a trailing - * @c '/', @c +1 adds a trailing @c '/' if there is none yet - * and @c 0 returns the path unchanged - * @param _flags if StripFileProtocol, @c "file://" will be stripped. - * The use of this method is now discouraged, better use pathOrURL(). - * - * @return a human readable URL, with no non-necessary encodings/escaped - * characters. Password will not be shown - * - * @see prettyURL() - * @see url() - * @see pathOrURL() - */ - TQString prettyURL( int _trailing, AdjustementFlags _flags) const; - // ### BIC: Merge the two above + spell it as "Adjustment" - // Or remove completely, and let people use pathOrURL() instead - - /** - * @brief 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. - * - * @return the path or URL string depending on its properties - * - * @see prettyURL() - * @see path() - * @see url() - * @see isLocalFile() - * - * @since 3.4 - */ - TQString pathOrURL() const; - - /** - * @brief Returns the URL as string, escaped for HTML - * - * @return 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 prettyURL() - * @see url() - * @see pathOrURL() - */ - TQString htmlURL() const; - - - /** - * @brief Tests if the KURL is empty - * - * An empty URL has neither path nor protocol set. - * - * @return @c true if the URL is empty - * - * @see hasPath() - * @see protocol() - * @see isValid() - */ - bool isEmpty() const; - - /** - * @brief 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 - * <tt>"file:///home/x.tgz#gzip:/#tar:/"</tt> and hit the up button you - * expect to see <tt>"file:///home"</tt>. 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. - * - * @return a URL that is a level higher - * - * @see cd() - * @see split() - * @see hasSubURL() - * @see path() - */ - KURL upURL( ) const; - - /** - * @brief Tests if this URL is less than the given URL - * - * The current URL is consideres <tt>"less than"</tt> then @p _u if - * (tested in this order): - * - it is not valid but @p _u is. See isValid() - * - its protocol is "less than" @p _u's protocol. See protocol() - * - its host is "less than" @p _u's host. See host() - * - its port is "less than" @p _u's port. See port() - * - its path is "less than" @p _u's path. See path() - * - its encoded query is "less than" @p _u's encoded query. See query() - * - its endoded reference is "less than" @p _u's encoded reference. - * See ref() - * - its username is "less than" @p _u's username. See user() - * - its password is "less than" @p _u's password. See pass() - * - * Examples: - * @code - * KURL url1; - * KURL url2; - * - * bool lessThan = url1 < url2; // false. Both invalid, no protocols - * - * url2.setProtocol( TQString::null ); - * lessThan = url1 < url2; // true. url2 is valid because of setProtocol() - * - * url1.setProtocol( TQString::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 - * @endcode - * - * @param _u the URL to compare to - * - * @return @c true if the URL is less than @p _u. Otherwise @c false - * (equal or greater than) - * - * @see operator==() - * @see TQString::compare() - */ - bool operator<(const KURL& _u) const; - - /** - * @brief Copies the values of the given URL into this one - * - * Just assigns each member using the member's assignment operator. - * - * @param _u the URL to take the values from - * - * @return a reference to this URL (*this) - * - * @see equals() - */ - KURL& operator=( const KURL& _u ); - - /** - * @brief Assigns the URL, given as a string, to this one - * - * This will reset the current URL and parse the given string. - * See the similar constructor for known limitations. - * - * @param _url the TQString to parse for values - * - * @return a reference to this URL (*this) - * - * @see equals() - * @see KURL(const TQString &, int) - */ - KURL& operator=( const TQString& _url ); - - /** - * @brief Assigns the URL, given as a C string, to this one - * - * This will reset the current URL and parse the given string. - * See the similar constructor for known limitations. - * - * @param _url the C string to parse for values - * - * @return a reference to this URL (*this) - * - * @see equals() - * @see KURL(const char *, int) - */ - KURL& operator=( const char * _url ); - - /** - * @brief Assigns the URL, given as a Qt URL, to this one - * - * This will reset the current URL and parse the given string. - * - * @param u the Qt URL to take the values from - * - * @return a reference to this URL (*this) - * - * @see equals() - * @see KURL(const TQUrl &) - */ - KURL& operator=( const TQUrl & u ); - - /** - * @brief 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 @p ignore_trailing set to - * @c false (default) - * - * @param _u the URL to compare to - * - * @return @c true if equal and neither this URL nor @p _u is malformed. - * Otherwise @c false - * - * @see equals() - * @see isValid() - * @see operator!=() - * @see operator<() - */ - bool operator==( const KURL& _u ) const; - - /** - * @brief Tests if this URL is equal to the one given as a string - * - * Creates a KURL instance for @p _u and compares with that using - * the equality operator for two KURLs. - * - * See the respective constructor for known limitations. - * - * @param _u the string to compare to - * - * @return @c true if equal and neither this URL nor @p _u is malformed. - * Otherwise @c false - * - * @see KURL(const TQString &, int) - * @see operator==(const KURL &) - * @see equals() - * @see isValid() - * @see operator!=() - * @see operator<() - */ - bool operator==( const TQString& _u ) const; - - /** - * @brief Tests if this URL is different from the given one - * - * Tests by negating the result of operator==() - * - * @param _u the URL to compare to - * - * @return the negated result of operator==() - * - * @see operator==() - * @see operator<() - */ - bool operator!=( const KURL& _u ) const { return !( *this == _u ); } - - /** - * @brief Tests if this URL is different from the one given as a string - * - * Tests by negating the result of operator==(const TQString &) - * - * @param _u the URL to compare to - * - * @return the negated result of operator==(const TQString &) - * - * @see operator==(const TQString &) - * @see operator<() - */ - bool operator!=( const TQString& _u ) const { return !( *this == _u ); } - - /** - * @brief Compares this URL with another one - * - * The same as equals(), just with a less obvious name. - * - * @param u the URL to compare this one with - * @param ignore_trailing set to @c true to ignore trailing @c '/' characters - * - * @return @c true if both URLs are the same - * - * @see operator==. This function should be used if you want to - * ignore trailing @c '/' characters - * - * @deprecated Use equals() instead. - */ - bool cmp( const KURL &u, bool ignore_trailing = false ) const KDE_DEPRECATED; - - /** - * @brief Compares this URL with another one - * - * @param u the URL to compare this one with - * @param ignore_trailing set to @c true to ignore trailing @c '/' characters - * - * @return @c true if both urls are the same - * - * @see operator==. This function should be used if you want to - * ignore trailing @c '/' characters - * - * @since 3.1 - */ - bool equals( const KURL &u, bool ignore_trailing = false ) const; // TODO KDE4: add bool _ignore_ref = false - - /** - * @brief Tests if the given URL is parent of this URL - * - * For instance, <tt>"ftp://host/dir/"</tt> is a parent of - * <tt>"ftp://host/dir/subdir/subsubdir/"</tt>. - * - * @return @c true if this URL is a parent of @p u (or the same URL as @p u) - * - * @see equals() - * @see cd() - */ - bool isParentOf( const KURL& u ) const; - - /** - * @brief Splits nested URLs into a list of URLs - * - * Example for a nested URL: - * @code - * file:///home/weis/kde.tgz#gzip:/#tar:/kdebase - * @endcode - * A URL like <tt>"http://www.kde.org#tar:/kde/README.hml#ref1"</tt> will be - * split in <tt>"http://www.kde.org#ref1"</tt> and - * <tt>"tar:/kde/README.html#ref1"</tt>. - * - * 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. - * - * @param _url the URL that has to be split - * - * @return an empty list on error or the list of split URLs - * - * @see hasSubURL() - * @see KURL(const TQString&, int) - * @see join() - */ - static List split( const TQString& _url ); - - /** - * @brief Splits nested URLs into a list of URLs - * - * Example for a nested URL: - * @code - * file:///home/weis/kde.tgz#gzip:/#tar:/kdebase - * @endcode - * A URL like <tt>"http://www.kde.org#tar:/kde/README.hml#ref1"</tt> will be - * split in <tt>"http://www.kde.org#ref1"</tt> and - * <tt>"tar:/kde/README.html#ref1"</tt>. - * - * 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. - * - * @param _url the URL that has to be split - * - * @return an empty list on error or the list of split URLs - * - * @see hasSubURL() - * @see join() - */ - static List split( const KURL& _url ); - - /** - * @brief 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. - * - * @param _list the list to join - * - * @return the joined URL or an invalid URL if the list is empty - * - * @see split() - */ - static KURL join( const List& _list ); - - /** - * @brief Creates a KURL object from a TQString representing either an - * absolute path or a real URL - * - * Use this method instead of - * @code - * TQString someDir = ... - * KURL url = someDir; - * @endcode - * - * Otherwise some characters (e.g. the '#') won't be encoded properly. - * - * @param text the string representation of the URL to convert - * - * @return the new KURL - * - * @see pathOrURL() - * @see KURL(const TQString&, int) - * - * @since 3.1 - */ - static KURL fromPathOrURL( const TQString& text ); - - /** - * @brief Encodes a string for use in URLs - * - * Convenience function. - * - * Convert tqunicoded string to local encoding and use %%-style - * encoding for all common delimiters / non-ascii characters. - * - * @param str the string to encode (can be @c TQString::null) - * @param encoding_hint MIB of encoding to use. - * See TQTextCodec::mibEnum() - * - * @return the encoded string - * - * @see encode_string_no_slash() - * @see decode_string() - */ - static TQString encode_string(const TQString &str, int encoding_hint = 0); - - /** - * @brief Encodes a string for use in URLs - * - * Convenience function. - * - * Convert tqunicoded string to local encoding and use %%-style - * encoding for all common delimiters and non-ascii characters - * as well as the slash @c '/'. - * - * @param str the string to encode (can be @c TQString::null) - * @param encoding_hint MIB of encoding to use. - * See TQTextCodec::mibEnum() - * - * @see encode_string() - * @see decode_string() - */ - static TQString encode_string_no_slash(const TQString &str, int encoding_hint = 0); - - /** - * @brief Decodes a string as used in URLs - * - * Convenience function. - * - * Decode %-style encoding and convert from local encoding to tqunicode. - * - * Reverse of encode_string() - * - * @param str the string to decode (can be @c TQString::null) - * @param encoding_hint MIB of original encoding of @p str . - * See TQTextCodec::mibEnum() - * - * @return the decoded string - * - * @see encode_string() - * @see encode_string_no_slash() - */ - static TQString decode_string(const TQString &str, int encoding_hint = 0); - - /** - * @brief Tests if a given URL is a relative as opposed to an absolute URL - * - * Convenience function. - * - * Returns whether @p _url is likely to be a "relative" URL instead of - * an "absolute" URL. - * - * @param _url the URL to examine - * @return @c true when the URL is likely to be "relative", - * @c false otherwise - * - * @see relativeURL() - */ - static bool isRelativeURL(const TQString &_url); - - /** - * @brief Creates an URL relative to a base URL for a given input URL - * - * Convenience function - * - * Returns a "relative URL" based on @p base_url that points to @p url. - * - * If no "relative URL" can be created, e.g. because the protocol - * and/or hostname differ between @p base_url and @p url an absolute - * URL is returned. - * - * @note if @p base_url represents a directory, it should contain - * a trailing slash - * - * @param base_url the URL to derive from - * @param url the URL to point to relatively from @p base_url - * @param encoding_hint MIB of original encoding of @p str . - * See TQTextCodec::mibEnum() - * - * @see isRelativeURL() - * @see relativePath() - * @see adjustPath() - */ - static TQString relativeURL(const KURL &base_url, const KURL &url, int encoding_hint = 0); - - /** - * @brief Creates a path relative to a base path for a given input path - * - * Convenience function - * - * Returns a relative path based on @p base_dir that points to @p path. - * - * @param base_dir the base directory to derive from - * @param path the new target directory - * @param isParent an optional pointer to a boolean which, if provided, will - * be set to reflect whether @p path has @p base_dir as a parent dir - * - * @see relativeURL() - */ - static TQString relativePath(const TQString &base_dir, const TQString &path, bool *isParent=0); - - /** - * @brief Determines which URI mode is suitable for processing URIs of a - * given protocol - * - * @param protocol the protocol name. See protocol() - * - * @return the URIMode suitable for the given protocol - * - * @see uriMode() - * - * @since 3.2 - */ - static URIMode uriModeForProtocol(const TQString& protocol); - -#ifdef KDE_NO_COMPAT -private: -#endif - /** - * @deprecated change code to call fileName() - */ - TQString filename( bool _ignore_trailing_slash_in_path = true ) const - { - return fileName(_ignore_trailing_slash_in_path); - } - -protected: - /** - * @brief Resets the members to their "null" state - * - * All TQString members get reset to @c TQString::null, the port to @c 0 - * the URIMode to @c 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. - * - * @see isValid() - * @see isEmpty() - */ - void reset(); - - /** - * @brief Parses the given string and fills the URL's values on success - * - * Treats the string as an URL. - * - * @param _url the string to parse - * @param encoding_hint MIB of original encoding of @p str . - * See TQTextCodec::mibEnum() - */ - void parseURL( const TQString& _url, int encoding_hint = 0 ); - /** - * @brief Parses the given string and fills the URL's values on success - * - * Treats the string as a generic URI. - * - * @param _url the string to parse - * @param encoding_hint MIB of original encoding of @p str . - * See TQTextCodec::mibEnum() - */ - void parseRawURI( const TQString& _url, int encoding_hint = 0 ); - /** - * @brief Parses the given string and fills the URL's values on success - * - * Treats the string as a @c "mailto:" URI. - * - * @param _url the string to parse - * @param encoding_hint MIB of original encoding of @p str . - * See TQTextCodec::mibEnum() - */ - void parseMailto( const TQString& _url, int encoding_hint = 0 ); - /** - * @brief Parses the given string and fills the URL's values on success - * - * @param _url the string to parse - * @param encoding_hint MIB of original encoding of @p str . - * See TQTextCodec::mibEnum() - */ - void parse( const TQString& _url, int encoding_hint = 0 ); - -private: - void _setQuery( const TQString& _txt, int encoding_hint = 0); - - TQString m_strProtocol; - TQString m_strUser; - TQString m_strPass; - TQString m_strHost; - TQString m_strPath; - TQString m_strRef_encoded; - TQString m_strQuery_encoded; - bool m_bIsMalformed : 1; - enum URIMode m_iUriMode : 3; - uint freeForUse : 4; - unsigned short int m_iPort; - TQString m_strPath_encoded; - - friend KDECORE_EXPORT TQDataStream & operator<< (TQDataStream & s, const KURL & a); - friend KDECORE_EXPORT TQDataStream & operator>> (TQDataStream & s, KURL & a); -private: - KURLPrivate* d; -}; - -/** - * \relates KURL - * Compares URLs. They are parsed, split and compared. - * Two malformed URLs with the same string representation - * are nevertheless considered to be unequal. - * That means no malformed URL equals anything else. - */ -KDECORE_EXPORT bool urlcmp( const TQString& _url1, const TQString& _url2 ); - -/** - * \relates KURL - * Compares URLs. They are parsed, split and compared. - * Two malformed URLs with the same string representation - * are nevertheless considered to be unequal. - * That means no malformed URL equals anything else. - * - * @param _url1 A reference URL - * @param _url2 A URL that will be compared with the reference URL - * @param _ignore_trailing Described in KURL::cmp - * @param _ignore_ref If true, disables comparison of HTML-style references. - */ -KDECORE_EXPORT bool urlcmp( const TQString& _url1, const TQString& _url2, bool _ignore_trailing, bool _ignore_ref ); - -KDECORE_EXPORT TQDataStream & operator<< (TQDataStream & s, const KURL & a); -KDECORE_EXPORT TQDataStream & operator>> (TQDataStream & s, KURL & a); - -#endif |