kurl.h

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

   * 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 QString::null if no host is set
   *
   * @see setHost()
   * @see hasHost()
   */
  QString 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 QString::null to remove the host
   *
   * @see host()
   * @see hasHost()
   */
  void setHost( const QString& _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 QString::null if no
   *         path is set
   *
   * @see path(int)
   * @see setPath()
   * @see hasPath()
   */
  QString 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 QString::null if no
   *         path is set
   *
   * @see path()
   * @see setPath()
   * @see hasPath()
   * @see adjustPath()
   */
  QString 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 QString::null to remove the path
   *
   * @see path()
   * @see path(int)
   * @see hasPath()
   */
  void setPath( const QString& 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 QTextCodec::mibEnum()
   *
   * @see encodedPathAndQuery()
   * @see setPath()
   * @see setQuery()
   */
  void setEncodedPathAndQuery( const QString& _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 QTextCodec::mibEnum()
   *
   * @see setEncodedPathAndQuery()
   * @see setPath()
   */
  void setEncodedPath(const QString& _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 QTextCodec::mibEnum()
   *
   * @return the concatenation of the encoded path , @c '?' and the
   *         encoded query
   *
   * @see setEncodedPathAndQuery()
   * @see path()
   * @see query()
   */
  QString 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 QTextCodec::mibEnum()
   *
   * @see query()
   */
  void setQuery( const QString& _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 QString::null if there is none
   *
   * @see setQuery()
   */
  QString query() const;

  /**
   * @brief Returns the encoded reference of the URL
   *
   * The reference is @em never decoded automatically.
   *
   * @return the undecoded reference, or @c QString::null if there is none
   *
   * @see setRef()
   * @see hasRef()
   * @see htmlRef()
   */
  QString 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 QString::null to remove it
   *
   * @see ref()
   * @see hasRef()
   */
  void setRef( const QString& _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()
   */
  QString 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()
   */
  QString 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 QString::null to remove it
   *
   * @see htmlRef()
   * @see hasHTMLRef()
   */
  void setHTMLRef( const QString& _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 QString::null to remove the
   *                 encoding
   *
   * @see fileEncoding()
   * @see QTextCodec::codecForName()
   */
  void setFileEncoding(const QString &encoding);

  /**
   * @brief Returns encoding information of the URL
   *
   * The encoding information is the content of the @c "charset" parameter.
   *
   * @return an encoding suitable for QTextCodec::codecForName()
   *         or @c QString::null if not encoding was specified
   */
  QString 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 QString& 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 QString::null if the
   *         specified item does not exist
   *
   * @see addQueryItem()
   * @see removeQueryItem()
   * @see queryItems()
   * @see query()
   */
  QString queryItem( const QString& 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 QTextCodec::mibEnum()
   *
   * @return the value of the given query item name or @c QString::null if the
   *         specified item does not exist
   *
   * @see addQueryItem()
   * @see removeQueryItem()
   * @see queryItems()
   * @see query()