KIO

kurifilter.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000-2001, 2003, 2010 Dawit Alemayehu <adawit at kde.org>
4 
5  Original author
6  SPDX-FileCopyrightText: 2000 Yves Arrouye <[email protected]>
7 
8  SPDX-License-Identifier: LGPL-2.0-or-later
9 */
10 
11 #ifndef KURIFILTER_H
12 #define KURIFILTER_H
13 
14 #include "kiowidgets_export.h"
15 
16 #include <QHash>
17 #include <QObject>
18 #include <QPair>
19 #include <QStringList>
20 #include <QUrl>
21 
22 #ifdef Q_OS_WIN
23 #undef ERROR
24 #endif
25 
26 class KUriFilterPrivate;
27 class KUriFilterDataPrivate;
28 class KCModule;
29 class QHostInfo;
30 
31 /**
32  * @class KUriFilterSearchProvider kurifilter.h <KUriFilter>
33  *
34  * Class that holds information about a search provider.
35  *
36  * @since 4.6
37  */
38 class KIOWIDGETS_EXPORT KUriFilterSearchProvider
39 {
40 public:
41  /**
42  * Default constructor.
43  */
45 
46  /**
47  * Copy constructor.
48  */
50 
51  /**
52  * Destructor.
53  */
54  virtual ~KUriFilterSearchProvider();
55 
56  /**
57  * Returns the desktop filename of the search provider without any extension.
58  *
59  * For example, if the desktop filename of the search provider was
60  * "foobar.desktop", this function will return "foobar".
61  */
62  QString desktopEntryName() const;
63 
64  /**
65  * Returns the descriptive name of the search provider, e.g. "Google News".
66  *
67  * This name comes from the "Name=" property entry in the desktop file that
68  * contains the search provider's information.
69  */
70  QString name() const;
71 
72  /**
73  * Returns the icon name associated with the search provider when available.
74  */
75  virtual QString iconName() const;
76 
77  /**
78  * Returns all the web shortcut keys associated with this search provider.
79  *
80  * @see defaultKey
81  */
82  QStringList keys() const;
83 
84  /**
85  * Returns the default web shortcut key for this search provider.
86  *
87  * Right now this is the same as doing keys().first(), it might however
88  * change based on what the backend plugins do.
89  *
90  * @see keys
91  */
92  QString defaultKey() const;
93 
94  /**
95  * Assignment operator.
96  */
98 
99 protected:
100  void setDesktopEntryName(const QString &);
101  void setIconName(const QString &);
102  void setKeys(const QStringList &);
103  void setName(const QString &);
104 
105 private:
106  friend class KUriFilterPlugin;
107  class KUriFilterSearchProviderPrivate;
108  KUriFilterSearchProviderPrivate *const d;
109 };
110 
111 /**
112  * @class KUriFilterData kurifilter.h <KUriFilter>
113  *
114  * This class is a basic messaging class used to exchange filtering information
115  * between the filter plugins and the application requesting the filtering
116  * service.
117  *
118  * Use this object if you require a more detailed information about the URI you
119  * want to filter. Any application can create an instance of this class and send
120  * it to KUriFilter to have the plugins fill out all possible information about
121  * the URI.
122  *
123  * On successful filtering you can use @ref uriType() to determine what type
124  * of resource the request was filtered into. See @ref KUriFilter::UriTypes for
125  * details. If an error is encountered, then @ref KUriFilter::Error is returned.
126  * You can use @ref errorMsg to obtain the error information.
127  *
128  * The functions in this class are not reentrant.
129  *
130  * \b Example
131  *
132  * Here is a basic example of how this class is used with @ref KUriFilter:
133  * \code
134  * KUriFilterData filterData (QLatin1String("kde.org"));
135  * bool filtered = KUriFilter::self()->filterUri(filterData);
136  * \endcode
137  *
138  * If you are only interested in getting the list of preferred search providers,
139  * then you can do the following:
140  *
141  * \code
142  * KUriFilterData data;
143  * data.setData("<text-to-search-for>");
144  * data.setSearchFilteringOption(KUriFilterData::RetrievePreferredSearchProvidersOnly);
145  * bool filtered = KUriFilter::self()->filterSearchUri(data, KUriFilter::NormalTextFilter);
146  * \endcode
147  *
148  * @short A class for exchanging filtering information.
149  * @author Dawit Alemayehu <adawit at kde.org>
150  */
151 
152 class KIOWIDGETS_EXPORT KUriFilterData
153 {
154 public:
155  /**
156  * Describes the type of the URI that was filtered.
157  * Here is a brief description of the types:
158  *
159  * @li NetProtocol - Any network protocol: http, ftp, nttp, pop3, etc...
160  * @li LocalFile - A local file whose executable flag is not set
161  * @li LocalDir - A local directory
162  * @li Executable - A local file whose executable flag is set
163  * @li Help - A man or info page
164  * @li Shell - A shell executable (ex: echo "Test..." >> ~/testfile)
165  * @li Blocked - A URI that should be blocked/filtered (ex: ad filtering)
166  * @li Error - An incorrect URI (ex: "~johndoe" when user johndoe
167  * does not exist in that system )
168  * @li Unknown - A URI that is not identified. Default value when
169  * a KUriFilterData is first created.
170  */
171  enum UriTypes { NetProtocol = 0, LocalFile, LocalDir, Executable, Help, Shell, Blocked, Error, Unknown };
172 
173  /**
174  * This enum describes the search filtering options to be used.
175  *
176  * @li SearchFilterOptionNone
177  * No search filter options are set and normal filtering is performed
178  * on the input data.
179  * @li RetrieveSearchProvidersOnly
180  * If set, the list of all available search providers are returned without
181  * any input filtering. This flag only applies when used in conjunction
182  * with the @ref KUriFilter::NormalTextFilter flag.
183  * @li RetrievePreferredSearchProvidersOnly
184  * If set, the list of preferred search providers are returned without
185  * any input filtering. This flag only applies when used in conjunction
186  * with the @ref KUriFilter::NormalTextFilter flag.
187  * @li RetrieveAvailableSearchProvidersOnly
188  * Same as doing RetrievePreferredSearchProvidersOnly | RetrieveSearchProvidersOnly,
189  * where all available search providers are returned if no preferred ones
190  * ones are available. No input filtering will be performed.
191  *
192  * @see setSearchFilteringOptions
193  * @see KUriFilter::filterSearchUri
194  * @see SearchFilterOptions
195  * @since 4.6
196  */
198  SearchFilterOptionNone = 0x0,
199  RetrieveSearchProvidersOnly = 0x01,
200  RetrievePreferredSearchProvidersOnly = 0x02,
201  RetrieveAvailableSearchProvidersOnly = (RetrievePreferredSearchProvidersOnly | RetrieveSearchProvidersOnly),
202  };
203  /**
204  * Stores a combination of #SearchFilterOption values.
205  */
207 
208  /**
209  * Default constructor.
210  *
211  * Creates a UriFilterData object.
212  */
213  KUriFilterData();
214 
215  /**
216  * Creates a KUriFilterData object from the given URL.
217  *
218  * @param url is the URL to be filtered.
219  */
220  explicit KUriFilterData(const QUrl &url);
221 
222  /**
223  * Creates a KUriFilterData object from the given string.
224  *
225  * @param url is the string to be filtered.
226  */
227  explicit KUriFilterData(const QString &url);
228 
229  /**
230  * Copy constructor.
231  *
232  * Creates a KUriFilterData object from another KURIFilterData object.
233  *
234  * @param other the uri filter data to be copied.
235  */
236  KUriFilterData(const KUriFilterData &other);
237 
238  /**
239  * Destructor.
240  */
241  ~KUriFilterData();
242 
243  /**
244  * Returns the filtered or the original URL.
245  *
246  * If one of the plugins successfully filtered the original input, this
247  * function returns it. Otherwise, it will return the input itself.
248  *
249  * @return the filtered or original url.
250  */
251  QUrl uri() const;
252 
253  /**
254  * Returns an error message.
255  *
256  * This functions returns the error message set by the plugin whenever the
257  * uri type is set to KUriFilterData::ERROR. Otherwise, it returns a nullptr
258  * string.
259  *
260  * @return the error message or a nullptr when there is none.
261  */
262  QString errorMsg() const;
263 
264  /**
265  * Returns the URI type.
266  *
267  * This method always returns KUriFilterData::UNKNOWN if the given URL was
268  * not filtered.
269  *
270  * @return the type of the URI
271  */
272  UriTypes uriType() const;
273 
274  /**
275  * Returns the absolute path if one has already been set.
276  *
277  * @return the absolute path, or QString()
278  *
279  * @see hasAbsolutePath()
280  */
281  QString absolutePath() const;
282 
283  /**
284  * Checks whether the supplied data had an absolute path.
285  *
286  * @return true if the supplied data has an absolute path
287  *
288  * @see absolutePath()
289  */
290  bool hasAbsolutePath() const;
291 
292  /**
293  * Returns the command line options and arguments for a local resource
294  * when present.
295  *
296  * @return options and arguments when present, otherwise QString()
297  */
298  QString argsAndOptions() const;
299 
300  /**
301  * Checks whether the current data is a local resource with command line
302  * options and arguments.
303  *
304  * @return true if the current data has command line options and arguments
305  */
306  bool hasArgsAndOptions() const;
307 
308  /**
309  * @return true if the filters should attempt to check whether the
310  * supplied uri is an executable. False otherwise.
311  */
312  bool checkForExecutables() const;
313 
314  /**
315  * The string as typed by the user, before any URL processing is done.
316  */
317  QString typedString() const;
318 
319  /**
320  * Returns the search term portion of the typed string.
321  *
322  * If the @ref typedString was not filtered by a search filter plugin, this
323  * function returns an empty string.
324  *
325  * @see typedString
326  * @since 4.5
327  */
328  QString searchTerm() const;
329 
330  /**
331  * Returns the character that is used to separate the search term from the
332  * keyword.
333  *
334  * If @ref typedString was not filtered by a search filter plugin, this
335  * function returns a null character.
336  *
337  * @see typedString
338  * @since 4.5
339  */
340  QChar searchTermSeparator() const;
341 
342  /**
343  * Returns the name of the search service provider, e.g. Google.
344  *
345  * If @ref typedString was not filtered by a search filter plugin, this
346  * function returns an empty string.
347  *
348  * @see typedString
349  * @since 4.5
350  */
351  QString searchProvider() const;
352 
353  /**
354  * Returns a list of the names of preferred or available search providers.
355  *
356  * This function returns the list of providers marked as preferred whenever
357  * the input data, i.e. @ref typedString, is successfully filtered.
358  *
359  * If no default search provider has been selected prior to a filter request,
360  * this function will return an empty list. To avoid this problem you must
361  * either set an alternate default search provider using @ref setAlternateDefaultSearchProvider
362  * or set one of the @ref SearchFilterOption flags if you are only interested
363  * in getting the list of providers and not filtering the input.
364  *
365  * Additionally, you can also provide alternate search providers in case
366  * there are no preferred ones already selected.
367  *
368  * You can use @ref queryForPreferredServiceProvider to obtain the query
369  * associated with the list of search providers returned by this function.
370  *
371  * @see setAlternateSearchProviders
372  * @see setAlternateDefaultSearchProvider
373  * @see setSearchFilteringOption
374  * @see queryForPreferredServiceProvider
375  * @since 4.5
376  */
377  QStringList preferredSearchProviders() const;
378 
379  /**
380  * Returns information about @p provider.
381  *
382  * You can use this function to obtain the more information about the search
383  * providers returned by @ref preferredSearchProviders.
384  *
385  * @see preferredSearchProviders
386  * @see KUriFilterSearchProvider
387  * @since 4.6
388  */
389  KUriFilterSearchProvider queryForSearchProvider(const QString &provider) const;
390 
391  /**
392  * Returns the web shortcut url for the given preferred search provider.
393  *
394  * You can use this function to obtain the query for the preferred search
395  * providers returned by @ref preferredSearchProviders.
396  *
397  * The query returned by this function is in web shortcut format, i.e.
398  * "gg:foo bar", and must be re-filtered through KUriFilter to obtain a
399  * valid url.
400  *
401  * @see preferredSearchProviders
402  * @since 4.5
403  */
404  QString queryForPreferredSearchProvider(const QString &provider) const;
405 
406  /**
407  * Returns all the query urls for the given search provider.
408  *
409  * Use this function to obtain all the different queries that can be used
410  * for the given provider. For example, if a search engine provider named
411  * "foobar" has web shortcuts named "foobar", "foo" and "bar", then this
412  * function, unlike @ref queryForPreferredSearchProvider, will return a
413  * a query for each and every web shortcut.
414  *
415  * @see queryForPreferredSearchProvider
416  * @since 4.6
417  */
418  QStringList allQueriesForSearchProvider(const QString &provider) const;
419 
420  /**
421  * Returns the icon associated with the given preferred search provider.
422  *
423  * You can use this function to obtain the icon names associated with the
424  * preferred search providers returned by @ref preferredSearchProviders.
425  *
426  * @see preferredSearchProviders
427  * @since 4.5
428  */
429  QString iconNameForPreferredSearchProvider(const QString &provider) const;
430 
431  /**
432  * Returns the list of alternate search providers.
433  *
434  * This function returns an empty list if @ref setAlternateSearchProviders
435  * was not called to set the alternate search providers to be when no
436  * preferred providers have been chosen by the user through the search
437  * configuration module.
438  *
439  * @see setAlternatteSearchProviders
440  * @see preferredSearchProviders
441  * @since 4.5
442  */
443  QStringList alternateSearchProviders() const;
444 
445  /**
446  * Returns the search provider to use when a default provider is not available.
447  *
448  * This function returns an empty string if @ref setAlternateDefaultSearchProvider
449  * was not called to set the default search provider to be used when none has been
450  * chosen by the user through the search configuration module.
451  *
452  * @see setAlternateDefaultSearchProvider
453  * @since 4.5
454  */
455  QString alternateDefaultSearchProvider() const;
456 
457  /**
458  * Returns the default protocol to use when filtering potentially valid url inputs.
459  *
460  * By default this function will return an empty string.
461  *
462  * @see setDefaultUrlScheme
463  * @since 4.6
464  */
465  QString defaultUrlScheme() const;
466 
467  /**
468  * Returns the specified search filter options.
469  *
470  * By default this function returns @ref SearchFilterOptionNone.
471  *
472  * @see setSearchFilteringOptions
473  * @since 4.6
474  */
475  SearchFilterOptions searchFilteringOptions() const;
476 
477  /**
478  * The name of the icon that matches the current filtered URL.
479  *
480  * This function returns a null string by default and when no icon is found
481  * for the filtered URL.
482  */
483  QString iconName();
484 
485  /**
486  * Check whether the provided uri is executable or not.
487  *
488  * Setting this to false ensures that typing the name of an executable does
489  * not start that application. This is useful in the location bar of a
490  * browser. The default value is true.
491  */
492  void setCheckForExecutables(bool check);
493 
494  /**
495  * Same as above except the argument is a URL.
496  *
497  * Use this function to set the string to be filtered when you construct an
498  * empty filter object.
499  *
500  * @param url the URL to be filtered.
501  */
502  void setData(const QUrl &url);
503 
504  /**
505  * Sets the URL to be filtered.
506  *
507  * Use this function to set the string to be
508  * filtered when you construct an empty filter
509  * object.
510  *
511  * @param url the string to be filtered.
512  */
513  void setData(const QString &url);
514 
515  /**
516  * Sets the absolute path to be used whenever the supplied data is a
517  * relative local URL.
518  *
519  * NOTE: This function should only be used for local resources, i.e. the
520  * "file:/" protocol. It is useful for specifying the absolute path in
521  * cases where the actual URL might be relative. If deriving the path from
522  * a QUrl, make sure you set the argument for this function to the result
523  * of calling path () instead of url ().
524  *
525  * @param abs_path the absolute path to the local resource.
526  *
527  * @return true if absolute path is successfully set. Otherwise, false.
528  */
529  bool setAbsolutePath(const QString &abs_path);
530 
531  /**
532  * Sets a list of search providers to use in case no preferred search
533  * providers are available.
534  *
535  * The list of preferred search providers set using this function will only
536  * be used if the default and favorite search providers have not yet been
537  * selected by the user. Otherwise, the providers specified through this
538  * function will be ignored.
539  *
540  * @see alternateSearchProviders
541  * @see preferredSearchProviders
542  * @since 4.5
543  */
544  void setAlternateSearchProviders(const QStringList &providers);
545 
546  /**
547  * Sets the search provider to use in case no default provider is available.
548  *
549  * The default search provider set using this function will only be used if
550  * the default and favorite search providers have not yet been selected by
551  * the user. Otherwise, the default provider specified by through function
552  * will be ignored.
553  *
554  * @see alternateDefaultSearchProvider
555  * @see preferredSearchProviders
556  * @since 4.5
557  */
558  void setAlternateDefaultSearchProvider(const QString &provider);
559 
560  /**
561  * Sets the default scheme used when filtering potentially valid url inputs.
562  *
563  * Use this function to change the default protocol used when filtering
564  * potentially valid url inputs. The default protocol is http.
565  *
566  * If the scheme is specified without a separator, then "://" will be used
567  * as the separator by default. For example, if the default url scheme was
568  * simply set to "ftp", then a potentially valid url input such as "kde.org"
569  * will be filtered to "ftp://kde.org".
570  *
571  * @see defaultUrlScheme
572  * @since 4.6
573  */
574  void setDefaultUrlScheme(const QString &);
575 
576  /**
577  * Sets the options used by search filter plugins to filter requests.
578  *
579  * The default search filter option is @ref SearchFilterOptionNone. See
580  * @ref SearchFilterOption for the description of the other flags.
581  *
582  * It is important to note that the options set through this function can
583  * prevent any filtering from being performed by search filter plugins.
584  * As such, @ref uriTypes can return KUriFilterData::Unknown and @ref uri
585  * can return an invalid url even though the filtering request returned
586  * a successful response.
587  *
588  * @see searchFilteringOptions
589  * @since 4.6
590  */
591  void setSearchFilteringOptions(SearchFilterOptions options);
592 
593  /**
594  * Overloaded assignment operator.
595  *
596  * This function allows you to easily assign a QUrl
597  * to a KUriFilterData object.
598  *
599  * @return an instance of a KUriFilterData object.
600  */
601  KUriFilterData &operator=(const QUrl &url);
602 
603  /**
604  * Overloaded assignment operator.
605  *
606  * This function allows you to easily assign a QString to a KUriFilterData
607  * object.
608  *
609  * @return an instance of a KUriFilterData object.
610  */
611  KUriFilterData &operator=(const QString &url);
612 
613 private:
614  friend class KUriFilterPlugin;
615  KUriFilterDataPrivate *const d;
616 };
617 
618 /**
619  * @class KUriFilterPlugin kurifilter.h <KUriFilter>
620  *
621  * Base class for URI filter plugins.
622  *
623  * This class applies a single filter to a URI. All plugins designed to provide
624  * URI filtering service should inherit from this abstract class and provide a
625  * concrete implementation.
626  *
627  * All inheriting classes need to implement the pure virtual function
628  * @ref filterUri.
629  *
630  * @short Abstract class for URI filter plugins.
631  */
632 class KIOWIDGETS_EXPORT KUriFilterPlugin : public QObject
633 {
634  Q_OBJECT
635 
636 public:
637 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 6)
638  /**
639  * List for holding the following search provider information:
640  * ([search provider name], [search query, search query icon name])
641  *
642  * @since 4.5
643  * @deprecated Since 4.6, use @ref KUriFilterSearchProvider instead. See @ref setSearchProviders;
644  */
645  KIOWIDGETS_DEPRECATED_VERSION(4, 6, "Use KUriFilterSearchProvider")
646  typedef QHash<QString, QPair<QString, QString>> ProviderInfoList;
647 #endif
648 
649  /**
650  * Constructs a filter plugin with a given name
651  *
652  * @param parent the parent object, or @c nullptr for no parent
653  * @param name the name of the plugin, mandatory
654  */
655  explicit KUriFilterPlugin(const QString &name, QObject *parent = nullptr);
656 
657  // KF6 TODO ~KUriFilterPlugin();
658 
659  /**
660  * Filters a URI.
661  *
662  * @param data the URI data to be filtered.
663  * @return A boolean indicating whether the URI has been changed.
664  */
665  virtual bool filterUri(KUriFilterData &data) const = 0;
666 
667  /**
668  * Creates a configuration module for the filter.
669  *
670  * It is the responsibility of the caller to delete the module once it is
671  * not needed anymore.
672  *
673  * @return A configuration module, or @c nullptr if the filter isn't configurable.
674  */
675  virtual KCModule *configModule(QWidget *, const char *) const;
676 
677  /**
678  * Returns the name of the configuration module for the filter.
679  *
680  * @return the name of a configuration module or QString() if none.
681  */
682  virtual QString configName() const;
683 
684 protected:
685  /**
686  * Sets the URL in @p data to @p uri.
687  */
688  void setFilteredUri(KUriFilterData &data, const QUrl &uri) const;
689 
690  /**
691  * Sets the error message in @p data to @p errormsg.
692  */
693  void setErrorMsg(KUriFilterData &data, const QString &errmsg) const;
694 
695  /**
696  * Sets the URI type in @p data to @p type.
697  */
698  void setUriType(KUriFilterData &data, KUriFilterData::UriTypes type) const;
699 
700  /**
701  * Sets the arguments and options string in @p data to @p args if any were
702  * found during filtering.
703  */
704  void setArguments(KUriFilterData &data, const QString &args) const;
705 
706  /**
707  * Sets the name of the search provider, the search term and keyword/term
708  * separator in @p data.
709  *
710  * @since 4.5
711  */
712  void setSearchProvider(KUriFilterData &data, const QString &provider, const QString &term, const QChar &separator) const;
713 
714  /**
715  * Sets the information about the search @p providers in @p data.
716  *
717  * @since 4.6
718  */
719  void setSearchProviders(KUriFilterData &data, const QList<KUriFilterSearchProvider *> &providers) const;
720 
721  /**
722  * Returns the icon name for the given @p url and URI @p type.
723  *
724  * @since 4.5
725  */
726  QString iconNameFor(const QUrl &url, KUriFilterData::UriTypes type) const;
727 
728  /**
729  * Performs a DNS lookup for @p hostname and returns the result.
730  *
731  * This function uses the KIO/KHTML DNS cache to speed up the
732  * lookup. It also avoids doing a reverse lookup if the given
733  * host name is already an ip address.
734  *
735  * \note All uri filter plugins that need to perform a hostname
736  * lookup should use this function.
737  *
738  * @param hostname the hostname to lookup.
739  * @param timeout the amount of time in msecs to wait for the lookup.
740  * @return the result of the host name lookup.
741  *
742  * @since 4.7
743  */
744  QHostInfo resolveName(const QString &hostname, unsigned long timeout) const;
745 
746 private:
747  class KUriFilterPluginPrivate *const d;
748 };
749 
750 /**
751  * @class KUriFilter kurifilter.h <KUriFilter>
752  *
753  * KUriFilter applies a number of filters to a URI and returns a filtered version if any
754  * filter matches.
755  * A simple example is "kde.org" to "http://www.kde.org", which is commonplace in web browsers.
756  *
757  * The filters are implemented as plugins in @ref KUriFilterPlugin subclasses.
758  *
759  * KUriFilter is a singleton object: obtain the instance by calling
760  * @p KUriFilter::self() and use the public member functions to
761  * perform the filtering.
762  *
763  * \b Example
764  *
765  * To simply filter a given string:
766  *
767  * \code
768  * QString url("kde.org");
769  * bool filtered = KUriFilter::self()->filteredUri( url );
770  * \endcode
771  *
772  * You can alternatively use a QUrl:
773  *
774  * \code
775  * QUrl url("kde.org");
776  * bool filtered = KUriFilter::self()->filterUri( url );
777  * \endcode
778  *
779  * If you have a constant string or a constant URL, simply invoke the
780  * corresponding function to obtain the filtered string or URL instead
781  * of a boolean flag:
782  *
783  * \code
784  * QString filteredText = KUriFilter::self()->filteredUri( "kde.org" );
785  * \endcode
786  *
787  * All of the above examples should result in "kde.org" being filtered into
788  * "http://kde.org".
789  *
790  * You can also restrict the filters to be used by supplying the name of the
791  * filters you want to use. By default all available filters are used.
792  *
793  * To use specific filters, add the names of the filters you want to use to a
794  * QStringList and invoke the appropriate filtering function.
795  *
796  * The examples below show the use of specific filters. KDE ships with the
797  * following filter plugins by default:
798  *
799  * kshorturifilter:
800  * This is used for filtering potentially valid url inputs such as "kde.org"
801  * Additionally it filters shell variables and shortcuts such as $HOME and
802  * ~ as well as man and info page shortcuts, # and ## respectively.
803  *
804  * kuriikwsfilter:
805  * This is used for filtering normal input text into a web search url using the
806  * configured fallback search engine selected by the user.
807  *
808  * kurisearchfilter:
809  * This is used for filtering KDE webshortcuts. For example "gg:KDE" will be
810  * converted to a url for searching the work "KDE" using the Google search
811  * engine.
812  *
813  * localdomainfilter:
814  * This is used for doing a DNS lookup to determine whether the input is a valid
815  * local address.
816  *
817  * fixuphosturifilter:
818  * This is used to append "www." to the host name of a pre filtered http url
819  * if the original url cannot be resolved.
820  *
821  * \code
822  * QString text ("kde.org");
823  * bool filtered = KUriFilter::self()->filterUri(text, QLatin1String("kshorturifilter"));
824  * \endcode
825  *
826  * The above code should result in "kde.org" being filtered into "http://kde.org".
827  *
828  * \code
829  * QStringList list;
830  * list << QLatin1String("kshorturifilter") << QLatin1String("localdomainfilter");
831  * bool filtered = KUriFilter::self()->filterUri( text, list );
832  * \endcode
833  *
834  * Additionally if you only want to do search related filtering, you can use the
835  * search specific function, @ref filterSearchUri, that is available in KDE
836  * 4.5 and higher. For example, to search for a given input on the web you
837  * can do the following:
838  *
839  * KUriFilterData filterData ("foo");
840  * bool filtered = KUriFilter::self()->filterSearchUri(filterData, KUriFilterData::NormalTextFilter);
841  *
842  * KUriFilter converts all filtering requests to use @ref KUriFilterData
843  * internally. The use of this bi-directional class allows you to send specific
844  * instructions to the filter plugins as well as receive detailed information
845  * about the filtered request from them. See the documentation of KUriFilterData
846  * class for more examples and details.
847  *
848  * All functions in this class are thread safe and reentrant.
849  *
850  * @short Filters the given input into a valid url whenever possible.
851  */
852 class KIOWIDGETS_EXPORT KUriFilter
853 {
854 public:
855  /**
856  * This enum describes the types of search plugin filters available.
857  *
858  * @li NormalTextFilter The plugin used to filter normal text, e.g. "some term to search".
859  * @li WebShortcutFilter The plugin used to filter web shortcuts, e.g. gg:KDE.
860  *
861  * @see SearchFilterTypes
862  */
864  NormalTextFilter = 0x01,
865  WebShortcutFilter = 0x02,
866  };
867  /**
868  * Stores a combination of #SearchFilterType values.
869  */
871 
872  /**
873  * Destructor
874  */
875  ~KUriFilter();
876 
877  /**
878  * Returns an instance of KUriFilter.
879  */
880  static KUriFilter *self();
881 
882  /**
883  * Filters @p data using the specified @p filters.
884  *
885  * If no named filters are specified, the default, then all the
886  * URI filter plugins found will be used.
887  *
888  * @param data object that contains the URI to be filtered.
889  * @param filters specify the list of filters to be used.
890  *
891  * @return a boolean indicating whether the URI has been changed
892  */
893  bool filterUri(KUriFilterData &data, const QStringList &filters = QStringList());
894 
895  /**
896  * Filters the URI given by the URL.
897  *
898  * The given URL is filtered based on the specified list of filters.
899  * If the list is empty all available filters would be used.
900  *
901  * @param uri the URI to filter.
902  * @param filters specify the list of filters to be used.
903  *
904  * @return a boolean indicating whether the URI has been changed
905  */
906  bool filterUri(QUrl &uri, const QStringList &filters = QStringList());
907 
908  /**
909  * Filters a string representing a URI.
910  *
911  * The given URL is filtered based on the specified list of filters.
912  * If the list is empty all available filters would be used.
913  *
914  * @param uri The URI to filter.
915  * @param filters specify the list of filters to be used.
916  *
917  * @return a boolean indicating whether the URI has been changed
918  */
919  bool filterUri(QString &uri, const QStringList &filters = QStringList());
920 
921  /**
922  * Returns the filtered URI.
923  *
924  * The given URL is filtered based on the specified list of filters.
925  * If the list is empty all available filters would be used.
926  *
927  * @param uri The URI to filter.
928  * @param filters specify the list of filters to be used.
929  *
930  * @return the filtered URI or null if it cannot be filtered
931  */
932  QUrl filteredUri(const QUrl &uri, const QStringList &filters = QStringList());
933 
934  /**
935  * Return a filtered string representation of a URI.
936  *
937  * The given URL is filtered based on the specified list of filters.
938  * If the list is empty all available filters would be used.
939  *
940  * @param uri the URI to filter.
941  * @param filters specify the list of filters to be used.
942  *
943  * @return the filtered URI or null if it cannot be filtered
944  */
945  QString filteredUri(const QString &uri, const QStringList &filters = QStringList());
946 
947 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 6)
948  /**
949  * See @ref filterSearchUri(KUriFilterData&, SearchFilterTypes)
950  *
951  * @since 4.5
952  * @deprecated Since 4.6, use filterSearchUri(KUriFilterData&, SearchFilterTypes) instead.
953  */
954  KIOWIDGETS_DEPRECATED_VERSION(4, 6, "Use KUriFilter::filterSearchUri(KUriFilterData &, SearchFilterTypes)")
955  bool filterSearchUri(KUriFilterData &data);
956 #endif
957 
958  /**
959  * Filter @p data using the criteria specified by @p types.
960  *
961  * The search filter type can be individual value of @ref SearchFilterTypes
962  * or a combination of those types using the bitwise OR operator.
963  *
964  * You can also use the flags from @ref KUriFilterData::SearchFilterOption
965  * to alter the filtering mechanisms of the search filter providers.
966  *
967  * @param data object that contains the URI to be filtered.
968  * @param types the search filters used to filter the request.
969  * @return true if the specified @p data was successfully filtered.
970  *
971  * @see KUriFilterData::setSearchFilteringOptions
972  * @since 4.6
973  */
974  bool filterSearchUri(KUriFilterData &data, SearchFilterTypes types);
975 
976  /**
977  * Return a list of the names of all loaded plugins.
978  *
979  * @return a QStringList of plugin names
980  */
981  QStringList pluginNames() const;
982 
983 protected:
984  /**
985  * Constructor.
986  *
987  * Creates a KUriFilter object and calls @ref loadPlugins to load all
988  * available URI filter plugins.
989  */
990  KUriFilter();
991 
992  /**
993  * Loads all allowed plugins.
994  *
995  * This function only loads URI filter plugins that have not been disabled.
996  */
997  void loadPlugins();
998 
999 private:
1000  KUriFilterPrivate *const d;
1001  friend class KUriFilterSingleton;
1002 };
1003 
1004 Q_DECLARE_OPERATORS_FOR_FLAGS(KUriFilterData::SearchFilterOptions)
1005 Q_DECLARE_OPERATORS_FOR_FLAGS(KUriFilter::SearchFilterTypes)
1006 
1007 #endif
Base class for URI filter plugins.
Definition: kurifilter.h:632
SearchFilterOption
This enum describes the search filtering options to be used.
Definition: kurifilter.h:197
Class that holds information about a search provider.
Definition: kurifilter.h:38
UriTypes
Describes the type of the URI that was filtered.
Definition: kurifilter.h:171
KUriFilter applies a number of filters to a URI and returns a filtered version if any filter matches...
Definition: kurifilter.h:852
This class is a basic messaging class used to exchange filtering information between the filter plugi...
Definition: kurifilter.h:152
SearchFilterType
This enum describes the types of search plugin filters available.
Definition: kurifilter.h:863
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Mar 2 2021 23:59:04 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.