FileSystem

Version:1.0
Status:Stable
Date:February 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1998-2004. All rights reserved.



Function Index
AnalyseLocation  Analyses location strings to determine their type (file, directory or assign).
CopyLocation  Makes copies of directories and files.
DeleteAssign  Deletes directory assignments from the system.
DeleteFile  Deletes files and directories.
FileCaseSensitive  Enables case sensitivity for certain file functions.
GetDeviceInfo  Returns information on an available device.
GetFileIcon  Analyses a file to determine the icon that should be used for graphical representation.
GetFileInfo  Returns information for a specific file or directory location.
IdentifyFile  Used for associating data with object classes.
MakeDirectory  Makes new directories.
MoveLocation  Moves directories and files to new locations.
ResolveAssign  Resolves assign strings into absolute paths.
SaveObjectToFile  Saves an object to a destination file.
SetAssign  Adds a new directory assignment to the system.

 

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. You can set this argument to NULL if you are only interested in checking if the location exists.

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: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:DeleteFile()
Short:Deletes files and directories.
Synopsis:ERROR DeleteFile(STRING Location)
Arguments:
Location  String referring to the file or directory to be deleted. Directories must be denoted with a trailing slash.

This function will delete a file or directory when given a valid file location. The current user must have delete access to the given file. When deleting directories, all directory content will be scanned and deleted recursively.

Result
ERR_Okay  The file or directory was deleted successfully.
ERR_Args  The Location parameter was not specified.
ERR_FileNotFound  The file location does not exist.
ERR_File  The location could not be opened for deletion.

Function:FileCaseSensitive()
Short:Enables case sensitivity for certain file functions.
Synopsis:LONG FileCaseSensitive(LONG Status)
Arguments:
Status  Set to TRUE to enable case sensitivity or FALSE to turn it off.

This function is used to turn on case sensitivity for certain functions like AnalyseLocation(). When the case sensitivity value is set to TRUE, all filename checks will be made on a case-sensitive basis. The default value is FALSE.

If you use this function, please set the sensitivity back to its original state after use.

Result
The previous sensitivity value is returned by this function (either TRUE or FALSE).


Function:GetDeviceInfo()
Short:Returns information on an available device.
Synopsis:ERROR GetDeviceInfo(STRING Path, struct DeviceInfo *Info, LONG InfoSize)
Arguments:
Path  The location or name of the device.
Info  Must point to a DeviceInfo structure.
InfoSize  The size of the structure passed in the Info parameter, in bytes.

The GetDeviceInfo() function returns information on a particular device or software assignment. You need to provide a valid assign reference in order to make a successful analysis. If the Path does not refer to a valid assignment as identifiable by the AnalyseLocation() function, the call will fail. The Path will be scanned until it encounters the first colon or null-byte, so strings such as "cd1", "cd1:" and "cd1:documents/" will all be identified as the "cd1" device.

Information on the device will be returned in the Info structure. This structure includes the following fields:

FieldDescription
LARGE FlagsFlags identifying the device and type of media available (see flags).
LARGE DeviceSizeThe limiting size of the device/media, in bytes.
LARGE BytesAvailableThe number of bytes available to the user, in bytes.
LARGE BytesUsedThe total number of bytes already in use on the current media.

Flags clarifying device details are as follows:

FlagsDescription
DEVICE_COMPACTDISCThe device uses compact disc media.
DEVICE_HARDDISKThe device is a hard disk.
DEVICE_FLOPPYDISKThe device supports removeable floppy disks or similarly styled media.
DEVICE_READThe device is readable.
DEVICE_WRITEThe device is writeable.
DEVICE_REMOVEABLEThe media can be removed from the device.
DEVICE_SOFTWAREThe device is written purely as a software/virtual device.
DEVICE_NETWORKThe device refers to an unknown storage system at a network location.
DEVICE_TAPEThe device uses magnetic tape or is based on streaming media.
DEVICE_PRINTERThe device is a printer (write only).
DEVICE_SCANNERThe device is an image scanner (read only).
DEVICE_TEMPORARYAll information stored on this device is held temporarily (e.g. may be lost on power-off).
DEVICE_MEMORYThe device is based on RAM, ROM, WORM, NVRAM or other form of memory storage.
DEVICE_MODEMThe device is a modem (capable of some form of dial-up and/or direct PC connectivity).
Result
ERR_Okay  The directory was created successfully.
ERR_Args  The Path, Info or InfoSize argument was missing.
ERR_Failed  A failure occurred during the directory creation.

