TSLFileLoaderRemote Class Reference

Inheritance diagram for TSLFileLoaderRemote:

Detailed Description

A loader that can load remote files, which are those in paths starting with http://, ftp:// or https://

Can also decompress files (either remote or local).

Can be used asynchronously (multi-threaded with callbacks) or synchronously (return when finished).

Public Member Functions
	TSLFileLoaderRemote (unsigned int maximumConcurrentRequests=1)
bool	addCredentials (const char *username, const char *password, const char *address)
bool	allowInvalidSSLCertDomain () const
void	allowInvalidSSLCertDomain (bool value)
bool	allowUnknownSSLAuthorities () const
void	allowUnknownSSLAuthorities (bool value)
void	clearCachedCredentials ()
bool	enableContentCompression () const
void	enableContentCompression (bool value)
TSLLoaderStatus	loadPOST (const char *addressURL, const char *mimeType, unsigned char *buffer, unsigned int lengthOfBuffer, TSLLoaderCallback callback, void *arg, bool synchronous=true)
void	maximumConcurrentRequests (unsigned int maximumConcurrentRequests)
unsigned int	maximumConcurrentRequests () const
void	remoteAuthenticationCallback (TSLRemoteAuthenticationCallback *callback)
TSLLoaderStatus	loadGET (const char *addressURL, TSLLoaderCallback callback, void *arg, bool synchronous=true)
bool	addCertificates (const char *certificatePath, const char *address)
void	clearCachedCertificates ()
void *	operator new (size_t size) TSL_NO_THROW
void *	operator new (size_t size, char *filename, int line)
Public Member Functions inherited from TSLFileLoader
void	cancelAllLoads ()
void	destroy ()
bool	fileExists (const char *filename)
bool	fileModificationTime (TSLPathList *pathList, const char *filename, TSLTimeType &lastModificationTime)
bool	findMatchingFile (TSLPathList *pathList, const char *filename, TSLSimpleString &fullPathFound, TSLMaplCompressionOption *compression=0, bool *remote=0)
TSLLoaderStatus	load (TSLPathList *pathList, const char *filename, TSLLoaderCallback callback, void *arg, bool synchronous=true)
TSLLoaderStatus	loadImmediate (TSLPathList *pathList, const char *filename, TSLifstream *stream)
TSLLoaderStatus	loadSegment (TSLPathList *pathList, const char *filename, TSLFileOffset offset, TSLFileLength length, TSLLoaderCallback callback, void *arg, bool synchronous=true)
TSLLoaderStatus	loadSegmentImmediate (TSLPathList *pathList, const char *filename, TSLFileOffset offset, TSLFileLength length, TSLifstream *stream)
void	setCallback (TSLLoaderFileCallback callback, void *userData, int loaderCallbacks)
TSLFileLoaderTypeEnum	type () const

Additional Inherited Members
Protected Member Functions inherited from TSLFileLoader
	TSLFileLoader ()
	~TSLFileLoader ()

Constructor & Destructor Documentation

TSLFileLoaderRemote()

TSLFileLoaderRemote::TSLFileLoaderRemote

(

unsigned int

maximumConcurrentRequests = 1

)

Constructor

Parameters

maximumConcurrentRequests

The maximum number of requests for an instance of the TSLFileLoaderRemote class to handle.

Member Function Documentation

addCertificates()

bool TSLFileLoaderRemote::addCertificates	(	const char *	certificatePath,
		const char *	address )

Add a certificate to the cache. The supplied certificate will be attached to all requests sent to the supplied address.

If the address already exists in the cache, the certificate will be replaced.

Parameters

certificatePath	the file path to the .cer file
address	the url address the certificate is to be used for

Returns

true on success, false otherwise.

addCredentials()

bool TSLFileLoaderRemote::addCredentials	(	const char *	username,
		const char *	password,
		const char *	address )

Add a set of credentials to the cache. The supplied username and password will be used for all addresses which begin with the supplied address.

If the address already exists in the cache, the credentials will be replaced.

Parameters

username	The username for the address.
password	The password for the address.
address	The address to set the credentials for.

Returns

true if the credentials were added to the cache, false otherwise

allowInvalidSSLCertDomain() [1/2]

bool TSLFileLoaderRemote::allowInvalidSSLCertDomain

(

)

const

Queries whether to allow SSL certificates that do not correspond to the domain name being accessed.

When connecting to remote servers using SSL, by enabling this flag the loader will not fail due to the server's certificate not corresponding to the domain name being accessed. By default this flag is set to false.

allowInvalidSSLCertDomain() [2/2]

void TSLFileLoaderRemote::allowInvalidSSLCertDomain

(

bool

value

)

Sets whether to allow SSL certificates that do not correspond to the domain name being accessed.

When connecting to remote servers using SSL, by enabling this flag the loader will not fail due to the server's certificate not corresponding to the domain name being accessed. By default this flag is set to false.

allowUnknownSSLAuthorities() [1/2]

bool TSLFileLoaderRemote::allowUnknownSSLAuthorities

