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 | |
40 | class KUriFilterPrivate; |
41 | class KUriFilterDataPrivate; |
42 | class KCModule; |
43 | class QHostInfo; |
44 | |
45 | /** |
46 | * Class that holds information about a search provider. |
47 | * |
48 | * @since 4.6 |
49 | */ |
50 | class KIO_EXPORT KUriFilterSearchProvider |
51 | { |
52 | public: |
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 | |
111 | protected: |
112 | void setDesktopEntryName(const QString&); |
113 | void setIconName(const QString&); |
114 | void setKeys(const QStringList&); |
115 | void setName(const QString&); |
116 | |
117 | private: |
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 | |
169 | class KIO_EXPORT KUriFilterData |
170 | { |
171 | public: |
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 | |
627 | private: |
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 | */ |
645 | class KIO_EXPORT KUriFilterPlugin : public QObject |
646 | { |
647 | Q_OBJECT |
648 | |
649 | public: |
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 | |
694 | protected: |
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 | |
767 | private: |
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 | */ |
871 | class KIO_EXPORT KUriFilter |
872 | { |
873 | public: |
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 | |
996 | protected: |
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 | |
1013 | private: |
1014 | KUriFilterPrivate * const d; |
1015 | }; |
1016 | |
1017 | Q_DECLARE_OPERATORS_FOR_FLAGS(KUriFilterData::SearchFilterOptions) |
1018 | Q_DECLARE_OPERATORS_FOR_FLAGS(KUriFilter::SearchFilterTypes) |
1019 | |
1020 | #endif |
1021 | |