KUriFilterData Class Reference

from PyKDE4.kio import *

Detailed Description

This class is a basic messaging class used to exchange filtering information between the filter plugins and the application requesting the filtering service.

Use this object if you require a more detailed information about the URI you want to filter. Any application can create an instance of this class and send it to KUriFilter to have the plugins fill out all possible information about the URI.

On successful filtering you can use uriType() to determine what type of resource the request was filtered into. See KUriFilter.UriTypes for details. If an error is encountered, then KUriFilter.Error is returned. You can use errorMsg to obtain the error information.

The functions in this class are not reentrant.

Example

Here is a basic example of how this class is used with KUriFilter:

   KUriFilterData filterData (QLatin1String("kde.org"));
   bool filtered = KUriFilter.self()->filterUri(filterData);

If you are only interested in getting the list of preferred search providers, then you can do the following (requires KDE >= 4.5):

 KDE 4.5:
 KUriFilterData data;
 data.setData("<text-to-search-for>");
 data.setAlternateDefaultSearchProvider("google");
 bool filtered = KUriFilter.self()->filterUri(data, "kuriikwsfilter");

 KDE >= 4.6:
 KUriFilterData data;
 data.setData("<text-to-search-for>");
 data.setSearchFilteringOption(KUriFilterData.RetrievePreferredSearchProvidersOnly);
 bool filtered = KUriFilter.self()->filterSearchUri(data, KUriFilter.NormalTextFilter);

A class for exchanging filtering information.

Author:: Dawit Alemayehu <adawit at kde.org>

Enumerations
SearchFilterOption	{ SearchFilterOptionNone, RetrieveSearchProvidersOnly, RetrievePreferredSearchProvidersOnly, RetrieveAvailableSearchProvidersOnly }
UriTypes	{ NetProtocol, LocalFile, LocalDir, Executable, Help, Shell, Blocked, Error, Unknown }
Methods
	__init__ (self)
	__init__ (self, KUrl url)
	__init__ (self, QString url)
	__init__ (self, KUriFilterData other)
QString	absolutePath (self)
QStringList	allQueriesForSearchProvider (self, QString provider)
QString	alternateDefaultSearchProvider (self)
QStringList	alternateSearchProviders (self)
QString	argsAndOptions (self)
bool	checkForExecutables (self)
QString	defaultUrlScheme (self)
QString	errorMsg (self)
bool	hasAbsolutePath (self)
bool	hasArgsAndOptions (self)
QString	iconName (self)
QString	iconNameForPreferredSearchProvider (self, QString provider)
QStringList	preferredSearchProviders (self)
QString	queryForPreferredSearchProvider (self, QString provider)
KUriFilterSearchProvider	queryForSearchProvider (self, QString provider)
KUriFilterData.SearchFilterOptions	searchFilteringOptions (self)
QString	searchProvider (self)
QString	searchTerm (self)
QChar	searchTermSeparator (self)
bool	setAbsolutePath (self, QString abs_path)
	setAlternateDefaultSearchProvider (self, QString provider)
	setAlternateSearchProviders (self, QStringList providers)
	setCheckForExecutables (self, bool check)
	setData (self, KUrl url)
	setData (self, QString url)
	setDefaultUrlScheme (self, QString a0)
	setSearchFilteringOptions (self, KUriFilterData.SearchFilterOptions options)
QString	typedString (self)
KUrl	uri (self)
KUriFilterData.UriTypes	uriType (self)

Method Documentation

__init__ ( self )

Default constructor.

Creates a UriFilterData object.

__init__	(	self,
		KUrl	url
	)

Creates a KUriFilterData object from the given string.

Parameters:

url

is the string to be filtered.

__init__	(	self,
		QString	url
	)

Creates a KUriFilterData object from the given string.

Parameters:

url

is the string to be filtered.

__init__	(	self,
		KUriFilterData	other
	)

Copy constructor.

Creates a KUriFilterData object from another KURIFilterData object.

Parameters:

other

the uri filter data to be copied.

QString absolutePath ( self )

Returns the absolute path if one has already been set.

Returns:: the absolute path, or QString()

See also:: hasAbsolutePath()

QStringList allQueriesForSearchProvider	(	self,
		QString	provider
	)

Returns all the query urls for the given search provider.

Use this function to obtain all the different queries that can be used for the given provider. For example, if a search engine provider named "foobar" has web shortcuts named "foobar", "foo" and "bar", then this function, unlike queryForPreferredSearchProvider, will return a a query for each and every web shortcut.

See also:: queryForPreferredSearchProvider

Since:: 4.6

QString alternateDefaultSearchProvider ( self )

Returns the search provider to use when a default provider is not available.

This function returns an empty string if setAlternateDefaultSearchProvider was not called to set the default search provider to be used when none has been chosen by the user through the search configuration module.

