kurl.h

来自「konqueror3 embedded版本, KDE环境下的当家浏览器的嵌入式版」· C头文件 代码 · 共 1,829 行 · 第 1/4 页

/* This file is part of the KDE libraries
 *  Copyright (C) 1999 Torben Weis <[e-mail]>
 *
 *  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 <qstring.h>
#include <qvaluelist.h>
#include "kdelibs_export.h"

class QUrl;
class QStringList;
template <typename K, typename V> class QMap;

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 QString&) 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 QString&):
 * @code
 *     KURL kurl;
 *     kurl.setPath( "/bar/#foo#" );
 *     QString 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() )
 *       QString 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
 *    QString dirUrl = "file:///bar/";
 *    QString fileName = "#foo#";
 *    QString 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/" );
 *    QString fileName = "#foo#";
 *    url.addPath( fileName );
 *    QString 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:[e-mail]/bar/%23foo%23");
 *    QString visibleURL = url.prettyURL(); // -> "ftp://[e-mail]/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 <[e-mail]>
 */
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 QValueList that contains KURLs with a few
   * convenience methods.
   * @see KURL
   * @see QValueList
   */
  class KDECORE_EXPORT List : public QValueList<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 QString &, int)
       */
      List(const QStringList &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()
       */
      QStringList 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 QTextCodec::mibEnum()
   *
   * @see fromPathOrURL()
   */
  KURL( const QString& 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 QTextCodec::mibEnum()
   *
   * @see fromPathOrURL()
   * @see QString::fromLatin1()
   */
  KURL( const char * url, int encoding_hint = 0 );
  /**
   * @brief Constructor taking an URL encoded in a QCString
   *
   * Constructor taking a QCString @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 QTextCodec::mibEnum()
   *
   * @see fromPathOrURL()
   * @see QString::fromLatin1()
   */
  KURL( const QCString& 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 QUrl &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 QTextCodec::mibEnum()
   *
   * @see fromPathOrURL()
   */
  KURL( const KURL& _baseurl, const QString& _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 QString::null will be returned
   *
   * @see setProtocol()
   * @see isValid()
   */
  QString protocol() const { return m_bIsMalformed ? QString::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 QString& _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 QString::null if there is no user name
   *
   * @see setUser()
   * @see hasUser()
   */
  QString 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 QString::null to remove the user
   *
   * @see user()
   * @see hasUser()
   * @see hasPass()
   */
  void setUser( const QString& _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 QString::null if it does not exist
   *
   * @see setPass()
   * @see hasPass()
   * @see hasUser()
   */
  QString 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 QString::null to remove the password
   *
   * @see pass()
   * @see hasPass()
   * @see hasUser()
   */
  void setPass( const QString& _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