KProtocolManager Class Reference

from PyKDE4.kio import *

Detailed Description

Provides information about I/O (Internet, etc.) settings chosen/set by the end user.

KProtocolManager has a heap of static functions that allows only read access to KDE's IO related settings. These include proxy, cache, file transfer resumption, timeout and user-agent related settings.

The information provided by this class is generic enough to be applicable to any application that makes use of KDE's IO sub-system. Note that this mean the proxy, timeout etc. settings are saved in a separate user-specific config file and not in the config file of the application.

Original author:

Author:: Torben Weis <weis@kde.org>

Revised by:

Author:: Waldo Bastain <bastain@kde.org>

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

See also:: KPAC

Enumerations
ProxyAuthMode	{ Prompt, Automatic }
ProxyType	{ NoProxy, ManualProxy, PACProxy, WPADProxy, EnvVarProxy }
Static Methods
QString	acceptLanguagesHeader ()
bool	autoResume ()
	badProxy (QString proxy)
KIO.CacheControl	cacheControl ()
QString	cacheDir ()
bool	canCopyFromFile (KUrl url)
bool	canCopyToFile (KUrl url)
bool	canDeleteRecursive (KUrl url)
bool	canRenameFromFile (KUrl url)
bool	canRenameToFile (KUrl url)
int	connectTimeout ()
QString	defaultMimetype (KUrl url)
QString	defaultUserAgent ()
QString	defaultUserAgent (QString keys)
KProtocolInfo.FileNameUsedForCopying	fileNameUsedForCopying (KUrl url)
bool	getSystemNameVersionAndMachine (QString systemName, QString systemVersion, QString machine)
KProtocolInfo.Type	inputType (KUrl url)
bool	isSourceProtocol (KUrl url)
QStringList	listing (KUrl url)
bool	markPartial ()
int	maxCacheAge ()
int	maxCacheSize ()
int	minimumKeepSize ()
QString	noProxyFor ()
KProtocolInfo.Type	outputType (KUrl url)
bool	persistentConnections ()
bool	persistentProxyConnection ()
QString	protocolForArchiveMimetype (QString mimeType)
KProtocolManager.ProxyAuthMode	proxyAuthMode ()
QString	proxyConfigScript ()
int	proxyConnectTimeout ()
QString	proxyFor (QString protocol)
QString	proxyForUrl (KUrl url)
KProtocolManager.ProxyType	proxyType ()
int	readTimeout ()
	reparseConfiguration ()
int	responseTimeout ()
QString	slaveProtocol (KUrl url, QString proxy)
bool	supportsDeleting (KUrl url)
bool	supportsLinking (KUrl url)
bool	supportsListing (KUrl url)
bool	supportsMakeDir (KUrl url)
bool	supportsMoving (KUrl url)
bool	supportsOpening (KUrl url)
bool	supportsReading (KUrl url)
bool	supportsWriting (KUrl url)
bool	useCache ()
bool	useProxy ()
bool	useReverseProxy ()
QString	userAgentForApplication (QString appName, QString appVersion, QStringList extraInfo=QStringList())
QString	userAgentForHost (QString hostname)

Static Method Documentation

QString acceptLanguagesHeader ( )

Return Accept-Languages header built up according to user's desktop language settings.

Returns:: Accept-Languages header string

bool autoResume ( )

Returns true if partial downloads should be automatically resumed.

Returns:: true to resume partial downloads

badProxy	(	QString	proxy
	)

Marks this proxy as bad (down). It will not be used for the next 30 minutes. (The script may supply an alternate proxy)

Parameters:

proxy

the proxy to mark as bad (as URL)

KIO.CacheControl cacheControl ( )

Returns the Cache control directive to be used.

Returns:: the cache control value

QString cacheDir ( )

The directory which contains the cache files.

Returns:: the directory that contains the cache files

bool canCopyFromFile	(	KUrl	url
	)

Returns whether the protocol can copy files/objects directly from the filesystem itself. If not, the application will read files from the filesystem using the file-protocol and pass the data on to the destination protocol.

This corresponds to the "copyFromFile=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol can copy files from the local file system

