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