File indexing completed on 2024-06-16 10:06:20

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000-2001, 2003, 2010 Dawit Alemayehu <adawit at kde.org>
0004 
0005     Original author
0006     SPDX-FileCopyrightText: 2000 Yves Arrouye <yves@realnames.com>
0007 
0008     SPDX-License-Identifier: LGPL-2.0-or-later
0009 */
0010 
0011 #ifndef KURIFILTER_H
0012 #define KURIFILTER_H
0013 
0014 #include "kiowidgets_export.h"
0015 
0016 #include <QHash>
0017 #include <QObject>
0018 #include <QPair>
0019 #include <QStringList>
0020 #include <QUrl>
0021 
0022 #include <memory>
0023 
0024 #ifdef Q_OS_WIN
0025 #undef ERROR
0026 #endif
0027 
0028 class KUriFilterPrivate;
0029 class KUriFilterDataPrivate;
0030 class KCModule;
0031 class QHostInfo;
0032 
0033 /**
0034  * @class KUriFilterSearchProvider kurifilter.h <KUriFilter>
0035  *
0036  * Class that holds information about a search provider.
0037  *
0038  * @since 4.6
0039  */
0040 class KIOWIDGETS_EXPORT KUriFilterSearchProvider
0041 {
0042 public:
0043     /**
0044      * Default constructor.
0045      */
0046     KUriFilterSearchProvider();
0047 
0048     /**
0049      * Copy constructor.
0050      */
0051     KUriFilterSearchProvider(const KUriFilterSearchProvider &);
0052 
0053     /**
0054      * Destructor.
0055      */
0056     virtual ~KUriFilterSearchProvider();
0057 
0058     /**
0059      * Returns the desktop filename of the search provider without any extension.
0060      *
0061      * For example, if the desktop filename of the search provider was
0062      * "foobar.desktop", this function will return "foobar".
0063      */
0064     QString desktopEntryName() const;
0065 
0066     /**
0067      * Returns the descriptive name of the search provider, e.g.\ "Google News".
0068      *
0069      * This name comes from the "Name=" property entry in the desktop file that
0070      * contains the search provider's information.
0071      */
0072     QString name() const;
0073 
0074     /**
0075      * Returns the icon name associated with the search provider when available.
0076      */
0077     virtual QString iconName() const;
0078 
0079     /**
0080      * Returns all the web shortcut keys associated with this search provider.
0081      *
0082      * @see defaultKey
0083      */
0084     QStringList keys() const;
0085 
0086     /**
0087      * Returns the default web shortcut key for this search provider.
0088      *
0089      * Right now this is the same as doing keys().first(), it might however
0090      * change based on what the backend plugins do.
0091      *
0092      * @see keys
0093      */
0094     QString defaultKey() const;
0095 
0096     /**
0097      * Assignment operator.
0098      */
0099     KUriFilterSearchProvider &operator=(const KUriFilterSearchProvider &);
0100 
0101 protected:
0102     void setDesktopEntryName(const QString &);
0103     void setIconName(const QString &);
0104     void setKeys(const QStringList &);
0105     void setName(const QString &);
0106 
0107 private:
0108     friend class KUriFilterPlugin;
0109     class KUriFilterSearchProviderPrivate;
0110     std::unique_ptr<KUriFilterSearchProviderPrivate> const d;
0111 };
0112 
0113 /**
0114  * @class KUriFilterData kurifilter.h <KUriFilter>
0115  *
0116  * This class is a basic messaging class used to exchange filtering information
0117  * between the filter plugins and the application requesting the filtering
0118  * service.
0119  *
0120  * Use this object if you require a more detailed information about the URI you
0121  * want to filter. Any application can create an instance of this class and send
0122  * it to KUriFilter to have the plugins fill out all possible information about
0123  * the URI.
0124  *
0125  * On successful filtering you can use @ref uriType() to determine what type
0126  * of resource the request was filtered into. See @ref KUriFilter::UriTypes for
0127  * details. If an error is encountered, then @ref KUriFilter::Error is returned.
0128  * You can use @ref errorMsg to obtain the error information.
0129  *
0130  * The functions in this class are not reentrant.
0131  *
0132  * \b Example
0133  *
0134  * Here is a basic example of how this class is used with @ref KUriFilter:
0135  * \code
0136  *   KUriFilterData filterData (QLatin1String("kde.org"));
0137  *   bool filtered = KUriFilter::self()->filterUri(filterData);
0138  * \endcode
0139  *
0140  * If you are only interested in getting the list of preferred search providers,
0141  * then you can do the following:
0142  *
0143  * \code
0144  * KUriFilterData data;
0145  * data.setData("<text-to-search-for>");
0146  * data.setSearchFilteringOption(KUriFilterData::RetrievePreferredSearchProvidersOnly);
0147  * bool filtered = KUriFilter::self()->filterSearchUri(data, KUriFilter::NormalTextFilter);
0148  * \endcode
0149  *
0150  * @short A class for exchanging filtering information.
0151  * @author Dawit Alemayehu <adawit at kde.org>
0152  */
0153 
0154 class KIOWIDGETS_EXPORT KUriFilterData
0155 {
0156 public:
0157     /**
0158      * Describes the type of the URI that was filtered.
0159      */
0160     enum UriTypes {
0161         NetProtocol = 0, ///< Any network protocol: http, ftp, nttp, pop3, etc...
0162         LocalFile, ///< A local file whose executable flag is not set
0163         LocalDir, ///< A local directory
0164         Executable, ///< A local file whose executable flag is set
0165         Help, ///< A man or info page
0166         Shell, ///< A shell executable (ex: echo "Test..." >> ~/testfile)
0167         Blocked, ///< A URI that should be blocked/filtered (ex: ad filtering)
0168         Error, ///< An incorrect URI (ex: "~johndoe" when user johndoe does not exist in that system)
0169         Unknown, ///< A URI that is not identified. Default value when a KUriFilterData is first created.
0170     };
0171 
0172     /**
0173      * This enum describes the search filtering options to be used.
0174      *
0175      * @li SearchFilterOptionNone
0176      *     No search filter options are set and normal filtering is performed
0177      *     on the input data.
0178      * @li RetrieveSearchProvidersOnly
0179      *     If set, the list of all available search providers are returned without
0180      *     any input filtering. This flag only applies when used in conjunction
0181      *     with the @ref KUriFilter::NormalTextFilter flag.
0182      * @li RetrievePreferredSearchProvidersOnly
0183      *     If set, the list of preferred search providers are returned without
0184      *     any input filtering. This flag only applies when used in conjunction
0185      *     with the @ref KUriFilter::NormalTextFilter flag.
0186      * @li RetrieveAvailableSearchProvidersOnly
0187      *     Same as doing RetrievePreferredSearchProvidersOnly | RetrieveSearchProvidersOnly,
0188      *     where all available search providers are returned if no preferred ones
0189      *     ones are available. No input filtering will be performed.
0190      *
0191      * @see setSearchFilteringOptions
0192      * @see KUriFilter::filterSearchUri
0193      * @see SearchFilterOptions
0194      * @since 4.6
0195      */
0196     enum SearchFilterOption {
0197         SearchFilterOptionNone = 0x0,
0198         RetrieveSearchProvidersOnly = 0x01,
0199         RetrievePreferredSearchProvidersOnly = 0x02,
0200         RetrieveAvailableSearchProvidersOnly = (RetrievePreferredSearchProvidersOnly | RetrieveSearchProvidersOnly),
0201     };
0202     /**
0203      * Stores a combination of #SearchFilterOption values.
0204      */
0205     Q_DECLARE_FLAGS(SearchFilterOptions, SearchFilterOption)
0206 
0207     /**
0208      * Default constructor.
0209      *
0210      * Creates a UriFilterData object.
0211      */
0212     KUriFilterData();
0213 
0214     /**
0215      * Creates a KUriFilterData object from the given URL.
0216      *
0217      * @param url is the URL to be filtered.
0218      */
0219     explicit KUriFilterData(const QUrl &url);
0220 
0221     /**
0222      * Creates a KUriFilterData object from the given string.
0223      *
0224      * @param url is the string to be filtered.
0225      */
0226     explicit KUriFilterData(const QString &url);
0227 
0228     /**
0229      * Copy constructor.
0230      *
0231      * Creates a KUriFilterData object from another KURIFilterData object.
0232      *
0233      * @param other the uri filter data to be copied.
0234      */
0235     KUriFilterData(const KUriFilterData &other);
0236 
0237     /**
0238      * Destructor.
0239      */
0240     ~KUriFilterData();
0241 
0242     /**
0243      * Returns the filtered or the original URL.
0244      *
0245      * If one of the plugins successfully filtered the original input, this
0246      * function returns it. Otherwise, it will return the input itself.
0247      *
0248      * @return the filtered or original url.
0249      */
0250     QUrl uri() const;
0251 
0252     /**
0253      * Returns an error message.
0254      *
0255      * This functions returns the error message set by the plugin whenever the
0256      * uri type is set to KUriFilterData::ERROR. Otherwise, it returns a nullptr
0257      * string.
0258      *
0259      * @return the error message or a nullptr when there is none.
0260      */
0261     QString errorMsg() const;
0262 
0263     /**
0264      * Returns the URI type.
0265      *
0266      * This method always returns KUriFilterData::UNKNOWN if the given URL was
0267      * not filtered.
0268      *
0269      * @return the type of the URI
0270      */
0271     UriTypes uriType() const;
0272 
0273     /**
0274      * Returns the absolute path if one has already been set.
0275      *
0276      * @return the absolute path, or QString()
0277      *
0278      * @see hasAbsolutePath()
0279      */
0280     QString absolutePath() const;
0281 
0282     /**
0283      * Checks whether the supplied data had an absolute path.
0284      *
0285      * @return true if the supplied data has an absolute path
0286      *
0287      * @see absolutePath()
0288      */
0289     bool hasAbsolutePath() const;
0290 
0291     /**
0292      * Returns the command line options and arguments for a local resource
0293      * when present.
0294      *
0295      * @return options and arguments when present, otherwise QString()
0296      */
0297     QString argsAndOptions() const;
0298 
0299     /**
0300      * Checks whether the current data is a local resource with command line
0301      * options and arguments.
0302      *
0303      * @return true if the current data has command line options and arguments
0304      */
0305     bool hasArgsAndOptions() const;
0306 
0307     /**
0308      * @return true if the filters should attempt to check whether the
0309      * supplied uri is an executable. False otherwise.
0310      */
0311     bool checkForExecutables() const;
0312 
0313     /**
0314      * The string as typed by the user, before any URL processing is done.
0315      */
0316     QString typedString() const;
0317 
0318     /**
0319      * Returns the search term portion of the typed string.
0320      *
0321      * If the @ref typedString was not filtered by a search filter plugin, this
0322      * function returns an empty string.
0323      *
0324      * @see typedString
0325      * @since 4.5
0326      */
0327     QString searchTerm() const;
0328 
0329     /**
0330      * Returns the character that is used to separate the search term from the
0331      * keyword.
0332      *
0333      * If @ref typedString was not filtered by a search filter plugin, this
0334      * function returns a null character.
0335      *
0336      * @see typedString
0337      * @since 4.5
0338      */
0339     QChar searchTermSeparator() const;
0340 
0341     /**
0342      * Returns the name of the search service provider, e.g.\ Google.
0343      *
0344      * If @ref typedString was not filtered by a search filter plugin, this
0345      * function returns an empty string.
0346      *
0347      * @see typedString
0348      * @since 4.5
0349      */
0350     QString searchProvider() const;
0351 
0352     /**
0353      * Returns a list of the names of preferred or available search providers.
0354      *
0355      * This function returns the list of providers marked as preferred whenever
0356      * the input data, i.e. @ref typedString, is successfully filtered.
0357      *
0358      * If no default search provider has been selected prior to a filter request,
0359      * this function will return an empty list. To avoid this problem you must
0360      * either set an alternate default search provider using @ref setAlternateDefaultSearchProvider
0361      * or set one of the @ref SearchFilterOption flags if you are only interested
0362      * in getting the list of providers and not filtering the input.
0363      *
0364      * Additionally, you can also provide alternate search providers in case
0365      * there are no preferred ones already selected.
0366      *
0367      * You can use @ref queryForPreferredServiceProvider to obtain the query
0368      * associated with the list of search providers returned by this function.
0369      *
0370      * @see setAlternateSearchProviders
0371      * @see setAlternateDefaultSearchProvider
0372      * @see setSearchFilteringOption
0373      * @see queryForPreferredServiceProvider
0374      * @since 4.5
0375      */
0376     QStringList preferredSearchProviders() const;
0377 
0378     /**
0379      * Returns information about @p provider.
0380      *
0381      * You can use this function to obtain the more information about the search
0382      * providers returned by @ref preferredSearchProviders.
0383      *
0384      * @see preferredSearchProviders
0385      * @see KUriFilterSearchProvider
0386      * @since 4.6
0387      */
0388     KUriFilterSearchProvider queryForSearchProvider(const QString &provider) const;
0389 
0390     /**
0391      * Returns the web shortcut url for the given preferred search provider.
0392      *
0393      * You can use this function to obtain the query for the preferred search
0394      * providers returned by @ref preferredSearchProviders.
0395      *
0396      * The query returned by this function is in web shortcut format, i.e.
0397      * "gg:foo bar", and must be re-filtered through KUriFilter to obtain a
0398      * valid url.
0399      *
0400      * @see preferredSearchProviders
0401      * @since 4.5
0402      */
0403     QString queryForPreferredSearchProvider(const QString &provider) const;
0404 
0405     /**
0406      * Returns all the query urls for the given search provider.
0407      *
0408      * Use this function to obtain all the different queries that can be used
0409      * for the given provider. For example, if a search engine provider named
0410      * "foobar" has web shortcuts named "foobar", "foo" and "bar", then this
0411      * function, unlike @ref queryForPreferredSearchProvider, will return a
0412      * a query for each and every web shortcut.
0413      *
0414      * @see queryForPreferredSearchProvider
0415      * @since 4.6
0416      */
0417     QStringList allQueriesForSearchProvider(const QString &provider) const;
0418 
0419     /**
0420      * Returns the icon associated with the given preferred search provider.
0421      *
0422      * You can use this function to obtain the icon names associated with the
0423      * preferred search providers returned by @ref preferredSearchProviders.
0424      *
0425      * @see preferredSearchProviders
0426      * @since 4.5
0427      */
0428     QString iconNameForPreferredSearchProvider(const QString &provider) const;
0429 
0430     /**
0431      * Returns the list of alternate search providers.
0432      *
0433      * This function returns an empty list if @ref setAlternateSearchProviders
0434      * was not called to set the alternate search providers to be when no
0435      * preferred providers have been chosen by the user through the search
0436      * configuration module.
0437      *
0438      * @see setAlternatteSearchProviders
0439      * @see preferredSearchProviders
0440      * @since 4.5
0441      */
0442     QStringList alternateSearchProviders() const;
0443 
0444     /**
0445      * Returns the search provider to use when a default provider is not available.
0446      *
0447      * This function returns an empty string if @ref setAlternateDefaultSearchProvider
0448      * was not called to set the default search provider to be used when none has been
0449      * chosen by the user through the search configuration module.
0450      *
0451      * @see setAlternateDefaultSearchProvider
0452      * @since 4.5
0453      */
0454     QString alternateDefaultSearchProvider() const;
0455 
0456     /**
0457      * Returns the default protocol to use when filtering potentially valid url inputs.
0458      *
0459      * By default this function will return an empty string.
0460      *
0461      * @see setDefaultUrlScheme
0462      * @since 4.6
0463      */
0464     QString defaultUrlScheme() const;
0465 
0466     /**
0467      * Returns the specified search filter options.
0468      *
0469      * By default this function returns @ref SearchFilterOptionNone.
0470      *
0471      * @see setSearchFilteringOptions
0472      * @since 4.6
0473      */
0474     SearchFilterOptions searchFilteringOptions() const;
0475 
0476     /**
0477      * The name of the icon that matches the current filtered URL.
0478      *
0479      * This function returns a null string by default and when no icon is found
0480      * for the filtered URL.
0481      */
0482     QString iconName();
0483 
0484     /**
0485      * Check whether the provided uri is executable or not.
0486      *
0487      * Setting this to false ensures that typing the name of an executable does
0488      * not start that application. This is useful in the location bar of a
0489      * browser. The default value is true.
0490      */
0491     void setCheckForExecutables(bool check);
0492 
0493     /**
0494      * Same as above except the argument is a URL.
0495      *
0496      * Use this function to set the string to be filtered when you construct an
0497      * empty filter object.
0498      *
0499      * @param url the URL to be filtered.
0500      */
0501     void setData(const QUrl &url);
0502 
0503     /**
0504      * Sets the URL to be filtered.
0505      *
0506      * Use this function to set the string to be
0507      * filtered when you construct an empty filter
0508      * object.
0509      *
0510      * @param url the string to be filtered.
0511      */
0512     void setData(const QString &url);
0513 
0514     /**
0515      * Sets the absolute path to be used whenever the supplied data is a
0516      * relative local URL.
0517      *
0518      * NOTE: This function should only be used for local resources, i.e. the
0519      * "file:/" protocol. It is useful for specifying the absolute path in
0520      * cases where the actual URL might be relative. If deriving the path from
0521      * a QUrl, make sure you set the argument for this function to the result
0522      * of calling path () instead of url ().
0523      *
0524      * @param abs_path  the absolute path to the local resource.
0525      *
0526      * @return true if absolute path is successfully set. Otherwise, false.
0527      */
0528     bool setAbsolutePath(const QString &abs_path);
0529 
0530     /**
0531      * Sets a list of search providers to use in case no preferred search
0532      * providers are available.
0533      *
0534      * The list of preferred search providers set using this function will only
0535      * be used if the default and favorite search providers have not yet been
0536      * selected by the user. Otherwise, the providers specified through this
0537      * function will be ignored.
0538      *
0539      * @see alternateSearchProviders
0540      * @see preferredSearchProviders
0541      * @since 4.5
0542      */
0543     void setAlternateSearchProviders(const QStringList &providers);
0544 
0545     /**
0546      * Sets the search provider to use in case no default provider is available.
0547      *
0548      * The default search provider set using this function will only be used if
0549      * the default and favorite search providers have not yet been selected by
0550      * the user. Otherwise, the default provider specified by through function
0551      * will be ignored.
0552      *
0553      * @see alternateDefaultSearchProvider
0554      * @see preferredSearchProviders
0555      * @since 4.5
0556      */
0557     void setAlternateDefaultSearchProvider(const QString &provider);
0558 
0559     /**
0560      * Sets the default scheme used when filtering potentially valid url inputs.
0561      *
0562      * Use this function to change the default protocol used when filtering
0563      * potentially valid url inputs. The default protocol is http.
0564      *
0565      * If the scheme is specified without a separator, then  "://" will be used
0566      * as the separator by default. For example, if the default url scheme was
0567      * simply set to "ftp", then a potentially valid url input such as "kde.org"
0568      * will be filtered to "ftp://kde.org".
0569      *
0570      * @see defaultUrlScheme
0571      * @since 4.6
0572      */
0573     void setDefaultUrlScheme(const QString &);
0574 
0575     /**
0576      * Sets the options used by search filter plugins to filter requests.
0577      *
0578      * The default search filter option is @ref SearchFilterOptionNone. See
0579      * @ref SearchFilterOption for the description of the other flags.
0580      *
0581      * It is important to note that the options set through this function can
0582      * prevent any filtering from being performed by search filter plugins.
0583      * As such, @ref uriTypes can return KUriFilterData::Unknown and @ref uri
0584      * can return an invalid url even though the filtering request returned
0585      * a successful response.
0586      *
0587      * @see searchFilteringOptions
0588      * @since 4.6
0589      */
0590     void setSearchFilteringOptions(SearchFilterOptions options);
0591 
0592     /**
0593      * Overloaded assignment operator.
0594      *
0595      * This function allows you to easily assign a QUrl
0596      * to a KUriFilterData object.
0597      *
0598      * @return an instance of a KUriFilterData object.
0599      */
0600     KUriFilterData &operator=(const QUrl &url);
0601 
0602     /**
0603      * Overloaded assignment operator.
0604      *
0605      * This function allows you to easily assign a QString to a KUriFilterData
0606      * object.
0607      *
0608      * @return an instance of a KUriFilterData object.
0609      */
0610     KUriFilterData &operator=(const QString &url);
0611 
0612 private:
0613     friend class KUriFilterPlugin;
0614     std::unique_ptr<KUriFilterDataPrivate> d;
0615 };
0616 
0617 /**
0618  * @class KUriFilterPlugin kurifilter.h <KUriFilter>
0619  *
0620  * Base class for URI filter plugins.
0621  *
0622  * This class applies a single filter to a URI. All plugins designed to provide
0623  * URI filtering service should inherit from this abstract class and provide a
0624  * concrete implementation.
0625  *
0626  * All inheriting classes need to implement the pure virtual function
0627  * @ref filterUri.
0628  *
0629  * @short Abstract class for URI filter plugins.
0630  */
0631 class KIOWIDGETS_EXPORT KUriFilterPlugin : public QObject // TODO KF6: move to separate header (maybe we don't need to install it then)
0632 {
0633     Q_OBJECT
0634 
0635 public:
0636 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 6)
0637     /**
0638      * List for holding the following search provider information:
0639      * ([search provider name], [search query, search query icon name])
0640      *
0641      * @since 4.5
0642      * @deprecated Since 4.6, use @ref KUriFilterSearchProvider instead. See @ref setSearchProviders;
0643      */
0644     KIOWIDGETS_DEPRECATED_VERSION(4, 6, "Use KUriFilterSearchProvider")
0645     typedef QHash<QString, QPair<QString, QString>> ProviderInfoList;
0646 #endif
0647 
0648     /**
0649      * Constructs a filter plugin with a given name
0650      *
0651      * @param parent the parent object, or @c nullptr for no parent
0652      * @param name the name of the plugin, mandatory
0653      */
0654     explicit KUriFilterPlugin(const QString &name, QObject *parent = nullptr);
0655 
0656     // KF6 TODO ~KUriFilterPlugin();
0657 
0658     /**
0659      * Filters a URI.
0660      *
0661      * @param data the URI data to be filtered.
0662      * @return A boolean indicating whether the URI has been changed.
0663      */
0664     virtual bool filterUri(KUriFilterData &data) const = 0;
0665 
0666     /**
0667      * Creates a configuration module for the filter.
0668      *
0669      * It is the responsibility of the caller to delete the module once it is
0670      * not needed anymore.
0671      *
0672      * @return A configuration module, or @c nullptr if the filter isn't configurable.
0673      */
0674     virtual KCModule *configModule(QWidget *, const char *) const; // TODO KF6: unused, remove
0675 
0676     /**
0677      * Returns the name of the configuration module for the filter.
0678      *
0679      * @return the name of a configuration module or QString() if none.
0680      */
0681     virtual QString configName() const; // TODO KF6: unused, remove
0682 
0683 protected:
0684     /**
0685      * Sets the URL in @p data to @p uri.
0686      */
0687     void setFilteredUri(KUriFilterData &data, const QUrl &uri) const;
0688 
0689     /**
0690      * Sets the error message in @p data to @p errormsg.
0691      */
0692     void setErrorMsg(KUriFilterData &data, const QString &errmsg) const;
0693 
0694     /**
0695      * Sets the URI type in @p data to @p type.
0696      */
0697     void setUriType(KUriFilterData &data, KUriFilterData::UriTypes type) const;
0698 
0699     /**
0700      * Sets the arguments and options string in @p data to @p args if any were
0701      * found during filtering.
0702      */
0703     void setArguments(KUriFilterData &data, const QString &args) const;
0704 
0705     /**
0706      * Sets the name of the search provider, the search term and keyword/term
0707      * separator in @p data.
0708      *
0709      * @since 4.5
0710      */
0711     void setSearchProvider(KUriFilterData &data, const QString &provider, const QString &term, const QChar &separator) const;
0712 
0713     /**
0714      * Sets the information about the search @p providers in @p data.
0715      *
0716      * @since 4.6
0717      */
0718     void setSearchProviders(KUriFilterData &data, const QList<KUriFilterSearchProvider *> &providers) const;
0719 
0720     /**
0721      * Returns the icon name for the given @p url and URI @p type.
0722      *
0723      * @since 4.5
0724      */
0725     QString iconNameFor(const QUrl &url, KUriFilterData::UriTypes type) const;
0726 
0727     /**
0728      * Performs a DNS lookup for @p hostname and returns the result.
0729      *
0730      * This function uses the KIO/KHTML DNS cache to speed up the
0731      * lookup. It also avoids doing a reverse lookup if the given
0732      * host name is already an ip address.
0733      *
0734      * \note All uri filter plugins that need to perform a hostname
0735      * lookup should use this function.
0736      *
0737      * @param hostname   the hostname to lookup.
0738      * @param timeout    the amount of time in msecs to wait for the lookup.
0739      * @return the result of the host name lookup.
0740      *
0741      * @since 4.7
0742      */
0743     QHostInfo resolveName(const QString &hostname, unsigned long timeout) const;
0744 
0745 private:
0746     class KUriFilterPluginPrivate *const d;
0747 };
0748 
0749 /**
0750  * @class KUriFilter kurifilter.h <KUriFilter>
0751  *
0752  * KUriFilter applies a number of filters to a URI and returns a filtered version if any
0753  * filter matches.
0754  * A simple example is "kde.org" to "http://www.kde.org", which is commonplace in web browsers.
0755  *
0756  * The filters are implemented as plugins in @ref KUriFilterPlugin subclasses.
0757  *
0758  * KUriFilter is a singleton object: obtain the instance by calling
0759  * @p KUriFilter::self() and use the public member functions to
0760  * perform the filtering.
0761  *
0762  * \b Example
0763  *
0764  * To simply filter a given string:
0765  *
0766  * \code
0767  * QString url("kde.org");
0768  * bool filtered = KUriFilter::self()->filteredUri( url );
0769  * \endcode
0770  *
0771  * You can alternatively use a QUrl:
0772  *
0773  * \code
0774  * QUrl url("kde.org");
0775  * bool filtered = KUriFilter::self()->filterUri( url );
0776  * \endcode
0777  *
0778  * If you have a constant string or a constant URL, simply invoke the
0779  * corresponding function to obtain the filtered string or URL instead
0780  * of a boolean flag:
0781  *
0782  * \code
0783  * QString filteredText = KUriFilter::self()->filteredUri( "kde.org" );
0784  * \endcode
0785  *
0786  * All of the above examples should result in "kde.org" being filtered into
0787  * "http://kde.org".
0788  *
0789  * You can also restrict the filters to be used by supplying the name of the
0790  * filters you want to use. By default all available filters are used.
0791  *
0792  * To use specific filters, add the names of the filters you want to use to a
0793  * QStringList and invoke the appropriate filtering function.
0794  *
0795  * The examples below show the use of specific filters. KDE ships with the
0796  * following filter plugins by default:
0797  *
0798  * kshorturifilter:
0799  * This is used for filtering potentially valid url inputs such as "kde.org"
0800  * Additionally it filters shell variables and shortcuts such as $HOME and
0801  * ~ as well as man and info page shortcuts, # and ## respectively.
0802  *
0803  * kuriikwsfilter:
0804  * This is used for filtering normal input text into a web search url using the
0805  * configured fallback search engine selected by the user.
0806  *
0807  * kurisearchfilter:
0808  * This is used for filtering KDE webshortcuts. For example "gg:KDE" will be
0809  * converted to a url for searching the work "KDE" using the Google search
0810  * engine.
0811  *
0812  * localdomainfilter:
0813  * This is used for doing a DNS lookup to determine whether the input is a valid
0814  * local address.
0815  *
0816  * fixuphosturifilter:
0817  * This is used to append "www." to the host name of a pre filtered http url
0818  * if the original url cannot be resolved.
0819  *
0820  * \code
0821  * QString text ("kde.org");
0822  * bool filtered = KUriFilter::self()->filterUri(text, QLatin1String("kshorturifilter"));
0823  * \endcode
0824  *
0825  * The above code should result in "kde.org" being filtered into "http://kde.org".
0826  *
0827  * \code
0828  * QStringList list;
0829  * list << QLatin1String("kshorturifilter") << QLatin1String("localdomainfilter");
0830  * bool filtered = KUriFilter::self()->filterUri( text, list );
0831  * \endcode
0832  *
0833  * Additionally if you only want to do search related filtering, you can use the
0834  * search specific function, @ref filterSearchUri, that is available in KDE
0835  * 4.5 and higher. For example, to search for a given input on the web you
0836  * can do the following:
0837  *
0838  * KUriFilterData filterData ("foo");
0839  * bool filtered = KUriFilter::self()->filterSearchUri(filterData, KUriFilterData::NormalTextFilter);
0840  *
0841  * KUriFilter converts all filtering requests to use @ref KUriFilterData
0842  * internally. The use of this bi-directional class allows you to send specific
0843  * instructions to the filter plugins as well as receive detailed information
0844  * about the filtered request from them. See the documentation of KUriFilterData
0845  * class for more examples and details.
0846  *
0847  * All functions in this class are thread safe and reentrant.
0848  *
0849  * @short Filters the given input into a valid url whenever possible.
0850  */
0851 class KIOWIDGETS_EXPORT KUriFilter
0852 {
0853 public:
0854     /**
0855      * This enum describes the types of search plugin filters available.
0856      *
0857      * @li NormalTextFilter      The plugin used to filter normal text, e.g. "some term to search".
0858      * @li WebShortcutFilter     The plugin used to filter web shortcuts, e.g. gg:KDE.
0859      *
0860      * @see SearchFilterTypes
0861      */
0862     enum SearchFilterType {
0863         NormalTextFilter = 0x01,
0864         WebShortcutFilter = 0x02,
0865     };
0866     /**
0867      * Stores a combination of #SearchFilterType values.
0868      */
0869     Q_DECLARE_FLAGS(SearchFilterTypes, SearchFilterType)
0870 
0871     /**
0872      *  Destructor
0873      */
0874     ~KUriFilter();
0875 
0876     /**
0877      * Returns an instance of KUriFilter.
0878      */
0879     static KUriFilter *self();
0880 
0881     /**
0882      * Filters @p data using the specified @p filters.
0883      *
0884      * If no named filters are specified, the default, then all the
0885      * URI filter plugins found will be used.
0886      *
0887      * @param data object that contains the URI to be filtered.
0888      * @param filters specify the list of filters to be used.
0889      *
0890      * @return a boolean indicating whether the URI has been changed
0891      */
0892     bool filterUri(KUriFilterData &data, const QStringList &filters = QStringList());
0893 
0894     /**
0895      * Filters the URI given by the URL.
0896      *
0897      * The given URL is filtered based on the specified list of filters.
0898      * If the list is empty all available filters would be used.
0899      *
0900      * @param uri the URI to filter.
0901      * @param filters specify the list of filters to be used.
0902      *
0903      * @return a boolean indicating whether the URI has been changed
0904      */
0905     bool filterUri(QUrl &uri, const QStringList &filters = QStringList());
0906 
0907     /**
0908      * Filters a string representing a URI.
0909      *
0910      * The given URL is filtered based on the specified list of filters.
0911      * If the list is empty all available filters would be used.
0912      *
0913      * @param uri The URI to filter.
0914      * @param filters specify the list of filters to be used.
0915      *
0916      * @return a boolean indicating whether the URI has been changed
0917      */
0918     bool filterUri(QString &uri, const QStringList &filters = QStringList());
0919 
0920     /**
0921      * Returns the filtered URI.
0922      *
0923      * The given URL is filtered based on the specified list of filters.
0924      * If the list is empty all available filters would be used.
0925      *
0926      * @param uri The URI to filter.
0927      * @param filters specify the list of filters to be used.
0928      *
0929      * @return the filtered URI or null if it cannot be filtered
0930      */
0931     QUrl filteredUri(const QUrl &uri, const QStringList &filters = QStringList());
0932 
0933     /**
0934      * Return a filtered string representation of a URI.
0935      *
0936      * The given URL is filtered based on the specified list of filters.
0937      * If the list is empty all available filters would be used.
0938      *
0939      * @param uri the URI to filter.
0940      * @param filters specify the list of filters to be used.
0941      *
0942      * @return the filtered URI or null if it cannot be filtered
0943      */
0944     QString filteredUri(const QString &uri, const QStringList &filters = QStringList());
0945 
0946 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 6)
0947     /**
0948      * See @ref filterSearchUri(KUriFilterData&, SearchFilterTypes)
0949      *
0950      * @since 4.5
0951      * @deprecated Since 4.6, use filterSearchUri(KUriFilterData&, SearchFilterTypes) instead.
0952      */
0953     KIOWIDGETS_DEPRECATED_VERSION(4, 6, "Use KUriFilter::filterSearchUri(KUriFilterData &, SearchFilterTypes)")
0954     bool filterSearchUri(KUriFilterData &data);
0955 #endif
0956 
0957     /**
0958      * Filter @p data using the criteria specified by @p types.
0959      *
0960      * The search filter type can be individual value of @ref SearchFilterTypes
0961      * or a combination of those types using the bitwise OR operator.
0962      *
0963      * You can also use the flags from @ref KUriFilterData::SearchFilterOption
0964      * to alter the filtering mechanisms of the search filter providers.
0965      *
0966      * @param data object that contains the URI to be filtered.
0967      * @param types the search filters used to filter the request.
0968      * @return true if the specified @p data was successfully filtered.
0969      *
0970      * @see KUriFilterData::setSearchFilteringOptions
0971      * @since 4.6
0972      */
0973     bool filterSearchUri(KUriFilterData &data, SearchFilterTypes types);
0974 
0975     /**
0976      * Return a list of the names of all loaded plugins.
0977      *
0978      * @return a QStringList of plugin names
0979      */
0980     QStringList pluginNames() const;
0981 
0982 protected:
0983     /**
0984      * Constructor.
0985      *
0986      * Creates a KUriFilter object and calls @ref loadPlugins to load all
0987      * available URI filter plugins.
0988      */
0989     KUriFilter();
0990 
0991     /**
0992      * Loads all allowed plugins.
0993      *
0994      * This function only loads URI filter plugins that have not been disabled.
0995      */
0996     void loadPlugins();
0997 
0998 private:
0999     std::unique_ptr<KUriFilterPrivate> const d;
1000     friend class KUriFilterSingleton;
1001 };
1002 
1003 Q_DECLARE_OPERATORS_FOR_FLAGS(KUriFilterData::SearchFilterOptions)
1004 Q_DECLARE_OPERATORS_FOR_FLAGS(KUriFilter::SearchFilterTypes)
1005 
1006 #endif