bool canCopyToFile	(	KUrl	url
	)

Returns whether the protocol can copy files/objects directly to the filesystem itself. If not, the application will receive the data from the source protocol and store it in the filesystem using the file-protocol.

This corresponds to the "copyToFile=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol can copy files to the local file system

bool canDeleteRecursive	(	KUrl	url
	)

Returns whether the protocol can recursively delete directories by itself. If not (the usual case) then KIO will list the directory and delete files and empty directories one by one.

This corresponds to the "deleteRecursive=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol can delete non-empty directories by itself.

bool canRenameFromFile	(	KUrl	url
	)

Returns whether the protocol can rename (i.e. move fast) files/objects directly from the filesystem itself. If not, the application will read files from the filesystem using the file-protocol and pass the data on to the destination protocol.

This corresponds to the "renameFromFile=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol can rename/move files from the local file system

bool canRenameToFile	(	KUrl	url
	)

Returns whether the protocol can rename (i.e. move fast) files/objects directly to the filesystem itself. If not, the application will receive the data from the source protocol and store it in the filesystem using the file-protocol.

This corresponds to the "renameToFile=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol can rename files to the local file system

int connectTimeout ( )

Returns the preferred timeout value for remote connections in seconds.

Returns:: timeout value for remote connection in secs.

QString defaultMimetype	(	KUrl	url
	)

Returns default mimetype for this URL based on the protocol.

This corresponds to the "defaultMimetype=" field in the protocol description file.

Parameters:

url

the url to check

Returns:: the default mime type of the protocol, or null if unknown

QString defaultUserAgent ( )

Returns the default user-agent value used for web browsing, for example "Mozilla/5.0 (compatible; Konqueror/4.0; Linux; X11; i686; en_US) KHTML/4.0.1 (like Gecko)"

Parameters:

keys

can be any of the following:

'o' Show OS

'v' Show OS Version

'p' Show platform (only for X11)

'm' Show machine architecture

'l' Show language

Returns:: the default user-agent value with the given keys

QString defaultUserAgent	(	QString	keys
	)

Returns the default user-agent value used for web browsing, for example "Mozilla/5.0 (compatible; Konqueror/4.0; Linux; X11; i686; en_US) KHTML/4.0.1 (like Gecko)"

Parameters:

keys

can be any of the following:

'o' Show OS

'v' Show OS Version

'p' Show platform (only for X11)

'm' Show machine architecture

'l' Show language

Returns:: the default user-agent value with the given keys

KProtocolInfo.FileNameUsedForCopying fileNameUsedForCopying	(	KUrl	url
	)

This setting defines the strategy to use for generating a filename, when copying a file or directory to another directory. By default the destination filename is made out of the filename in the source URL. However if the ioslave displays names that are different from the filename of the URL (e.g. kio_fonts shows Arial for arial.ttf, or kio_trash shows foo.txt and uses some internal URL), using Name means that the display name (UDS_NAME) will be used to as the filename in the destination directory.

This corresponds to the "fileNameUsedForCopying=" field in the protocol description file. Valid values for this field are "Name" or "FromURL" (default).

Parameters:

url

the url to check

Returns:: how to generate the filename in the destination directory when copying/moving

bool getSystemNameVersionAndMachine	(	QString	systemName,
		QString	systemVersion,
		QString	machine
	)

KProtocolInfo.Type inputType	(	KUrl	url
	)

Returns whether the protocol should be treated as a filesystem or as a stream when reading from it.

This corresponds to the "input=" field in the protocol description file. Valid values for this field are "filesystem", "stream" or "none" (default).

Parameters:

url

the url to check

Returns:: the input type of the given url

bool isSourceProtocol	(	KUrl	url
	)

Returns whether the protocol can act as a source protocol.

A source protocol retrieves data from or stores data to the location specified by a URL. A source protocol is the opposite of a filter protocol.

The "source=" field in the protocol description file determines whether a protocol is a source protocol or a filter protocol.

Parameters:

url

the url to check

Returns:: true if the protocol is a source of data (e.g. http), false if the protocol is a filter (e.g. gzip)

