TSLFileLoader Class Reference

Inheritance diagram for TSLFileLoader:

Detailed Description

File loader interface class.

TSLFileLoader serves as a base class for more specialised file loaders. It provides the basic methods for loading data from local or remote files.

See description of the load() method for more details.

Public Member Functions
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

Protected Member Functions
	TSLFileLoader ()
	~TSLFileLoader ()

Constructor & Destructor Documentation

TSLFileLoader()

TSLFileLoader::TSLFileLoader ( )

inlineprotected

Protected constructor to prevent user instantiation of abstract base class.

~TSLFileLoader()

TSLFileLoader::~TSLFileLoader ( )

inlineprotected

Protected destructor to stop being instantiated on the stack Forces user to use new operator and destroy method.

Member Function Documentation

cancelAllLoads()

void TSLFileLoader::cancelAllLoads

(

)

This method instructs the loader to cancel any outstanding loads that are in progress or pending.

destroy()

void TSLFileLoader::destroy

(

)

Destroy method for general loaders. This should be called rather than deleting the loader, since the calls are redirected internally to MapLink.

fileExists()

bool TSLFileLoader::fileExists

(

const char *

filename

)

Checks that a file exists. Must be given a fully qualified path - use findMatchingFile to obtain this.

Parameters

filename

Fully qualified filename to check for existence

Returns

true if the file exists, otherwise false.

fileModificationTime()

bool TSLFileLoader::fileModificationTime	(	TSLPathList *	pathList,
		const char *	filename,
		TSLTimeType &	lastModificationTime )

Query for the time of the last modification of the given file. Searches the pathlist for matching directories and tries to find the file in these directories.

Note that the routine does not check for the file's existence. Use fileExists for this.

Always tries the local / fully qualified directory as well.

Returns true if the modification time is successfully retrieved, false otherwise.

If null is passed to the pathlist parameter then the routine can be used to determine whether a given file exists, either with a fully qualified path or in the local working directory.

Parameters

pathList	pathlist to search.
filename	file for which the last modification time is required.
lastModificationTime	This will be set to the time of the last modification of the file.

Returns

true if successful, false if not.

findMatchingFile()

bool TSLFileLoader::findMatchingFile	(	TSLPathList *	pathList,
		const char *	filename,
		TSLSimpleString &	fullPathFound,
		TSLMaplCompressionOption *	compression = 0,
		bool *	remote = 0 )

Searches the pathlist for matching directories and tries to find the file in these directories, returning if it finds a suitable path for the file.

Note that the routine does not check for the file's existence. Use fileExists for this.

Always tries the local / fully qualified directory as well.

Returns the fully qualified path in fullPathFound.

Can also return the compression setting and whether the file is remote or local, if required.

If NULL is passed to the pathlist parameter then the routine can be used to determine whether a given file exists, either with a fully qualified path or in the local working directory.

Parameters

pathList	pathlist to search.
filename	file to search for.
fullPathFound	A TSLSimpleString to store the for the fully qualified path for the 'filename'
compression	storage for the compression
remote	storage for the flag indicating whether the file is remote

Returns

true if successful, false if not.

load()

TSLLoaderStatus TSLFileLoader::load	(	TSLPathList *	pathList,
		const char *	filename,
		TSLLoaderCallback	callback,
		void *	arg,
		bool	synchronous = true )

Load data from a file, synchronously or asynchronously, with progress callbacks.

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

Parameters

pathList	list of directories to search for file. May be null. Files are searched for in the directories listed and in the local directory, or the filename may be an absolute path.
filename	file to find.
callback	function to call with progress and completion information, and to return the data when reading is successfully completed.
arg	argument passed to callback function, user-defined.
synchronous	see below.

• If synchronous return only when the load is complete, has failed, or has been cancelled.
• If not synchronous, checks if the file exists and then returns immediately.
• If the file does not exist, a failure callback is sent and the routine returns a failure.

There will always be a callback signifying the end of the load, which may be LoadingOK with done=100%, or one of the other status codes. One of these termination callbacks will always be sent for each call made to load().

Asynchronous loads are queued and happen one after another.

If the callback is made with status = LoadingOK and 100% done, the stream parameter will be valid. Note that the return value from the callback is ignored for this last callback made.

Note that when the call is asynchronous, the callback will be made from another thread, not the thread used to call load(). The user is responsible for safely synchronising the callback into the main application using thread-safe mechanisms, message passing etc., see the sample code for an example.

Note

Breaking Behaviour MapLink 7.5: The stream must not be deleted by the user.

loadImmediate()

TSLLoaderStatus TSLFileLoader::loadImmediate	(	TSLPathList *	pathList,
		const char *	filename,
		TSLifstream *	stream )

Load data from a file synchronously, returning data without using callbacks.

Parameters

pathList	list of directories to search for file. May be null. Files are searched for in the directories listed and in the local directory, or the filename may be an absolute path.
filename	file to find.
stream	pass the address of an existing stream, which on successful return will have data waiting.

loadSegment()

TSLLoaderStatus TSLFileLoader::loadSegment	(	TSLPathList *	pathList,
		const char *	filename,
		TSLFileOffset	offset,
		TSLFileLength	length,
		TSLLoaderCallback	callback,
		void *	arg,
		bool	synchronous = true )

As for 'load', but loads only a part of the file.

Parameters

pathList	list of directories to search for file. May be null. Files are searched for in the directories listed and in the local directory, or the filename may be an absolute path.
filename	file to find.
offset	offset from the start of the file
length	length of the segment
callback	function to call with progress and completion information, and to return the data when reading is successfully completed.
arg	argument passed to callback function, user-defined.
synchronous	see below.

• If synchronous return only when the load is complete, has failed, or has been cancelled.
• If not synchronous, checks if the file exists and then returns immediately.

loadSegmentImmediate()

TSLLoaderStatus TSLFileLoader::loadSegmentImmediate	(	TSLPathList *	pathList,
		const char *	filename,
		TSLFileOffset	offset,
		TSLFileLength	length,
		TSLifstream *	stream )

As for 'loadImmediate', but loads only a part of the file.

setCallback()

void TSLFileLoader::setCallback	(	TSLLoaderFileCallback	callback,
		void *	userData,
		int	loaderCallbacks )

This method allows the user to set a callback function which will be called for every file loaded by this TSLFileLoader instance.

It differs from setLoadedCallback in that it allows more flexibility in the location and combination of callbacks allowed

To disable the callback pass a NULL pointer as the callback argument.

Parameters

callback	A user supplied function conforming to the typedef TSLLoaderFileLoadedCallback. This will be called with userData when the file has been loaded but before it has been processed.
userData	A pointer to user supplied data. This will be forwarded to the user supplied callback function.
loaderCallbacks	A combination of location in the loading process where a callback will be generated. The possible value is any combination of the enum values defined in TSLFileLoaderCallbacks.

type()

TSLFileLoaderTypeEnum TSLFileLoader::type

(

)

const

This method returns the type of this file loader.