FileSystem

Version:1.0
Status:Unspecified
Date:October 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1998-2001. All rights reserved.



Function Index
AddAssign  Adds a new directory assignment to the system.
AnalyseLocation  Analyses location strings to determine their type (file, directory or assign).
AssignList  Returns a list of all directory assignments.
CopyLocation  Makes copies of directories and files.
DeleteAssign  Deletes directory assignments from the system.
MakeDirectory  Makes new directories.
MoveLocation  Moves directories and files to new locations.
ResolveAssign  Resolves assign strings into absolute paths.

 

Function:AddAssign()
Short:Adds a new directory assignment to the system.
Synopsis:ERROR AddAssign(STRING Name, STRING Path, LONG Flags)
Arguments:
Name  The name of the assignment.
Path  A list of paths to add to the assignment.
Flags  Optional flag settings.

The AddAssign() function is used to add a series of paths to an assignment name. This has the effect of preserving any existing paths that are attributed to the assignment if it already exists. If the assignment does not already exist, a new one will be created from scratch.

The Path argument accepts multiple path definitions if you seperate each path with a semicolon. Each path definition must end with a forward slash to denote a directory location.

Result
ERR_Okay  The assignment was sucessfully added.
ERR_Args  Invalid arguments were specified.
ERR_ExclusiveDenied  Access to the SystemAssignments shared object was denied.
ERR_AllocMemory  Failed during the allocation of a new memory block.

 

Function:AnalyseLocation()
Short:Analyses location strings to determine their type (file, directory or assign).
Synopsis:ERROR AnalyseLocation(STRING Location, LONG *LocationType)
Arguments:
Location  The location that you want to analyse.
LocationType  The result will be stored in the LONG variable referred to by this argument. The return types are LOC_DIRECTORY, LOC_FILE and LOC_ASSIGN.

This function will analyse a file location and determine what type of file type that the location is referring to. For instance, a location of "athene:documents/" would indicate a directory reference. A location of "pandora:" would be recognised as an assignment. A location of "athene:documents/copyright.txt" would be recognised as a file.

Ambiguous references are analysed to get the correct type - for example "athene:documents/helloworld" could be a directory or a file, so the location is analysed to check the location type. On occasions where the location exists as both a directory and a file, the function will detect the directory type first and return a LOC_DIRECTORY result.

Locations are always checked to see if they actually exist - if they do not, a fail code is returned.

Result
ERR_Okay  The location was analysed and the result is stored in the LocationType variable.
ERR_Args  Invalid arguments were specified.
ERR_Failed  The location could not be analysed.

 

Function:AssignList()
Short:Returns a list of all directory assignments.
Synopsis:ERROR AssignList(STRING **List)
Arguments:
List  Must point to an empty 'STRING *' variable for the generated list to be stored.

This function will return all registered directory assignments as a list of alpha-numerically sorted strings. You are required to supply a pointer to a 'STRING *' variable for the generated list to be stored. This list is allocated as a normal memory block and you are required to free it once you no longer require its services. The string list is terminated with a NULL entry to indicate the list's end.

Each listed assignment is fully qualified with a colon at the end of each string, i.e. "athene:", not "athene".

Result
ERR_Okay  Success.
ERR_Args  No List argument was specified.
ERR_NoData  There are no assignments in the system.
ERR_AllocMemory  The memory needed for the List could not be allocated.

 

Function:CopyLocation()
Short:Makes copies of directories and files.
Synopsis:ERROR CopyLocation(STRING Source, STRING Destination)
Arguments:
Source  The source location.
Destination  The destination location.

This function is used to copy files and directories to new locations. When copying directories it will do so recursively, so as to copy all sub-directories and files within the location.

It is important that you are aware that different types of string formatting can give different results. The following examples illustrate:

SourceDestinationResult
athene:makefileathene:documentsathene:documents
athene:makefileathene:documents/athene:documents/makefile
athene:pictures/athene:documents/athene:documents/pictures
athene:pictures/athene:documentsathene:documents (Existing documents directory destroyed)

This function will overwrite the destination location if it already exists.