QStringList listing	(	KUrl	url
	)

Returns the list of fields this protocol returns when listing The current possibilities are Name, Type, Size, Date, AccessDate, Access, Owner, Group, Link, URL, MimeType as well as Extra1, Extra2 etc. for extra fields (see extraFields).

This corresponds to the "listing=" field in the protocol description file. The supported fields should be separated with ',' in the protocol description file.

Parameters:

url

the url to check

Returns:: a list of field names

bool markPartial ( )

Returns true if partial downloads should be marked with a ".part" extension.

Returns:: true if partial downloads should get an ".part" extension

int maxCacheAge ( )

Returns the maximum age in seconds cached files should be kept before they are deleted as necessary.

Returns:: the maximum cache age in seconds

int maxCacheSize ( )

Returns the maximum size that can be used for caching.

By default this function returns the DEFAULT_MAX_CACHE_SIZE value as defined in http_slave_defaults.h. Not that the value returned is in bytes, hence a value of 5120 would mean 5 Kb.

Returns:: the maximum cache size in bytes

int minimumKeepSize ( )

Returns the minimum file size for keeping aborted downloads.

Any data downloaded that does not meet this minimum requirement will simply be discarded. The default size is 5 KB.

Returns:: the minimum keep size for aborted downloads in bytes

QString noProxyFor ( )

Returns the strings for hosts that should contacted DIRECTLY, bypassing any proxy settings.

Returns:: a list of (comma-separated) hostnames or partial host names

KProtocolInfo.Type outputType	(	KUrl	url
	)

Returns whether the protocol should be treated as a filesystem or as a stream when writing to it.

This corresponds to the "output=" field in the protocol description file. Valid values for this field are "filesystem", "stream" or "none" (default).

Parameters:

url

the url to check

Returns:: the output type of the given url

bool persistentConnections ( )

Returns true if connections should be persistent

Returns:: true if the connections should be persistent

bool persistentProxyConnection ( )

Returns true if proxy connections should be persistent.

Returns:: true if proxy connections should be persistent

QString protocolForArchiveMimetype	(	QString	mimeType
	)

Returns which protocol handles this mimetype, if it's an archive mimetype. For instance zip:/ handles application/x-zip.

This is defined in the protocol description file using an entry like "archiveMimetype=application/x-zip"

Parameters:

mimetype

the mimetype to check

Returns:: the protocol that can handle this archive mimetype, for instance "zip".

Since:: 4.1

KProtocolManager.ProxyAuthMode proxyAuthMode ( )

Returns the way proxy authorization should be handled.

Returns:: the proxy authorization mode

See also:: ProxyAuthMode

QString proxyConfigScript ( )

Returns the URL of the script for automatic proxy configuration.

Returns:: the proxy configuration script

int proxyConnectTimeout ( )

Returns the preferred timeout value for proxy connections in seconds.

Returns:: timeout value for proxy connection in secs.

QString proxyFor	(	QString	protocol
	)

Returns the proxy server address for a given protocol.

Parameters:

protocol

the protocol whose proxy info is needed

Returns:: the proxy server address if one is available, or QString() if not available

QString proxyForUrl	(	KUrl	url
	)

Returns the Proxy server address for a given URL If automatic proxy configuration is configured, KPAC is used to determine the proxy server, otherwise the return value of proxyFor for the URL's protocol is used. If an empty string is returned, the request is to be aborted, a return value of "DIRECT" requests a direct connection.

Parameters:

url

the URL whose proxy info is needed

Returns:: the proxy server address if one is available or QString() otherwise

KProtocolManager.ProxyType proxyType ( )

Returns the type of proxy configuration that is used.

Returns:: the proxy type

int readTimeout ( )

Returns the preferred timeout value for reading from remote connections in seconds.

Returns:: timeout value for remote connection in secs.

reparseConfiguration ( )

Force a reload of the general config file of io-slaves ( kioslaverc).

int responseTimeout ( )

Returns the preferred response timeout value for remote connecting in seconds.

Returns:: timeout value for remote connection in seconds.

QString slaveProtocol	(	KUrl	url,
		QString	proxy
	)

