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 <yves@realnames.com> |
7 | |
8 | SPDX-License-Identifier: LGPL-2.0-or-later |
9 | */ |
10 | |
11 | #ifndef KURIFILTER_H |
12 | #define KURIFILTER_H |
13 | |
14 | #include "kiogui_export.h" |
15 | |
16 | #include <QHash> |
17 | #include <QObject> |
18 | #include <QPair> |
19 | #include <QStringList> |
20 | #include <QUrl> |
21 | |
22 | #include <memory> |
23 | |
24 | #ifdef Q_OS_WIN |
25 | #undef ERROR |
26 | #endif |
27 | |
28 | class KUriFilterPrivate; |
29 | class KUriFilterDataPrivate; |
30 | class QHostInfo; |
31 | |
32 | /*! |
33 | * \class KUriFilterSearchProvider |
34 | * \inheaderfile KUriFilter |
35 | * \inmodule KIOGui |
36 | * |
37 | * \brief Class that holds information about a search provider. |
38 | * |
39 | */ |
40 | class KIOGUI_EXPORT KUriFilterSearchProvider |
41 | { |
42 | public: |
43 | /*! |
44 | * Default constructor. |
45 | */ |
46 | KUriFilterSearchProvider(); |
47 | |
48 | /*! |
49 | * Copy constructor. |
50 | */ |
51 | KUriFilterSearchProvider(const KUriFilterSearchProvider &); |
52 | |
53 | virtual ~KUriFilterSearchProvider(); |
54 | |
55 | /*! |
56 | * Returns the desktop filename of the search provider without any extension. |
57 | * |
58 | * For example, if the desktop filename of the search provider was |
59 | * "foobar.desktop", this function will return "foobar". |
60 | */ |
61 | QString desktopEntryName() const; |
62 | |
63 | /*! |
64 | * Returns the descriptive name of the search provider, e.g.\ "Google News". |
65 | * |
66 | * This name comes from the "Name=" property entry in the desktop file that |
67 | * contains the search provider's information. |
68 | */ |
69 | QString name() const; |
70 | |
71 | /*! |
72 | * Returns the icon name associated with the search provider when available. |
73 | */ |
74 | virtual QString iconName() const; |
75 | |
76 | /*! |
77 | * Returns all the web shortcut keys associated with this search provider. |
78 | * |
79 | * \sa defaultKey |
80 | */ |
81 | QStringList keys() const; |
82 | |
83 | /*! |
84 | * Returns the default web shortcut key for this search provider. |
85 | * |
86 | * Right now this is the same as doing keys().first(), it might however |
87 | * change based on what the backend plugins do. |
88 | * |
89 | * \sa keys |
90 | */ |
91 | QString defaultKey() const; |
92 | |
93 | KUriFilterSearchProvider &operator=(const KUriFilterSearchProvider &); |
94 | |
95 | protected: |
96 | /*! |
97 | * |
98 | */ |
99 | void setDesktopEntryName(const QString &); |
100 | |
101 | /*! |
102 | * |
103 | */ |
104 | void setIconName(const QString &); |
105 | |
106 | /*! |
107 | * |
108 | */ |
109 | void setKeys(const QStringList &); |
110 | |
111 | /*! |
112 | * |
113 | */ |
114 | void setName(const QString &); |
115 | |
116 | private: |
117 | friend class KUriFilterPlugin; |
118 | class KUriFilterSearchProviderPrivate; |
119 | std::unique_ptr<KUriFilterSearchProviderPrivate> const d; |
120 | }; |
121 | |
122 | /*! |
123 | * \class KUriFilterData |
124 | * \inheaderfile KUriFilter |
125 | * \inmodule KIOGui |
126 | * |
127 | * \brief A class for exchanging filtering information. |
128 | * |
129 | * This class is a basic messaging class used to exchange filtering information |
130 | * between the filter plugins and the application requesting the filtering |
131 | * service. |
132 | * |
133 | * Use this object if you require a more detailed information about the URI you |
134 | * want to filter. Any application can create an instance of this class and send |
135 | * it to KUriFilter to have the plugins fill out all possible information about |
136 | * the URI. |
137 | * |
138 | * On successful filtering you can use uriType() to determine what type |
139 | * of resource the request was filtered into. See KUriFilter::UriTypes for |
140 | * details. If an error is encountered, then KUriFilter::Error is returned. |
141 | * You can use errorMsg to obtain the error information. |
142 | * |
143 | * The functions in this class are not reentrant. |
144 | * |
145 | * Example: |
146 | * |
147 | * Here is a basic example of how this class is used with KUriFilter: |
148 | * \code |
149 | * KUriFilterData filterData (QLatin1String("kde.org")); |
150 | * bool filtered = KUriFilter::self()->filterUri(filterData); |
151 | * \endcode |
152 | * |
153 | * If you are only interested in getting the list of preferred search providers, |
154 | * then you can do the following: |
155 | * |
156 | * \code |
157 | * KUriFilterData data; |
158 | * data.setData("<text-to-search-for>"); |
159 | * data.setSearchFilteringOptions(KUriFilterData::RetrievePreferredSearchProvidersOnly); |
160 | * bool filtered = KUriFilter::self()->filterSearchUri(data, KUriFilter::NormalTextFilter); |
161 | * \endcode |
162 | */ |
163 | |
164 | class KIOGUI_EXPORT KUriFilterData |
165 | { |
166 | public: |
167 | /*! |
168 | * Describes the type of the URI that was filtered. |
169 | * |
170 | * \value NetProtocol Any network protocol: http, ftp, nttp, pop3, etc... |
171 | * \value LocalFile A local file whose executable flag is not set |
172 | * \value LocalDir A local directory |
173 | * \value Executable A local file whose executable flag is set |
174 | * \value Help A man or info page |
175 | * \value Shell A shell executable (ex: echo "Test..." >> ~/testfile) |
176 | * \value Blocked A URI that should be blocked/filtered (ex: ad filtering) |
177 | * \value Error An incorrect URI (ex: "~johndoe" when user johndoe does not exist in that system) |
178 | * \value Unknown A URI that is not identified. Default value when a KUriFilterData is first created. |
179 | */ |
180 | enum UriTypes { |
181 | NetProtocol = 0, |
182 | LocalFile, |
183 | LocalDir, |
184 | Executable, |
185 | Help, |
186 | Shell, |
187 | Blocked, |
188 | Error, |
189 | Unknown, |
190 | }; |
191 | |
192 | /*! |
193 | * This enum describes the search filtering options to be used. |
194 | * |
195 | * \value SearchFilterOptionNone No search filter options are set and normal filtering is performed on the input data. |
196 | * \value RetrieveSearchProvidersOnly If set, the list of all available search providers are returned without any input filtering. This flag only applies |
197 | * when used in conjunction with the KUriFilter::NormalTextFilter flag. |
198 | * \value RetrievePreferredSearchProvidersOnly If set, the list of preferred search providers are returned without any input filtering. This flag only |
199 | * applies when used in conjunction with the KUriFilter::NormalTextFilter flag. |
200 | * \value RetrieveAvailableSearchProvidersOnly Same as doing RetrievePreferredSearchProvidersOnly | RetrieveSearchProvidersOnly, where all available search |
201 | * providers are returned if no preferred ones are available. No input filtering will be performed. |
202 | * |
203 | * \sa setSearchFilteringOptions |
204 | * \sa KUriFilter::filterSearchUri |
205 | */ |
206 | enum SearchFilterOption { |
207 | SearchFilterOptionNone = 0x0, |
208 | RetrieveSearchProvidersOnly = 0x01, |
209 | RetrievePreferredSearchProvidersOnly = 0x02, |
210 | RetrieveAvailableSearchProvidersOnly = (RetrievePreferredSearchProvidersOnly | RetrieveSearchProvidersOnly), |
211 | }; |
212 | Q_DECLARE_FLAGS(SearchFilterOptions, SearchFilterOption) |
213 | |
214 | /*! |
215 | * Default constructor. |
216 | * |
217 | * Creates a UriFilterData object. |
218 | */ |
219 | KUriFilterData(); |
220 | |
221 | /*! |
222 | * Creates a KUriFilterData object from the given URL. |
223 | * |
224 | * \a url is the URL to be filtered. |
225 | */ |
226 | explicit KUriFilterData(const QUrl &url); |
227 | |
228 | /*! |
229 | * Creates a KUriFilterData object from the given string. |
230 | * |
231 | * \a url is the string to be filtered. |
232 | */ |
233 | explicit KUriFilterData(const QString &url); |
234 | |
235 | /*! |
236 | * Copy constructor. |
237 | * |
238 | * Creates a KUriFilterData object from another KURIFilterData object. |
239 | * |
240 | * \a other the uri filter data to be copied. |
241 | */ |
242 | KUriFilterData(const KUriFilterData &other); |
243 | |
244 | ~KUriFilterData(); |
245 | |
246 | /*! |
247 | * Returns the filtered or the original URL. |
248 | * |
249 | * If one of the plugins successfully filtered the original input, this |
250 | * function returns it. Otherwise, it will return the input itself. |
251 | * |
252 | * Returns the filtered or original url. |
253 | */ |
254 | QUrl uri() const; |
255 | |
256 | /*! |
257 | * Returns an error message. |
258 | * |
259 | * This functions returns the error message set by the plugin whenever the |
260 | * uri type is set to KUriFilterData::ERROR. Otherwise, it returns a nullptr |
261 | * string. |
262 | * |
263 | * Returns the error message or a nullptr when there is none. |
264 | */ |
265 | QString errorMsg() const; |
266 | |
267 | /*! |
268 | * Returns the URI type. |
269 | * |
270 | * This method always returns KUriFilterData::UNKNOWN if the given URL was |
271 | * not filtered. |
272 | * |
273 | * Returns the type of the URI |
274 | */ |
275 | UriTypes uriType() const; |
276 | |
277 | /*! |
278 | * Returns the absolute path if one has already been set. |
279 | * |
280 | * Returns the absolute path, or QString() |
281 | * |
282 | * \sa hasAbsolutePath() |
283 | */ |
284 | QString absolutePath() const; |
285 | |
286 | /*! |
287 | * Checks whether the supplied data had an absolute path. |
288 | * |
289 | * Returns true if the supplied data has an absolute path |
290 | * |
291 | * \sa absolutePath() |
292 | */ |
293 | bool hasAbsolutePath() const; |
294 | |
295 | /*! |
296 | * Returns the command line options and arguments for a local resource |
297 | * when present. |
298 | * |
299 | * Returns options and arguments when present, otherwise QString() |
300 | */ |
301 | QString argsAndOptions() const; |
302 | |
303 | /*! |
304 | * Checks whether the current data is a local resource with command line |
305 | * options and arguments. |
306 | * |
307 | * Returns true if the current data has command line options and arguments |
308 | */ |
309 | bool hasArgsAndOptions() const; |
310 | |
311 | /*! |
312 | * Returns true if the filters should attempt to check whether the |
313 | * supplied uri is an executable. False otherwise. |
314 | */ |
315 | bool checkForExecutables() const; |
316 | |
317 | /*! |
318 | * The string as typed by the user, before any URL processing is done. |
319 | */ |
320 | QString typedString() const; |
321 | |
322 | /*! |
323 | * Returns the search term portion of the typed string. |
324 | * |
325 | * If the typedString was not filtered by a search filter plugin, this |
326 | * function returns an empty string. |
327 | * |
328 | * \sa typedString |
329 | */ |
330 | QString searchTerm() const; |
331 | |
332 | /*! |
333 | * Returns the character that is used to separate the search term from the |
334 | * keyword. |
335 | * |
336 | * If typedString was not filtered by a search filter plugin, this |
337 | * function returns a null character. |
338 | * |
339 | * \sa typedString |
340 | */ |
341 | QChar searchTermSeparator() const; |
342 | |
343 | /*! |
344 | * Returns the name of the search service provider, e.g.\ Google. |
345 | * |
346 | * If typedString was not filtered by a search filter plugin, this |
347 | * function returns an empty string. |
348 | * |
349 | * \sa typedString |
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. 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 setAlternateDefaultSearchProvider |
362 | * or set one of the 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 queryForPreferredServiceProvider to obtain the query |
369 | * associated with the list of search providers returned by this function. |
370 | * |
371 | * \sa setAlternateSearchProviders() |
372 | * \sa setAlternateDefaultSearchProvider() |
373 | * \sa setSearchFilteringOptions() |
374 | * \sa queryForPreferredSearchProvider() |
375 | */ |
376 | QStringList preferredSearchProviders() const; |
377 | |
378 | /*! |
379 | * Returns information about \a provider. |
380 | * |
381 | * You can use this function to obtain the more information about the search |
382 | * providers returned by preferredSearchProviders. |
383 | * |
384 | * \sa preferredSearchProviders() |
385 | */ |
386 | KUriFilterSearchProvider queryForSearchProvider(const QString &provider) const; |
387 | |
388 | /*! |
389 | * Returns the web shortcut url for the given preferred search provider. |
390 | * |
391 | * You can use this function to obtain the query for the preferred search |
392 | * providers returned by preferredSearchProviders. |
393 | * |
394 | * The query returned by this function is in web shortcut format, i.e. |
395 | * "gg:foo bar", and must be re-filtered through KUriFilter to obtain a |
396 | * valid url. |
397 | * |
398 | * \sa preferredSearchProviders |
399 | */ |
400 | QString queryForPreferredSearchProvider(const QString &provider) const; |
401 | |
402 | /*! |
403 | * Returns all the query urls for the given search provider. |
404 | * |
405 | * Use this function to obtain all the different queries that can be used |
406 | * for the given provider. For example, if a search engine provider named |
407 | * "foobar" has web shortcuts named "foobar", "foo" and "bar", then this |
408 | * function, unlike queryForPreferredSearchProvider, will return a |
409 | * a query for each and every web shortcut. |
410 | * |
411 | * \sa queryForPreferredSearchProvider |
412 | */ |
413 | QStringList allQueriesForSearchProvider(const QString &provider) const; |
414 | |
415 | /*! |
416 | * Returns the icon associated with the given preferred search provider. |
417 | * |
418 | * You can use this function to obtain the icon names associated with the |
419 | * preferred search providers returned by preferredSearchProviders. |
420 | * |
421 | * \sa preferredSearchProviders |
422 | */ |
423 | QString iconNameForPreferredSearchProvider(const QString &provider) const; |
424 | |
425 | /*! |
426 | * Returns the list of alternate search providers. |
427 | * |
428 | * This function returns an empty list if setAlternateSearchProviders |
429 | * was not called to set the alternate search providers to be when no |
430 | * preferred providers have been chosen by the user through the search |
431 | * configuration module. |
432 | * |
433 | * \sa setAlternateSearchProviders |
434 | * \sa preferredSearchProviders |
435 | */ |
436 | QStringList alternateSearchProviders() const; |
437 | |
438 | /*! |
439 | * Returns the search provider to use when a default provider is not available. |
440 | * |
441 | * This function returns an empty string if setAlternateDefaultSearchProvider |
442 | * was not called to set the default search provider to be used when none has been |
443 | * chosen by the user through the search configuration module. |
444 | * |
445 | * \sa setAlternateDefaultSearchProvider |
446 | */ |
447 | QString alternateDefaultSearchProvider() const; |
448 | |
449 | /*! |
450 | * Returns the default protocol to use when filtering potentially valid url inputs. |
451 | * |
452 | * By default this function will return an empty string. |
453 | * |
454 | * \sa setDefaultUrlScheme |
455 | */ |
456 | QString defaultUrlScheme() const; |
457 | |
458 | /*! |
459 | * Returns the specified search filter options. |
460 | * |
461 | * By default this function returns SearchFilterOptionNone. |
462 | * |
463 | * \sa setSearchFilteringOptions |
464 | */ |
465 | SearchFilterOptions searchFilteringOptions() const; |
466 | |
467 | /*! |
468 | * The name of the icon that matches the current filtered URL. |
469 | * |
470 | * This function returns a null string by default and when no icon is found |
471 | * for the filtered URL. |
472 | */ |
473 | QString iconName(); |
474 | |
475 | /*! |
476 | * Check whether the provided uri is executable or not. |
477 | * |
478 | * Setting this to false ensures that typing the name of an executable does |
479 | * not start that application. This is useful in the location bar of a |
480 | * browser. The default value is true. |
481 | */ |
482 | void setCheckForExecutables(bool check); |
483 | |
484 | /*! |
485 | * Same as above except the argument is a URL. |
486 | * |
487 | * Use this function to set the string to be filtered when you construct an |
488 | * empty filter object. |
489 | * |
490 | * \a url the URL to be filtered. |
491 | */ |
492 | void setData(const QUrl &url); |
493 | |
494 | /*! |
495 | * Sets the URL to be filtered. |
496 | * |
497 | * Use this function to set the string to be |
498 | * filtered when you construct an empty filter |
499 | * object. |
500 | * |
501 | * \a url the string to be filtered. |
502 | */ |
503 | void setData(const QString &url); |
504 | |
505 | /*! |
506 | * Sets the absolute path to be used whenever the supplied data is a |
507 | * relative local URL. |
508 | * |
509 | * \note This function should only be used for local resources, i.e. the |
510 | * "file:/" protocol. It is useful for specifying the absolute path in |
511 | * cases where the actual URL might be relative. If deriving the path from |
512 | * a QUrl, make sure you set the argument for this function to the result |
513 | * of calling path () instead of url (). |
514 | * |
515 | * \a abs_path the absolute path to the local resource. |
516 | * |
517 | * Returns true if absolute path is successfully set. Otherwise, false. |
518 | */ |
519 | bool setAbsolutePath(const QString &abs_path); |
520 | |
521 | /*! |
522 | * Sets a list of search providers to use in case no preferred search |
523 | * providers are available. |
524 | * |
525 | * The list of preferred search providers set using this function will only |
526 | * be used if the default and favorite search providers have not yet been |
527 | * selected by the user. Otherwise, the providers specified through this |
528 | * function will be ignored. |
529 | * |
530 | * \sa alternateSearchProviders |
531 | * \sa preferredSearchProviders |
532 | */ |
533 | void setAlternateSearchProviders(const QStringList &providers); |
534 | |
535 | /*! |
536 | * Sets the search provider to use in case no default provider is available. |
537 | * |
538 | * The default search provider set using this function will only be used if |
539 | * the default and favorite search providers have not yet been selected by |
540 | * the user. Otherwise, the default provider specified by through function |
541 | * will be ignored. |
542 | * |
543 | * \sa alternateDefaultSearchProvider |
544 | * \sa preferredSearchProviders |
545 | */ |
546 | void setAlternateDefaultSearchProvider(const QString &provider); |
547 | |
548 | /*! |
549 | * Sets the default scheme used when filtering potentially valid url inputs. |
550 | * |
551 | * Use this function to change the default protocol used when filtering |
552 | * potentially valid url inputs. The default protocol is http. |
553 | * |
554 | * If the scheme is specified without a separator, then "://" will be used |
555 | * as the separator by default. For example, if the default url scheme was |
556 | * simply set to "ftp", then a potentially valid url input such as "kde.org" |
557 | * will be filtered to "ftp://kde.org". |
558 | * |
559 | * \sa defaultUrlScheme |
560 | */ |
561 | void setDefaultUrlScheme(const QString &); |
562 | |
563 | /*! |
564 | * Sets the options used by search filter plugins to filter requests. |
565 | * |
566 | * The default search filter option is SearchFilterOptionNone. See |
567 | * SearchFilterOption for the description of the other flags. |
568 | * |
569 | * It is important to note that the options set through this function can |
570 | * prevent any filtering from being performed by search filter plugins. |
571 | * As such, uriTypes can return KUriFilterData::Unknown and uri |
572 | * can return an invalid url even though the filtering request returned |
573 | * a successful response. |
574 | * |
575 | * \sa searchFilteringOptions |
576 | */ |
577 | void setSearchFilteringOptions(SearchFilterOptions options); |
578 | |
579 | KUriFilterData &operator=(const QUrl &url); |
580 | |
581 | KUriFilterData &operator=(const QString &url); |
582 | |
583 | private: |
584 | friend class KUriFilterPlugin; |
585 | std::unique_ptr<KUriFilterDataPrivate> d; |
586 | }; |
587 | |
588 | /*! |
589 | * \class KUriFilter |
590 | * \inmodule KIOGui |
591 | * |
592 | * \brief Filters the given input into a valid url whenever possible. |
593 | * |
594 | * KUriFilter applies a number of filters to a URI and returns a filtered version if any |
595 | * filter matches. |
596 | * A simple example is "kde.org" to "http://www.kde.org", which is commonplace in web browsers. |
597 | * |
598 | * The filters are implemented as plugins in KUriFilterPlugin subclasses. |
599 | * |
600 | * KUriFilter is a singleton object: obtain the instance by calling |
601 | * KUriFilter::self() and use the public member functions to |
602 | * perform the filtering. |
603 | * |
604 | * Example: |
605 | * |
606 | * To simply filter a given string: |
607 | * |
608 | * \code |
609 | * QString url("kde.org"); |
610 | * bool filtered = KUriFilter::self()->filteredUri( url ); |
611 | * \endcode |
612 | * |
613 | * You can alternatively use a QUrl: |
614 | * |
615 | * \code |
616 | * QUrl url("kde.org"); |
617 | * bool filtered = KUriFilter::self()->filterUri( url ); |
618 | * \endcode |
619 | * |
620 | * If you have a constant string or a constant URL, simply invoke the |
621 | * corresponding function to obtain the filtered string or URL instead |
622 | * of a boolean flag: |
623 | * |
624 | * \code |
625 | * QString filteredText = KUriFilter::self()->filteredUri( "kde.org" ); |
626 | * \endcode |
627 | * |
628 | * All of the above examples should result in "kde.org" being filtered into |
629 | * "http://kde.org". |
630 | * |
631 | * You can also restrict the filters to be used by supplying the name of the |
632 | * filters you want to use. By default all available filters are used. |
633 | * |
634 | * To use specific filters, add the names of the filters you want to use to a |
635 | * QStringList and invoke the appropriate filtering function. |
636 | * |
637 | * The examples below show the use of specific filters. KDE ships with the |
638 | * following filter plugins by default: |
639 | * |
640 | * kshorturifilter: |
641 | * This is used for filtering potentially valid url inputs such as "kde.org" |
642 | * Additionally it filters shell variables and shortcuts such as $HOME and |
643 | * ~ as well as man and info page shortcuts, # and ## respectively. |
644 | * |
645 | * kuriikwsfilter: |
646 | * This is used for filtering normal input text into a web search url using the |
647 | * configured fallback search engine selected by the user. |
648 | * |
649 | * kurisearchfilter: |
650 | * This is used for filtering KDE webshortcuts. For example "gg:KDE" will be |
651 | * converted to a url for searching the work "KDE" using the Google search |
652 | * engine. |
653 | * |
654 | * localdomainfilter: |
655 | * This is used for doing a DNS lookup to determine whether the input is a valid |
656 | * local address. |
657 | * |
658 | * fixuphosturifilter: |
659 | * This is used to append "www." to the host name of a pre filtered http url |
660 | * if the original url cannot be resolved. |
661 | * |
662 | * \code |
663 | * QString text ("kde.org"); |
664 | * bool filtered = KUriFilter::self()->filterUri(text, QLatin1String("kshorturifilter")); |
665 | * \endcode |
666 | * |
667 | * The above code should result in "kde.org" being filtered into "http://kde.org". |
668 | * |
669 | * \code |
670 | * QStringList list; |
671 | * list << QLatin1String("kshorturifilter") << QLatin1String("localdomainfilter"); |
672 | * bool filtered = KUriFilter::self()->filterUri( text, list ); |
673 | * \endcode |
674 | * |
675 | * Additionally if you only want to do search related filtering, you can use the |
676 | * search specific function, filterSearchUri, that is available in KDE |
677 | * 4.5 and higher. For example, to search for a given input on the web you |
678 | * can do the following: |
679 | * |
680 | * KUriFilterData filterData ("foo"); |
681 | * bool filtered = KUriFilter::self()->filterSearchUri(filterData, KUriFilterData::NormalTextFilter); |
682 | * |
683 | * KUriFilter converts all filtering requests to use KUriFilterData |
684 | * internally. The use of this bi-directional class allows you to send specific |
685 | * instructions to the filter plugins as well as receive detailed information |
686 | * about the filtered request from them. See the documentation of KUriFilterData |
687 | * class for more examples and details. |
688 | * |
689 | * All functions in this class are thread safe and reentrant. |
690 | */ |
691 | class KIOGUI_EXPORT KUriFilter |
692 | { |
693 | public: |
694 | /*! |
695 | * This enum describes the types of search plugin filters available. |
696 | * |
697 | * \value NormalTextFilter The plugin used to filter normal text, e.g. "some term to search". |
698 | * \value WebShortcutFilter The plugin used to filter web shortcuts, e.g. gg:KDE. |
699 | */ |
700 | enum SearchFilterType { |
701 | NormalTextFilter = 0x01, |
702 | WebShortcutFilter = 0x02, |
703 | }; |
704 | Q_DECLARE_FLAGS(SearchFilterTypes, SearchFilterType) |
705 | |
706 | ~KUriFilter(); |
707 | |
708 | /*! |
709 | * Returns an instance of KUriFilter. |
710 | */ |
711 | static KUriFilter *self(); |
712 | |
713 | /*! |
714 | * Filters \a data using the specified \a filters. |
715 | * |
716 | * If no named filters are specified, the default, then all the |
717 | * URI filter plugins found will be used. |
718 | * |
719 | * \a data object that contains the URI to be filtered. |
720 | * |
721 | * \a filters specify the list of filters to be used. |
722 | * |
723 | * Returns a boolean indicating whether the URI has been changed |
724 | */ |
725 | bool filterUri(KUriFilterData &data, const QStringList &filters = QStringList()); |
726 | |
727 | /*! |
728 | * Filters the URI given by the URL. |
729 | * |
730 | * The given URL is filtered based on the specified list of filters. |
731 | * If the list is empty all available filters would be used. |
732 | * |
733 | * \a uri the URI to filter. |
734 | * |
735 | * \a filters specify the list of filters to be used. |
736 | * |
737 | * Returns a boolean indicating whether the URI has been changed |
738 | */ |
739 | bool filterUri(QUrl &uri, const QStringList &filters = QStringList()); |
740 | |
741 | /*! |
742 | * Filters a string representing a URI. |
743 | * |
744 | * The given URL is filtered based on the specified list of filters. |
745 | * If the list is empty all available filters would be used. |
746 | * |
747 | * \a uri The URI to filter. |
748 | * |
749 | * \a filters specify the list of filters to be used. |
750 | * |
751 | * Returns a boolean indicating whether the URI has been changed |
752 | */ |
753 | bool filterUri(QString &uri, const QStringList &filters = QStringList()); |
754 | |
755 | /*! |
756 | * Returns the filtered URI. |
757 | * |
758 | * The given URL is filtered based on the specified list of filters. |
759 | * If the list is empty all available filters would be used. |
760 | * |
761 | * \a uri The URI to filter. |
762 | * |
763 | * \a filters specify the list of filters to be used. |
764 | * |
765 | * Returns the filtered URI or null if it cannot be filtered |
766 | */ |
767 | QUrl filteredUri(const QUrl &uri, const QStringList &filters = QStringList()); |
768 | |
769 | /*! |
770 | * Return a filtered string representation of a URI. |
771 | * |
772 | * The given URL is filtered based on the specified list of filters. |
773 | * If the list is empty all available filters would be used. |
774 | * |
775 | * \a uri the URI to filter. |
776 | * |
777 | * \a filters specify the list of filters to be used. |
778 | * |
779 | * Returns the filtered URI or null if it cannot be filtered |
780 | */ |
781 | QString filteredUri(const QString &uri, const QStringList &filters = QStringList()); |
782 | |
783 | /*! |
784 | * Filter \a data using the criteria specified by \a types. |
785 | * |
786 | * The search filter type can be individual value of SearchFilterTypes |
787 | * or a combination of those types using the bitwise OR operator. |
788 | * |
789 | * You can also use the flags from KUriFilterData::SearchFilterOption |
790 | * to alter the filtering mechanisms of the search filter providers. |
791 | * |
792 | * \a data object that contains the URI to be filtered. |
793 | * |
794 | * \a types the search filters used to filter the request. |
795 | * |
796 | * Returns \c true if the specified \a data was successfully filtered. |
797 | * |
798 | * \sa KUriFilterData::setSearchFilteringOptions |
799 | */ |
800 | bool filterSearchUri(KUriFilterData &data, SearchFilterTypes types); |
801 | |
802 | /*! |
803 | * Return a list of the names of all loaded plugins. |
804 | */ |
805 | QStringList pluginNames() const; |
806 | |
807 | protected: |
808 | /*! |
809 | * Constructor. |
810 | * |
811 | * Creates a KUriFilter object and calls loads all available URI filter plugins. |
812 | */ |
813 | KUriFilter(); |
814 | |
815 | private: |
816 | std::unique_ptr<KUriFilterPrivate> const d; |
817 | friend class KUriFilterSingleton; |
818 | }; |
819 | |
820 | Q_DECLARE_OPERATORS_FOR_FLAGS(KUriFilterData::SearchFilterOptions) |
821 | Q_DECLARE_OPERATORS_FOR_FLAGS(KUriFilter::SearchFilterTypes) |
822 | |
823 | #endif |
824 | |