gmSCFileSystemClass

The FileSystem Service Class

The service class FileSystem interacts with the operating system to form, decompose, and determine file names and attributes so that they conform the requirements of the hosting platform. In addition, it performs several low level file management operations such as searching for files and loading text files into internal text streams.

A full filename is viewed as consisting of three components:

Component	Description
pathname	Contains the location within the file system of the file. If it is omitted the the currently selected location is assumed.
localname	contains the actual name of the file. This is the only component that cannot be omitted.
extension	contains a short extension that describes the type of the file. If it is omitted then the context is often used to determine its value.

The method FileSystem_FileName

Prototype

int FileSystem_FileName(char* fileIdent,int nIdent,char* name,int iExt);

The FileSystem_FileName method extracts the local name from a full filename. In particular it locates the local name and copies it into the return parameter as a null-terminated string. If the include extension flag is nonzero, then the extension is included with the name. Its parameters are as follows:

Parameter	Description
fileIdent	Contains the file name to be parsed. It need be null-terminated only if its length is not specified.
nIdent	Specifies the length of file name. If it is set to zero, then the length is computed.
name	Receives the localname of the file possibly concatenated with its extension. It is null-terminated.
iExt	Specifies whether the extension should be included in the returned name. If it is nonzero, then the extension is included in the name.

This method returns the overall length of the local name.

The method FileSystem_FindFiles

Prototype

void* FileSystem_FindFiles(char* directory,char* extensions);

The FileSystem_FindFiles method searches the directory tree starting in a specified directory for all files that have some specified number of extensions. The full names of the local files are stored in a text stream whose handle is the return value of this method. Its parameters are as follows:

Parameter	Description
directory	Contains the full name of the root directory for the search.
extensions	Contains a comma-delimited string of the extensions to be searched for.

The method returns the handle of the local text stream which contains the full filenames. It can be NULL, if it could not be created. It can contain no entries, if no files were found or if the starting directory did not exist.

The method FileSystem_GetDirectory

Prototype

int FileSystem_GetDirectory(char* buffer,char* string,int nString,int remove);

The FileSystem_GetDirectory method gets the full directory name from a path name by removing the local filename. In addition, it may remove additional subdirectory names. Its parameters are as follows:

Parameter	Description
buffer	Receives the directory name extracted from the pathname in null-terminated form.
string	Contains the full pathname of a file whose directory location is wanted. It need be null-terminated only if nString set to zero.
nString	Specifies the overall length of the pathname. If set to zero, then the length of the pathname is computed.
removed	Specifies the number of subdirectory names to be removed from the back of the directory name.

This method returns the length in characters of the returned directory name.

The method FileSystem_LoadFile

Prototype

int FileSystem_LoadFile(void* Storage,char* filename,int strip);

The FileSystem_LoadFile method loads the content of a text file into a text stream in storage. Optionally, leading and/or trailing whitespace is stripped. The file is closed after it has been read. Note that both ASCII and Unicode files can be read by this method. The Unicode is transparently converted to ASCII before loading the records into the text stream. Its parameters are as follows:

Parameter

Description

Storage

Specifies the handle for the storage area to contain the text buffer. If this handle is NULL, then the text buffer will be allocated to a memory based storage area. If the LoadFile_UseExisting entry flag is set then this parameter Specifies the handle of the text stream.

filename

Contains the full filename for the text file whose content is to be loaded.

strip

Specifies how records are to be modified and/or stored in the text stream. The bits this parameter are used as follows:

Entry	Description of use
LoadFile_StripTrailing	strip trailing whitespace
LoadFile_StripLeading	strip leading white space
LoadFile_ReplaceCR	replace embedded CR’s with newlines
LoadFile_NullTerminate	terminate stored records with null-byte
LoadFile_UseExisting	insert file into existing text stream

The method returns the root offset of the variable information stream that contains the records of the file if all goes well. If the file cannot be opened with readonly access, then a zero is returned.

The method FileSystem_MakeFullName

Prototype

int FileSystem_MakeFullName(char* path,char* name,int nname,char* ext,char* fullname);

The FileSystem_MakeFullName method forms a full filename from its components. This method views a file as though it consisted of three concatenated components: path name, local name, and extension. This method constructs the full name in accordance with the conventions of the platform. It has the following parameters:

Parameter	Description
path	Contains the path name to be used. It may be NULL, in which case a local filename is constructed.
name	Contains the local name of the file. It need not be null-terminated if the nname parameter is not zero.
nname	Specifies the number of characters in the beginning of the name parameter. If it is zero, then the name string must be null-terminated and its entire content is used.
ext	Contains the extension to be used. If it is NULL then the filename contains no extension.
fullname	Receives the full constructed name of the file in null-terminated form. If is up to the user to ensure that it contains sufficient space.

The method returns the overall length of the filename as constructed.

The method FileSystem_MakeLocalName

Prototype

int FileSystem_MakeLocalName(char* FileName,char* LocalName,int LocalLength,CONST char* Extension,int XtnLength);

The FileSystem_MakeLocalName method creates a local filename by concatenating a local name with the local extension character and an extension. Note that the local name may already contain an extension. In that case that extension is replaced. Its parameters are:

Parameter	Description
FileName	Receives the constructed local filename in null-terminated form.
LocalName	Contains the local name to be used. This name may already have an extension at its back. This method does not check the front of this name therefore, it may contain a path name as well.
LocalLength	specifies length of local name. A value of zero means that LocalName is null-terminated and its length is computed.
Extension	Contains the extension.
XtnLength	Specifies the length of the extension. If it is zero then Extension is assumed to be null-terminated.

The method returns the length of the constructed filename.

The method FileSystem_ParseFileName

Prototype

int FileSystem_ParseFileName(char* FileName,int Length,int* LocalStart,int* XtnStart);

The FileSystem_ParseFileName method parses a filename into its components. It views a filename as though it consisted of three concatenated components: path name, local name, and extension. This method computes the relative position within the full name of the start of the local name and the start of the extension. Since the path name is always first, if the local name start is greater than zero, then the beginning of the filename contains a path name. Its parameters are as follows:

Parameter	Description
FileName	Contains the filename to be parsed. It need be null-terminated only if Length set to zero.
Length	Specifies the overall length of the filename. If set to zero, then the length of the filename is computed.
LocalStart	returns the offset of the start of the local name in the filename. A value of zero indicates that the name contains no path name component.
XtnStart	returns the offset of the start of the extension in the filename. A value of Length indicates that the name had no extension.

The method returns the overall length of the filename.

The method FileSystem_RelativePathName

Prototype

int FileSystem_RelativePathName(char* parent,char* child,char* relative);

The FileSystem_RelativePathName method creates a relative pathname of a child file as referenced by a parent file, such as a code file being referenced by a project file. Its parameters are as follows:

Parameter	Description
parent	Contains the full pathname of the parent file.
child	Contains the full pathname of the child file.
relative	Receives the relative pathname required to reference the child file when in the parent location.

The method returns the length of the relative name.