Return the protocol to use in order to handle the given url It's usually the same, except that FTP, when handled by a proxy, needs an HTTP ioslave.

When a proxy is to be used, proxy contains the URL for the proxy.

Parameters:

	url	the url to check
	proxy	the URL of the proxy to use

Returns:: the slave protocol (e.g. 'http'), can be null if unknown

bool supportsDeleting	(	KUrl	url
	)

Returns whether the protocol can delete files/objects.

This corresponds to the "deleting=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol supports deleting

bool supportsLinking	(	KUrl	url
	)

Returns whether the protocol can create links between files/objects.

This corresponds to the "linking=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol supports linking

bool supportsListing	(	KUrl	url
	)

Returns whether the protocol can list files/objects. If a protocol supports listing it can be browsed in e.g. file-dialogs and konqueror.

Whether a protocol supports listing is determined by the "listing=" field in the protocol description file. If the protocol support listing it should list the fields it provides in this field. If the protocol does not support listing this field should remain empty (default.)

Parameters:

url

the url to check

Returns:: true if the protocol support listing

See also:: listing()

bool supportsMakeDir	(	KUrl	url
	)

Returns whether the protocol can create directories/folders.

This corresponds to the "makedir=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol can create directories

bool supportsMoving	(	KUrl	url
	)

Returns whether the protocol can move files/objects between different locations.

This corresponds to the "moving=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol supports moving

bool supportsOpening	(	KUrl	url
	)

Returns whether the protocol can be opened using KIO.open(const KUrl&).

This corresponds to the "opening=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol supports opening

bool supportsReading	(	KUrl	url
	)

Returns whether the protocol can retrieve data from URLs.

This corresponds to the "reading=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if it is possible to read from the URL

bool supportsWriting	(	KUrl	url
	)

Returns whether the protocol can store data to URLs.

This corresponds to the "writing=" field in the protocol description file. Valid values for this field are "true" or "false" (default).

Parameters:

url

the url to check

Returns:: true if the protocol supports writing

bool useCache ( )

Returns true/false to indicate whether a cache should be used

Returns:: true to use the cache, false otherwisea

bool useProxy ( )

Returns whether or not the user specified the use of proxy server to make connections.

Returns:: true to use a proxy

bool useReverseProxy ( )

Returns whether or not the proxy server lookup should be reversed or not.

Returns:: true to use a reversed proxy

QString userAgentForApplication	(	QString	appName,
		QString	appVersion,
		QStringList	extraInfo=QStringList()
	)

Returns the application's user-agent string. Example string is "KMail/1.9.50 (Windows/6.0; KDE/3.97.1; i686; svn-762186; 2008-01-15)", where "KMail" is the appName parameter, "1.9.50" is the appVersion parameter, "Windows/6.0; KDE/3.97.1; i686" part is added automatically and "svn-762186; 2008-01-15" is provided by extraInfo list.

Parameters:

	appName	name of the application
	appVersion	name of the application
	extraInfo	a list of elements that will be appended to the string as extra information

Returns:: the application's user-agent string

Since:: 4.1

QString userAgentForHost	(	QString	hostname
	)

Returns the user-agent string configured for the specified host.

If hostname is not found or is empty (i.e. "" or QString()) this function will return the default user agent.

Parameters:

hostname

name of the host

Returns:: specified user-agent string

Enumeration Documentation

ProxyAuthMode

Proxy authorization modes.

Prompt - Ask for authorization as needed

Automatic - Use auto login as defined in kionetrc files.

Enumerator:

Prompt
Automatic

ProxyType

Types of proxy configuration

NoProxy - No proxy is used

ManualProxy - Proxies are manually configured

PACProxy - A Proxy configuration URL has been given

WPADProxy - A proxy should be automatically discovered

EnvVarProxy - Use the proxy values set through environment variables.

Enumerator:

NoProxy
ManualProxy
PACProxy
WPADProxy
EnvVarProxy

KProtocolManager Class Reference

Detailed Description

Enumerations

Static Methods

Static Method Documentation

Enumeration Documentation

Modules