TSLPathList Class Reference

Detailed Description

The TSLPathList component is a general-purpose component that sets up a list of directories which may be searched for a given file.

May store local directories (on a hard disk, including network locations) and remote directories (via http, https, ftp or gopher).

This component is required for the TSLMapDataLayer so that it may find the individual tiles which constitute the map but it can also be used as a general purpose component outside the data layers.

A TSLDataLayer will maintain a reference on a TSLPathList the user passed to it using the TSLDataLayer::addPathList() method. The same TSLPathList can be shared by more than one TSLDataLayer at the same time. Therefore the user should make sure the TSLPathList created is not destroyed before the TSLDataLayers that point to it. You may reset to using the default pathlist by passing NULL, this is also true for the drawing surface pathlist.

In simple cases 'addDirectory' may be used, but with larger data structures addKeyedDirectory will make searching faster. 'addKeyedDirectory' must be used if a directory does not have default compression (see TSLMaplCompressionOption).

If a callback is added to the constructor, then the application is given a chance to indicate where files are to be found. This is useful for large or complex directory structures.

A callback can not be set on a pathlist for a map data-layer if you are using flashback.

Threading Notes

TSLPathList is not thread safe unless the application takes the following measures:

1. Do not use the callback.
2. If you are setting up a pathlist for the Drawing Surfaces to use; Set up the drawing surface pathlist object and add this to the drawing surface before your application starts using multiple threads.
3. If you need to change the drawing surface pathlist or modify it after your application has started its threads; Stop all threads outside of MapLink calls and do the necessary modifications.
4. If you are setting up a pathlist for data layers; Ideally use a separate pathlist per map data-layer (do not share cached layers between drawing surfaces in different threads). If you need to share the pathlist between map data-layers then only modify the pathlist when all threads using MapLink are stopped outside of MapLink method calls.

Public Member Functions
	TSLPathList (TSLPathListCallbackClass *callback=NULL, void *arg=NULL)
	~TSLPathList ()
bool	addDirectory (const char *dir_name, int location=-1)
bool	addKeyedDirectory (const char *name, const char *prefix, const char *extension, TSLMaplCompressionOption compression=TSLCompressedDefault, int location=-1)
bool	clear ()
bool	clearHistoryList ()
bool	findFile (const char *filename, TSLSimpleString &fullPath)
bool	getDirectoryName (int location, TSLSimpleString &directoryName)
bool	getKeyedDirectory (int position, const char **name, TSLMaplCompressionOption *compression=0, const char **prefix=0, const char **extension=0)
bool	getMatchingDirectoriesMT (const char *filename, TSLIndex **matches, int *matchCount)
bool	loadFromPathsFile (const char *filename, TSLFileLoader *loader, const char *root=0)
bool	removeDirectory (const char *dir_name)
int	size ()
	TSLPathList (MaplPathList *path_list)

Static Public Member Functions
static void	freeBuffer (TSLIndex *buffer)

Constructor & Destructor Documentation

TSLPathList() [1/2]

TSLPathList::TSLPathList	(	TSLPathListCallbackClass *	callback = NULL,
		void *	arg = NULL )

Constructs a TSLPathList object.

Parameters

callback

The callback class to use during getMatchingDirectories. The callback indicates whether it knows where to find the given file and/or whether the pathlist entries should be used. See TSLPathlistCallbackReturn.

The callback is made in the main thread, not a loader worker thread.

Parameters

arg	a user-defined value that will be passed to the callback routine.

Note

A callback can not be set on a pathlist for a map data-layer if you are using flashback.

~TSLPathList()

TSLPathList::~TSLPathList

(

)

Destructor for path list object.

TSLPathList() [2/2]

TSLPathList::TSLPathList

(

MaplPathList *

path_list

)

Member Function Documentation

addDirectory()

bool TSLPathList::addDirectory	(	const char *	dir_name,
		int	location = -1 )

Add directory to search list.

This method adds a new directory to the list of directories that will be examined when searching for a file. If the directory already exists in the list (with no keying) then it will be removed from its current position and placed at the given location. If the location is given as -1 the file will be added to the end of the list.