The Source argument should always clarify the type of location that is being copied - e.g. if you are copying a directory, you must specify a forward slash at the end of the string or the function will assume that you are copying a file.

Result
ERR_Okay  The location was copied successfully.
ERR_Args  Invalid arguments were specified.
ERR_Failed  A failure occurred during the move process.

 

Function:DeleteAssign()
Short:Deletes directory assignments from the system.
Synopsis:ERROR DeleteAssign(STRING Name)
Arguments:
Name  The name of the assignment.

This function deletes assignments from the system. Once an assignment is deleted, any further references to that assignment will result in errors unless the assignment is recreated. All paths that are related to the assignment are destroyed as a result of calling this function.

Result
ERR_Okay  The assignment was deleted.
ERR_Args  Invalid arguments were specified.
ERR_ExclusiveDenied  Access to the SystemAssignments object was denied.

 

Function:MakeDirectory()
Short:Makes new directories.
Synopsis:ERROR MakeDirectory(STRING Location)
Arguments:
Location  The location of the directory.

This function makes directories. Creating a new directory is as simple as specifying the new directory location. Currently, this function does not support the creation of multiple directories in a single call - for instance, to create a directory of "athene:apple/banana/orange/" you need to call this function three times - i.e. "athene:apple/", "athene:apple/banana/" and "athene:apple/banana/orange/". This restriction may be removed in future.

Result
ERR_Okay  The directory was created successfully.
ERR_Args  The Location argument was not specified.
ERR_Failed  A failure occurred during the directory creation.

 

Function:MoveLocation()
Short:Moves directories and files to new locations.
Synopsis:ERROR MoveLocation(STRING Source, STRING Destination)
Arguments:
Source  The source location.
Destination  The destination location.

This function is used to move files and directories to new locations. It can be used for renaming purposes as well as moving data between different types of media. When moving directories, any contents within the directory will also be moved across to the new location.

It is important that you are aware that different types of string formatting can give different results. The following examples illustrate:

SourceDestinationResult
athene:makefileathene:documentsathene:documents
athene:makefileathene:documents/athene:documents/makefile
athene:pictures/athene:documents/athene:documents/pictures
athene:pictures/athene:documentsathene:documents (Existing documents directory destroyed)

This function will overwrite the destination location if it already exists.

The Source argument should always clarify the type of location that is being copied - e.g. if you are copying a directory, you must specify a forward slash at the end of the string or the function will assume that you are copying a file.

Result
ERR_Okay  The location was moved successfully.
ERR_Args  Invalid arguments were specified.
ERR_Failed  A failure occurred during the move process.

 

Function:ResolveAssign()
Short:Resolves assign strings into absolute paths.
Synopsis:ERROR ResolveAssign(STRING Assign, STRING *Result, LONG Flags)
Arguments:
Assign  The assignment string that needs to be resolved.
Result  Must refer to an empty STRING variable so that the resolved path can be stored.
Flags  Optional flags.

This function will resolve an assignment to its true file path for the native system. For instance, on a Linux system an assigned location such as "athene:documents/readme.txt" would usually translate to "/athene/documents/readme.txt". On a Windows system, the same string could translate to "c:/athene/documents/readme.txt".

If an assignment refers to multiple paths, the ResolveAssign() method will attempt to guess the correct path by checking for the validity of each possible location. For instance, if you are resolving an assignment of "user:document.txt" and the "user:" assignment refers to "system:users/joebloggs/" and "system:users/default/", the routine will check both directories for the existence of the document.txt file to determine the correct location. While helpful, this can often cause problems when creating new files. To circumvent this feature, use the RSF_NOFILECHECK setting in the Flags argument.

You are required to supply a STRING variable in the Result argument so that the resolved path can be stored. The Result string is allocated as a normal memory block, so you will need to free it once you no longer require its services.

Result
ERR_Okay  The assignment was resolved.
ERR_Args  Invalid arguments were specified.
ERR_AllocMemory  The result string could not be allocated.
ERR_ExclusiveDenied  Access to the SystemAssignments object was denied.
ERR_Search  The given assignment does not exist.
ERR_Loop  The assignment refers back to itself.