Function:GetFileIcon()
Short:Analyses a file to determine the icon that should be used for graphical representation.
Synopsis:STRING GetFileIcon(STRING Location)
Arguments:
Location  The path of the file or directory that you want to analyse.

The GetFileIcon() function is used to determine the best icon to use when representing a file graphically. Icons derived from this function are commonly used when listing files so that the user has a visual indication of what the file represents.

The resulting string is returned in the format "icons:category/name" and can be opened via the Picture class. If you want to specify the size of icon, you will need to add the pixel size, in brackets, to the end of the icon string.

Result
A string referencing the icon is returned by this function. The string is an internal reference to the file system module, so it is only good up until the next time that you call the GetFileIcon() function. This function always succeeds because the icon "icons:filetypes/empty" is returned in the event that no suitable icon is discovered.


Function:GetFileInfo()
Short:Returns information for a specific file or directory location.
Synopsis:ERROR GetFileInfo(STRING Location, struct FileInfo *Info, LONG InfoSize)
Arguments:
Location  The path of the file or directory to analyse.
Info  Pointer to a FileInfo structure for holding the results.
InfoSize  The byte-size of the Info structure.

The GetFileInfo() function provides the means for obtaining basic information from files and directories. You are required to provide a FileInfo structure that will hold the results following successful analysis of the file. The following FileInfo fields are supported by this function:

TypeFieldDescription
STRING Name The name of the file. This string remains valid until the next call to GetFileInfo().
STRING * Tags A list of special tag strings that are file-specific.
LONG PermissionsStandard permission flags.
LARGE Size The size of the structure (note 64-bit quantity).
FileTime Time Time structure, consists of Year, Month, Day, Hour, Minute and Second information.
LARGE TimeStamp 64-bit time stamp - usable only for comparison (e.g. sorting).
LONG UserID User ID (Unix systems only)
LONG GroupID Group ID (Unix systems only)

Filename approximation is supported, so the Location string does not need to be an exact file reference.

Result
ERR_Okay  Success.
ERR_Args  Not all of the required arguments were specified.
ERR_FileNotFound  The specified Location does not exist.

Function:IdentifyFile()
Short:Used for associating data with object classes.
Synopsis:ERROR IdentifyFile(STRING Location, CLASSID *ClassID, CLASSID *SubClassID)
Arguments:
Location  The location of the object data.
ClassID  Must refer to a CLASSID variable that will store the resulting class ID.
SubClassID  Optional argument that can refer to a variable that will store the resulting sub-class ID (if the result is a base-class, this variable will be set to NULL).

This function is used for identifying the relationship between file data and the classes that have been installed on a system running the Pandora Engine. If for instance you want to know what class is capable of handling a data file located at "athene:pictures/screenshot.pcx" you can call the IdentifyFile() function and it will tell you that the data is supported by a member of the Picture class.

The function works by analysing the Location string's file extension and comparing it to the supported extensions of all available classes. If a class supports the file extension then the ID of that class will be returned. If the file extension is not understood, the function will load the first 80 bytes of the file's data and then check it against classes that can match against file header information. If a match is found, the ID of the matching class will be returned.

This function returns an error code of ERR_Search in the event that it cannot find a suitable match. In such cases it should be assumed that either the required class for the data is not installed, or the file consists of raw binary data that has no class representation.

Result
ERR_Okay  The data was successfully identified.
ERR_Args  Invalid arguments were specified.
ERR_Search  A suitable class could not be found for the data source.
ERR_NewObject  A File object could not be created.
ERR_Init  The internal File object could not be initialised (the Location argument may be invalid).
ERR_Read  Data could not be read from the Location.