The compression is set to "default" (see TSLMaplCompressionOption). Use addKeyedDirectory if compression is not default or if keying is to be used.

Note: the location of a directory within the list may change as other directories are added and removed from the list.

Parameters

dir_name	Name of the directory to add to the list.
location	Location at which to add the directory name. -1 adds at the end of the list.

Returns

true if the directory has been added successfully, false otherwise.

addKeyedDirectory()

bool TSLPathList::addKeyedDirectory	(	const char *	name,
		const char *	prefix,
		const char *	extension,
		TSLMaplCompressionOption	compression = TSLCompressedDefault,
		int	location = -1 )

Adds a specific directory to the pathlist.

Along with the directory is filtering information describing what files are to be found in that directory, to be used by getMatchingDirectories. The information consists of a prefix which the first part of a filename must match, and an extension which the filename extension must match.

getMatchingDirectory checks the given directory against these filters and returns all directories that match, see getMatchingDirectory for more information.

Associated with the directory is a flag that indicates whether the directory is compressed or uncompressed, or has default compression (see TSLMaplCompressionOption).

If the directory already exists in the list with the same keying then it will be removed from its current position and placed at the given position. If it already exists but with different keying then it is simply added to the list.

Parameters

name	full directory to add
prefix	Prefix which files in this directory have. The beginning of the filename is checked against this prefix by getMatchingDirectories. Case is ignored. May be null if no prefix check is required.
extension	Extension which files in this directory have. The filename extension is checked against this extension by getMatchingDirectories. Case is ignored. May be null if no prefix check is required. If an empty string is passed, filenames with no extension or ending in a dot are matched.
compression	Compression of the files in this directory.
location	Position where the directory is to be added in the search list. Zero is first in the list. The default value -1 adds to the end.

Returns

true if successful.

clear()

bool TSLPathList::clear

(

)

Remove all directories from search list.

This method clears the list of directories stored. It also clears the history list.

Returns true if the directories have been removed, false otherwise.

clearHistoryList()

bool TSLPathList::clearHistoryList

(

)

Clear history of previous searches.

To speed up the search for files, any file which has previously been found will be stored in a history list. It may be necessary to clear the history list if new directories are added or removed or the location of files has been changed by some external application.

Note that the history list is only used by findFile and therefore only for local directories, not remote directories.

Returns true if the history list has been cleared successfully, false otherwise.

findFile()

bool TSLPathList::findFile	(	const char *	filename,
		TSLSimpleString &	fullPath )

Given the name of a file this method will search the directories in its list for the first one containing a file with that filename.

This method searches directories added with both addDirectory and addKeyedDirectory, but ignores the keying information.

After trying all paths in its list, the routine tries the local directory and also tries to find the file assuming that the filename is already fully qualified.

If the file is found, the routine returns a fully qualified path to the file. Otherwise it returns an empty string.

To increase speed, the function checks an internal list of previously found files, and if the filename is the same as one already found it returns the name previously found. If the file is not in the list, when it is found it is added to the list.

NOTE: Only works for local directories, not remote. There is no function for finding remote files, the FileLoader classes must be used for this.

Parameters

filename	Name of the file to find.
fullPath	Variable to return the full path to the filename if the file was found otherwise this is set to an empty string.

Returns

true if the method succeeds, false otherwise.

freeBuffer()

static void TSLPathList::freeBuffer ( TSLIndex * buffer )

static

Used to free the buffer allocated and provided to the user through the getMatchingDirectoriesMT method,

Argument List Description:

buffer: The buffer allocated and provided to the user through the getMatchingDirectoriesMT method,

getDirectoryName()

bool TSLPathList::getDirectoryName	(	int	location,
		TSLSimpleString &	directoryName )

Query name of the directory at the requested location.

Parameters

location	Location in the list of directories for which to obtain the directory name.
directoryName	the name of the directory at the given list location, or empty if there is no directory at the given location.

Returns

true if the method succeeds, false otherwise.

getKeyedDirectory()

bool TSLPathList::getKeyedDirectory	(	int	position,
		const char **	name,
		TSLMaplCompressionOption *	compression = 0,
		const char **	prefix = 0,
		const char **	extension = 0 )