See also:: setAlternateDefaultSearchProvider

Since:: 4.5

QStringList alternateSearchProviders ( self )

Returns the list of alternate search providers.

This function returns an empty list if setAlternateSearchProviders was not called to set the alternate search providers to be when no preferred providers have been chosen by the user through the search configuration module.

See also:: setAlternatteSearchProviders

See also:: preferredSearchProviders

Since:: 4.5

QString argsAndOptions ( self )

Returns the command line options and arguments for a local resource when present.

Returns:: options and arguments when present, otherwise QString()

bool checkForExecutables ( self )

Returns:: true if the filters should attempt to check whether the supplied uri is an executable. False otherwise.

QString defaultUrlScheme ( self )

Returns the default protocol to use when filtering potentially valid url inputs.

By default this function will return an empty string.

See also:: setDefaultUrlScheme

Since:: 4.6

QString errorMsg ( self )

Returns an error message.

This functions returns the error message set by the plugin whenever the uri type is set to KUriFilterData.ERROR. Otherwise, it returns a NULL string.

Returns:: the error message or a NULL when there is none.

bool hasAbsolutePath ( self )

Checks whether the supplied data had an absolute path.

Returns:: true if the supplied data has an absolute path

See also:: absolutePath()

bool hasArgsAndOptions ( self )

Checks whether the current data is a local resource with command line options and arguments.

Returns:: true if the current data has command line options and arguments

QString iconName ( self )

The name of the icon that matches the current filtered URL.

This function returns a null string by default and when no icon is found for the filtered URL.

QString iconNameForPreferredSearchProvider	(	self,
		QString	provider
	)

Returns the icon associated with the given preferred search provider.

You can use this function to obtain the icon names associated with the preferred search providers returned by preferredSearchProviders.

See also:: preferredSearchProviders

Since:: 4.5

QStringList preferredSearchProviders ( self )

Returns a list of the names of preferred or available search providers.

This function returns the list of providers marked as preferred whenever the input data, i.e. typedString, is successfully filtered.

If no default search provider has been selected prior to a filter request, this function will return an empty list. To avoid this problem you must either set an alternate default search provider using setAlternateDefaultSearchProvider or set one of the SearchFilterOption flags if you are only interested in getting the list of providers and not filtering the input.

Additionally, you can also provide alternate search providers in case there are no preferred ones already selected.

You can use queryForPreferredServiceProvider to obtain the query associated with the list of search providers returned by this function.

See also:: setAlternateSearchProviders

See also:: setAlternateDefaultSearchProvider

See also:: setSearchFilteringOption

See also:: queryForPreferredServiceProvider

Since:: 4.5

QString queryForPreferredSearchProvider	(	self,
		QString	provider
	)

Returns the web shortcut url for the given preferred search provider.

You can use this function to obtain the query for the preferred search providers returned by preferredSearchProviders.

The query returned by this function is in web shortcut format, i.e. "gg:foo bar", and must be re-filtered through KUriFilter to obtain a valid url.

See also:: preferredSearchProviders

Since:: 4.5

KUriFilterSearchProvider queryForSearchProvider	(	self,
		QString	provider
	)

Returns information about provider.

You can use this function to obtain the more information about the search providers returned by preferredSearchProviders.

See also:: preferredSearchProviders

See also:: KUriFilterSearchProvider

Since:: 4.6

KUriFilterData.SearchFilterOptions searchFilteringOptions ( self )

Returns the specified search filter options.

By default this function returns SearchFilterOptionNone.

See also:: setSearchFilteringOptions

Since:: 4.6

QString searchProvider ( self )

Returns the name of the search service provider, e.g. Google.

If typedString was not filtered by a search filter plugin, this function returns an empty string.

See also:: typedString

Since:: 4.5

QString searchTerm ( self )

Returns the search term portion of the typed string.

If the typedString was not filtered by a search filter plugin, this function returns an empty string.

See also:: typedString

Since:: 4.5

QChar searchTermSeparator ( self )

Returns the character that is used to separate the search term from the keyword.

If typedString was not filtered by a search filter plugin, this function returns a null charater.

See also:: typedString

Since:: 4.5

bool setAbsolutePath	(	self,
		QString	abs_path
	)

Sets the absolute path to be used whenever the supplied data is a relative local URL.

NOTE: This function should only be used for local resources, i.e. the "file:/" protocol. It is useful for specifying the absolute path in cases where the actual URL might be relative. If deriving the path from a KUrl, make sure you set the argument for this function to the result of calling path () instead of url ().

Parameters:

abs_path

the abolute path to the local resource.

Returns:: true if absolute path is successfully set. Otherwise, false.

setAlternateDefaultSearchProvider	(	self,
		QString	provider
	)

