gmSCFileSystemClass

Owned by Mark Juras
Last updated: Jul 25, 2018Version comment

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.
Table of Contents