Retrieves the name of the directory at the given list location. Can also return the compression setting and prefix and extension settings for the location found.

The string pointers returned are temporary and should not be stored.

See also getMatchingDirectories.

Parameters

position	Location in list from which to retrieve the information.
name	Returns the directory name.
prefix	Returns the prefix (may be null)
extension	Returns the extension (may be null)
compression	Returns the compression.

Returns

false if the given position is invalid.

getMatchingDirectoriesMT()

bool TSLPathList::getMatchingDirectoriesMT	(	const char *	filename,
		TSLIndex **	matches,
		int *	matchCount )

Thread-safe variant of the now deprecated getMatchingDirectories method.

Searches the list of directories for directories whose keying information (recorded with addKeyedDirectory) can match the given filename.

Does not use a cache list like findFile does.

If both prefix and extension are recorded for a directory then both must match the given filename. If either is null then all filenames match that filter.

If the extension stored is an empty string then it will match all filenames that have no extension or end in a dot e.g. "filename" and "filename.".

Returns a list of the indices of the matching directories, which will include all non-keyed directories (since these have no keying and so match everything).

Pass in the address of a pointer in the matches parameter, which on return will point to a list of indices of directories found. The number of directories in the list will be returned in matchCount.

If a callback was added to the constructor, the callback is called by this routine. The callback can control the other entries returned by the call, see the TSLPathlistCallbackReturn enum. If the callback returns a directory, the list of indices returned from this routine will include a special value that means "use the value returned by the last callback" when passed to getKeyedDirectory or getDirectoryName.

Does not return the local directory - if all directories returned fail to contain the file, the caller may wish to try the local directory.

Parameters

filename	File to search for.
matches	Returns a pointer to the list of directories found. This array is owned by the user and should be deleted using the TSLPathList::freeBuffer method when it has been finished with.
matchCount	Returns the number of directories found.

Returns

true if successful. Note that the only time false will be returned is if a callback was made to the application and the application indicated that the given file will definitely not exist. In these circumstances the file should not be looked for, even in the local directory.

loadFromPathsFile()

bool TSLPathList::loadFromPathsFile	(	const char *	filename,
		TSLFileLoader *	loader,
		const char *	root = 0 )

Append to the pathlist by reading keyed paths from a file. If any of the paths in the file are relative then a root directory must be passed to the routine; if all are absolute then no root directory is needed.

The file contains keyed paths - see addKeyedDirectory for more explanation.

Parameters

filename	absolute filename from which to load the pathlist
loader	file loader to use to load the file. Could be obtained by calling getLoader on a drawing surface or a data layer, or by instantiating a loader.
root	root path to be prefixed to any relative paths included in the file.

The format of the file is as follows:

TSLPTH  - header confirming that this is the right sort of file
100     - version number of format
2       - number of paths in file
        - blank line before each path
ABS     - this is an absolute (fully qualified) path - ABS or REL
d/temp;   - the absolute path followed by semicolon
layer1;   - prefix followed by semicolon (semicolon only  if none)
dat;      - extension followed by semicolon (";" means "any file".  ".;" means "any file with no extension".)
DFLT      - directory compression YES, NO or DFLT
          - blank line before each path
REL       - this is a relative path; appended to the root parameter passed to the routine (error if none passed) - ABS or REL
temp;     - the relative path followed by semicolon.  If root directory then just a semicolon.
layer2;   - prefix followed by semicolon (semicolon only  if none)
.;        - extension followed by semicolon (";" means "any file".  ".;" means "any file with no extension".)
YES       - directory compression YES, NO or DFLT.

removeDirectory()

bool TSLPathList::removeDirectory

(

const char *

dir_name

)

This method removed the specified directory from the list of directories that will be examined when searching for a file. All instances of the directory are removed (there may be several, with different keying).

Parameters

dir_name

Name of the directory to remove.

Returns

true if the directory has been removed, false otherwise.

size()

int TSLPathList::size

(

)

Query number of directory names in the path list.

Returns number of directories, -1 on error.