filesystem_t class reference

This covers the abstract filesystem_t class, plus the supplied concrete classes.

Character Set in the PC Filesystem

In the PC_filesystem_t concrete class, the Unicode version of the Win32 primitives will be used if at run-time they are found to be supported. Otherwise the ANSI versions will be used.
Note: this feature has not been implemented yet. For now, the ANSI forms are always used.


virtual void assure_path_exists (filename_t) =0

public

This function creates subdirectories, if necessary, so that the path specified exists. The file name part, if present, is ignored.

If the path did not already exist or could not be created, an exception is thrown detailing the nature of the error. In the event of an error, the path may have been partially created.


virtual int dotname (const ustring&)

public

This recognises the "dotnames" that may be used as parts of a path.

If the argument is not a special name, return -1.

If the argument is a special name, return the number of parts to be removed. That is, "." returns 0, ".." returns 1, "..." returns 2, etc. This function exists here so you can override it to change (or even disable) the recognition of these special names.


virtual bool exists (const filename_t&) const =0

public

This returns true if the specified filename exists. It does distinguish between files and directories, so if a directory exists with the name you asked for as a file, or vice-versa, the function returns false.

In the PC_filesystem_t concrete class, it uses the Win32 function FindFirstFile to check for the file's (or directory's) existance, and then checks the attribute bits to make sure it's the right kind of thing. The usual mechanism is used for ANSI vs. Unicode names.

In the URL_filesystem_t ... TBA.


virtual filename_t fully_qualify (const filename_t&) =0

public

This returns the fully-qualified form of the input name. That is, it merges the "current" working directory information with the contents of the specified name.

In the PC_filesystem_t concrete class, it uses the Win32 function GetFullPathName to do this work.

There is a bug in GetFullPathName as tested under Windows NT 4.0 SP3. It does not give the correct (or even meaningful) result when qualifing relative paths on drives other than the default drive when the logged path on the drive in question is not the root. This will be handled by this function directly in a later update.

For removable media, GetFullPathName will hit the disk when called. This results in a long timeout and an error for removed disks.

To interactivly test this function, use the filename_t_test.cxx program with an argument of Q followed by the argument to the fully_qualify function. The result will be sent to standard output.

Sample command prompt:

[e:\dev\progress\compile.vc5\bin_release]filename_t_test.exe Q "foo\bar"
E:\dev\progress\compile.vc5\bin_Release\foo\bar

[e:\dev\progress\compile.vc5\bin_release]_

The usual mechanism is used for ANSI vs. Unicode names.

In the URL_filesystem_t ... TBA.


virtual int stringcompare (const ustring& left, const ustring& right) const

public

This compares two strings according to the rules used by the file system. Of particular note are characters that are treated as being the same thing, such as with the case-insensitive PC file system ("A" == "a"), or escape codes in URLs ("%41"=="A").

In the PC_filesystem_t concrete class, it uses the Win32 function LCMapString to do this work. This function seems to be the only place in the Win32 documentation that indicates that case-insensitive matching is different for file names than for normal strings which should use the current locale. The simpler CompareString function does not have a flag for this, so it cannot be used here. More information on this issue will be added as it becomes known.

The return value is negative, zero, or positive to indicate whether left is less than, equal to, or greater than right, respectivly. This is the same kind of result that you know from the standard C function strcmp.

note: could add another function to return a sort key


virtual bool stringmatch (const ustring& left, const ustring& right) const

public

This function is semantically equivilent to (0==stringcompare(left,right)), but potentially more efficient as the code can be simpler.


signatures not yet documented

   virtual filesystem_t* clone() const =0;
   virtual index_t* parse (wstring) const =0;
   virtual void create (const filename_t&) const {}
   wstring seperator() const { return Seperator; }
   CLASSICS_EXPORT virtual filename_t directory (const ustring&);