(

)

const

Queries whether to allow SSL certificates to be issued by an unknown authority.

When connecting to remote servers using SSL, by enabling this flag the loader will not fail due to the server's certificate being issued from an untrusted signing authority. By default this flag is set to false.

allowUnknownSSLAuthorities() [2/2]

void TSLFileLoaderRemote::allowUnknownSSLAuthorities

(

bool

value

)

Set whether to allow SSL certificates to be issued by an unknown authority.

When connecting to remote servers using SSL, by enabling this flag the loader will not fail due to the server's certificate being issued from an untrusted signing authority. By default this flag is set to false.

clearCachedCertificates()

void TSLFileLoaderRemote::clearCachedCertificates

(

)

Deletes all credentials from the cache.

clearCachedCredentials()

void TSLFileLoaderRemote::clearCachedCredentials

(

)

Deletes all credentials from the cache.

enableContentCompression() [1/2]

bool TSLFileLoaderRemote::enableContentCompression

(

)

const

Queries whether requests should include the "Accept-Encoding" header with a value of "gzip". Assuming the server supports this, the response will be sent back compressed, thus reducing network traffic. This does have the draw back that additional processing is required at both the server and client however.

By default this flag is set to false.

enableContentCompression() [2/2]

void TSLFileLoaderRemote::enableContentCompression

(

bool

value

)

Sets whether requests should include the "Accept-Encoding" header with a value of "gzip". Assuming the server supports this, the response will be sent back compressed, thus reducing network traffic. This does have the draw back that additional processing is required at both the server and client however.

By default this flag is set to false.

loadGET()

TSLLoaderStatus TSLFileLoaderRemote::loadGET	(	const char *	addressURL,
		TSLLoaderCallback	callback,
		void *	arg,
		bool	synchronous = true )

Performs an HTTP GET request to the URL provided. An optional buffer may be provided that contains this content.

The request will be made synchronously.

If successful, the body of the response is returned in a stream as part of the callback function.

Parameters

addressURL	The address of the target of the request
callback	Function to call when the operation has been completed successfully. The server response will be passed in the form of a TSLifstream to the function.
arg	Argument passed to callback function, user-defined.
synchronous	Reserved for future use.

If the operation is successful, a call will be made to the passed callback and the value TSLLoadingOK will be returned. Otherwise a status code denoting the reason for failure will be returned.

loadPOST()

TSLLoaderStatus TSLFileLoaderRemote::loadPOST	(	const char *	addressURL,
		const char *	mimeType,
		unsigned char *	buffer,
		unsigned int	lengthOfBuffer,
		TSLLoaderCallback	callback,
		void *	arg,
		bool	synchronous = true )

Performs an HTTP POST request to the URL provided. A mime type should be provided to denote the format of the content of the request, while an optional buffer may be provided that contains this content.

The request will be made synchronously.

If successful, the body of the response is returned in a stream as part of the callback function.

Parameters

addressURL	The address of the target of the request
mimeType	The format of the content of the request
buffer	The content of the request. If this parameter is null then the request will be made with no content.
lengthOfBuffer	The length of the buffer passed in the buffer parameter
callback	Function to call when the operation has been completed successfully. The server response will be passed in the form of a TSLifstream to the function.
arg	Argument passed to callback function, user-defined.
synchronous	Reserved for future use.

If the operation is successful, a call will be made to the passed callback and the value TSLLoadingOK will be returned. Otherwise a status code denoting the reason for failure will be returned.

maximumConcurrentRequests() [1/2]

unsigned int TSLFileLoaderRemote::maximumConcurrentRequests

(

)

const

Returns the number of maximum concurrent requests for an instance of this class.

maximumConcurrentRequests() [2/2]

void TSLFileLoaderRemote::maximumConcurrentRequests

(

unsigned int

maximumConcurrentRequests

)

Sets the number of maximum concurrent requests for an instance of this class.

Parameters

maximumConcurrentRequests

The maximum number of requests for an instance of the TSLFileLoaderRemote class to handle.

operator new() [1/2]

void * TSLFileLoaderRemote::operator new

(

size_t

size

)

Overridden allocation to redirect to MapLink

operator new() [2/2]

void * TSLFileLoaderRemote::operator new	(	size_t	size,
		char *	filename,
		int	line )

When included in an MFC application in debug mode, the debug new expects this to be here. Override it and return the same as the normal one. The library must include it when compiled in release mode, since the user's application may be in debug mode.

remoteAuthenticationCallback()

void TSLFileLoaderRemote::remoteAuthenticationCallback

(

TSLRemoteAuthenticationCallback *

callback

)

Sets the TSLRemoteAuthenticationCallback used when server credentials are required.

The callback will be called any time the loader encounters the http 401 (unauthorised) response.

MapLink does not automatically cache the returned credentials, please use the addCredentials method if they need to be cached for further requests.

Pass NULL as the parameter to clear the callback.

Parameters

callback

The TSLRemoteAuthenticationCallback instance to use.