Function:MakeDirectory()
Short:Makes new directories.
Synopsis:ERROR MakeDirectory(STRING Location, LONG Permissions)
Arguments:
Location  The location of the directory.
Permissions  Security permissions to apply to the created directory(s). Set to NULL if only the current user should have access.

This function creates new directories. You are required to specify the full path of the new directory. Standard permission flags can be passed to determine the new permissions to set against the newly created directory(s). If no permission flags are passed, only the current user will have access to the new directory (assuming that the file system supports security settings on the given media). This function will create multiple directories if the complete path does not exist at the time of the call.

Result
ERR_Okay  The directory was created successfully.
ERR_Args  The Location argument was not specified.
ERR_FileExists  The directory already exists.
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 also be used for renaming purposes and is able to move data from one type of media to another. 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 moving 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', according to the system hosting the Pandora Engine. For instance, on a Linux system a 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.

When checking for the location of a file, ResolveAssign() will only accept an exact filename match. If you know or suspect that the filename is an approximation (i.e. no extension is set at the end of your Assign string) then use the RSF_APPROXIMATE flag to tell the function to accept matches to filenames with extensions.

You are required to supply a STRING variable in the Result argument so that the resolved path can be returned. 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_FileNotFound  The path was resolved, but the referenced file or directory does not exist (use RSF_NOFILECHECK if you need to avoid this error code).
ERR_Loop  The assignment refers back to itself.

Function:SaveObjectToFile()
Short:Saves an object to a destination file.
Synopsis:ERROR SaveObjectToFile(OBJECTPTR Object, STRING Location, LONG Permissions)
Arguments:
Object  Pointer to the object that you want to save.
Location  The destination file location.
Permissions  File permissions to use (optional). If NULL, file is saved with user and group permissions of read/write.

This function simplifies the process of saving objects to files. You need to provide the object address and the destination file location for the data to be saved. The destination file exists, it will be overwritten.

The object's class must support the SaveToObject action or this function will return ERR_NoSupport.

Result
ERR_Okay  The assignment was sucessfully added.
ERR_Args  A valid Location argument was not provided.
ERR_CreateObject  Failed to create the file at the indicated destination.
ERR_NoSupport  The object does not support the SaveToObject action.

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

The SetAssign() function is used to set one or more paths against an assignment name. It can preserve any existing paths that are attributed to the assignment if the assign name already exists. If the assignment does not already exist, a new one will be created from scratch.

This function uses tags to create new assignments. The following table lists all tags that are accepted by this function. Remember to terminate your taglist with TAGEND.

TagDescription
AST_NAMERequired. Follow this tag with a string that specifies the name of the assign that you would like to set.
AST_PATHRequired. Follow this tag with the path to be set against the assign. If setting multiple paths, separate each path with a semi-colon character. Each path must terminate with a forward slash to denote a directory.
AST_ICONYou may set an icon to be associated with the assign, so that it has graphical representation when viewed in a file viewer for example. The required icon string format is "category/name".
AST_COMMENTA user comment string may be set against the assign with this tag.
AST_FLAGSOptional flags. See below for more details.

Flags that may be passed with the AST_FLAGS tag are as follows:

FlagsDescription
ASSIGN_REPLACEIf the assignment already exists, all paths that are attached to it will be replaced with your new path setting.
ASSIGN_PRIORITYIf the assignment already exists, your path will be inserted at the beginning of the path list so that it has priority over the others.
ASSIGN_HIDDENHides the assignment so that it will not show up when reading the root directory.
ASSIGN_SAVEThe assign will be saved to user:config/assignments.cfg if you set this flag. This allows the assign to be automatically restored on the next reboot.
Result
ERR_Okay  The assignment was sucessfully added.
ERR_Args  A valid name and path string was not provided.
ERR_AccessObject  Access to the SystemAssignments shared object was denied.
ERR_AllocMemory  Failed during the allocation of a new memory block.