METADATA
========

Applications can provide "metadata" to the slaves. Metadata can influence
the behaviour of a slave and is usally protocol dependent. MetaData consists
of two strings: a "key" and a "value".


The following keys are currently in use:

Key             Value(s)        Description
----            --------        -----------

referrer        string          The URL from which the request originates. (read by http)

modified        string          The modification date of the document (set by http)

accept          string          List of mimetypes to accept seperated by a ", ". (read by http)

UserAgent       string          The user agent name to send to remote host (read by http)

content-type    string          The content type of the data to be uploaded (read by http)
media-*         string          Media-Parameter attributes (e.g. media-boundary)

cache           "cache"         Use entry from cache if available.
                "cacheonly"     Do not do any remote lookups, fail if not in cache. (read by http)
                "verify"        Use entry from cache, verify with remote server if expired
                "refresh"       Use entry from cache after verifying with remote server
                "reload"        Do not do any cache lookups.

no-cache        bool            Flag that indicates whether caching is enabled/disabled

window-id       number          winId() of the window the request is associated with.

resume          number          Try to get the file starting at the given offset (set by TransferJob)

charset         string          Charset of the current content as returned by a HTTP Header Response.

content-
disposition     string          Suggested name to Save a file as as returned by a HTTP Header Response.

request-id	number		Sequence number to identify requests in a MultiGet command.

UserAgent	string		HTTP User Agent to send to remote server.

expire-date	number		Date on which a cache entry needs validation.

cache-creation-date	number	Date on which a cache entry has been created.

http-refresh    string          Passes HTTP Refresh meta-data back to the application.

cookies		"auto"		Use kcookiejar to lookup and collect cookies (default)
		"manual"	Cookies set in "setcookies" are send, received cookies are reported via "setcookies".
		"none"		No cookies are send, received cookies are discarded.

setcookies	string		Used to send/receive HTTP cookies when "cookies" is set to "manual".

errorPage	bool		Flag that indicates that an errorPage() is preferred over an error(). (default:true)

no-auth		bool		Flag that indicates that no authentication attempts should be made.
no-auth-prompt	bool		Flag that indicates that only cached authentication tokens should be used.

ssl_activate_warnings	bool	Flag that disables SSL warning dialogs if set to false.  (default: true)

ssl_was_in_use	bool		Flag to tell TCPSlaveBase if SSL was in use in the previous transaction.  (default: false)

ssl_in_use	bool		Set in TCPSlaveBase to tell the caller if SSL is in use.  (default: assume false)

ssl_using_client_cert	bool	Set in TCPSlaveBase to tell the caller if the session is using a client certificate   (default: assume false)

ssl_no_client_cert	bool	Flag to tell TCPSlaveBase if it should, under no circumstances, use a client certificate.  (default: false)

ssl_force_cert_prompt	bool	Flag to tell TCPSlaveBase to force the client certificate dialog to appear on this connection.  ssl_no_client_cert overrides this flag.  This does not force the user to actually choose a certificate.  (default: false)

ssl_demand_certificate	bool	Flag to tell TCPSlaveBase to demand that a client certificate is used for this connection.  (default: false)

ssl_militant	bool		Flag to tell TCPSlaveBase "do it right, or don't do it at all".  This means that if the certificate check or any other security test fails, just silently fail the connection.  This is of particular use to favicon code.  (default: false)

ssl_cipher	string		Set in TCPSlaveBase to tell the caller which cipher is currently being used.

ssl_cipher_desc	string		Set in TCPSlaveBase to describe the details of the current cipher being used.

ssl_cipher_version	string	Set in TCPSlaveBase to describe the version of the cipher being used.

ssl_cipher_used_bits	integer	Set in TCPSlaveBase to relay the number of bits of the key actually being used in this cipher and connection.

ssl_cipher_bits	integer		Set in TCPSlaveBase to relay the number of bits the key is capable of in this cipher and connection.

ssl_peer_ip	string		Set in TCPSlaveBase to tell the caller the IP address of the peer.

ssl_cert_state	integer		Set in TCPSlaveBase to relay the state of the certificate check, without considering the cache settings.  Can be checked with KSSLCertificate enumeration.

ssl_peer_certificate	string	Set in TCPSlaveBase to relay the base64 encoding of the X.509 certificate presented by the peer.

ssl_peer_chain	string		Set, if present, in TCPSlaveBase to relay the entire certificate chain presented by the peer.  The is base64 encoded and \n delimited.

ssl_action	string		Set in TCPSlaveBase to determine what the user wishes to do about the connection.  Enumerated to {"accept", "reject"} currently.

ssl_parent_ip	string		Set in TCPSlaveBase and in the caller.  If this is the parent frame of a frame of the session (really only applies to https), this variable is set so that it can be passed back to the child frames.  It is necessary to send it to child frames so that they can do a full certificate check.

ssl_parent_cert	string		Set in TCPSlaveBase and in the caller.  As above, this must be passed to child frames by the caller so that it can compare against the certificate presented in the child frames.  It is a base64 encoding of the X.509 presented.

main_frame_request	bool	Actually for SSL, this is set in the caller to tell TCPSlaveBase if this is the request for the main frame of an html page. (dfault: true)

HTTP-Version		string	The HTTP version in use for kio_http

HTTP-Headers		string	The HTTP headers, concatenated, \n delimited

PrivacyPolicy		stringlist  \n delimited URIs referring to P3P privacy
                                policies presented by the HTTP server

PrivacyCompactPolicy	stringlist  \n delimited P3P compact tag policies
                                presented by the HTTP server

** NOTE: Anything in quotes ("") under Value(s) indicates literal value.


Examples:

E.g. the following disables cookies:
job = KIO::get( KURL("http://www.kde.org"), false, false);
job->addMetaData("cookies", "none");

If you want to handle cookies yourself, you can do:
job = KIO::get( KURL("http://www.kde.org"), false, false);
job->addMetaData("cookies", "manual");
job->addMetaData("setcookies", "Cookie: foo=bar; gnat=gnork");

The above sends two cookies along with the request, any cookies send back by
the server can be retrieved with job->queryMetaData("cookies") after
receiving the mimetype() signal or when the job is finished.

The cookiejar is not used in this case.