Sets the search provider to use in case no default provider is available.

The default search provider set using this function will only be used if the default and favorite search providers have not yet been selected by the user. Otherwise, the default provider specified by through function will be ignored.

See also:: alternateDefaultSearchProvider

See also:: preferredSearchProviders

Since:: 4.5

setAlternateSearchProviders	(	self,
		QStringList	providers
	)

Sets a list of search providers to use in case no preferred search providers are available.

The list of preferred search providers set using this function will only be used if the default and favorite search providers have not yet been selected by the user. Otherwise, the providers specified through this function will be ignored.

See also:: alternateSearchProviders

See also:: preferredSearchProviders

Since:: 4.5

setCheckForExecutables	(	self,
		bool	check
	)

Check whether the provided uri is executable or not.

Setting this to false ensures that typing the name of an executable does not start that application. This is useful in the location bar of a browser. The default value is true.

setData	(	self,
		KUrl	url
	)

Sets the URL to be filtered.

Use this function to set the string to be filtered when you construct an empty filter object.

Parameters:

url

the string to be filtered.

setData	(	self,
		QString	url
	)

Sets the URL to be filtered.

Use this function to set the string to be filtered when you construct an empty filter object.

Parameters:

url

the string to be filtered.

setDefaultUrlScheme	(	self,
		QString	a0
	)

Sets the default scheme used when filtering potentially valid url inputs.

Use this function to change the default protocol used when filtering potentially valid url inputs. The default protocol is http.

If the scheme is specified without a separator, then "://" will be used as the separator by default. For example, if the default url scheme was simply set to "ftp", then a potentially valid url input such as "kde.org" will be filtered to "ftp://kde.org".

See also:: defaultUrlScheme

Since:: 4.6

setSearchFilteringOptions	(	self,
		KUriFilterData.SearchFilterOptions	options
	)

Sets the options used by search filter plugins to filter requests.

The default search filter option is SearchFilterOptionNone. See SearchFilterOption for the description of the other flags.

It is important to note that the options set through this function can prevent any filtering from being performed by search filter plugins. As such, uriTypes can return KUriFilterData.Unknown and uri can return an invalid url eventhough the filtering request returned a successful response.

See also:: searchFilteringOptions

Since:: 4.6

QString typedString ( self )

The string as typed by the user, before any URL processing is done.

KUrl uri ( self )

Returns the filtered or the original URL.

If one of the plugins successfully filtered the original input, this function returns it. Otherwise, it will return the input itself.

Returns:: the filtered or original url.

KUriFilterData.UriTypes uriType ( self )

Returns the URI type.

This method always returns KUriFilterData.UNKNOWN if the given URL was not filtered.

Returns:: the type of the URI

Enumeration Documentation

SearchFilterOption

This enum describes the search filtering options to be used.

SearchFilterOptionNone

No search filter options are set and normal filtering is performed on the input data.

RetrieveSearchProvidersOnly

If set, the list of all available search providers are returned without any input filtering. This flag only applies when used in conjunction with the KUriFilter.NormalTextFilter flag.

RetrievePreferredSearchProvidersOnly

If set, the list of preferred search providers are returned without any input filtering. This flag only applies when used in conjunction with the KUriFilter.NormalTextFilter flag.

RetrieveAvailableSearchProvidersOnly

Same as doing RetrievePreferredSearchProvidersOnly | RetrieveSearchProvidersOnly, where all available search providers are returned if no preferred ones ones are available. No input filtering will be performed.

See also:: setSearchFilteringOptions

See also:: KUriFilter.filterSearchUri

Since:: 4.6

Enumerator:

SearchFilterOptionNone = 0x0
RetrieveSearchProvidersOnly = 0x01
RetrievePreferredSearchProvidersOnly = 0x02
RetrieveAvailableSearchProvidersOnly = (RetrievePreferredSearchProvidersOnly\|RetrieveSearchProvidersOnly)

UriTypes

Describes the type of the URI that was filtered. Here is a brief description of the types:

NetProtocol - Any network protocol: http, ftp, nttp, pop3, etc...

LocalFile - A local file whose executable flag is not set

LocalDir - A local directory

Executable - A local file whose executable flag is set

Help - A man or info page

Shell - A shell executable (ex: echo "Test..." >> ~/testfile)

Blocked - A URI that should be blocked/filtered (ex: ad filtering)

Error - An incorrect URI (ex: "~johndoe" when user johndoe

does not exist in that system )

Unknown - A URI that is not identified. Default value when

a KUriFilterData is first created.

Enumerator:

NetProtocol = 0
LocalFile
LocalDir
Executable
Help
Shell
Blocked
Error
Unknown

KUriFilterData Class Reference

Detailed Description

Enumerations

Methods

Method Documentation

Enumeration Documentation

Modules