FileSystem

Version:1.1
Status:Stable
Date:April 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).
CloseDirectory  Closes a directory handle.
CopyLocation  Makes copies of directories and files.
CreateLink  Creates symbolic links on Unix file systems.
DeleteAssign  Deletes directory assignments from the system.
DeleteFile  Deletes files and directories.
FileCaseSensitive  Enables case sensitivity for certain file functions.
FileFeedback  Enables continual feedback when performing lengthy file operations.
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.
OpenDirectory  Opens a directory for content scanning.
ReadDirectory  Reads the contents of a directory in the file system.
ResolveAssign  Resolves assign strings into absolute paths.
SaveObjectToFile  Saves an object to a destination file.
ScanDirectory  Scans the content of a directory, by item.
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:CloseDirectory()
Short:Closes a directory handle.
Synopsis:void CloseDirectory(struct DirInfo *Info)
Arguments:
Info  The directory info structure to be closed.

This function closes a directory that has been opened with the OpenDirectory() function.


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:CreateLink()
Short:Creates symbolic links on Unix file systems.
Synopsis:ERROR CreateLink(STRING From, STRING To)
Arguments:
From  The symbolic link will be created at the location specified here.
To  The file that you are linking to is specified here.

Use the CreateLink() function to create symbolic links on Unix file systems. The link connects a new file created at From to an existing file referenced at To. The To link is allowed to be relative to the From location - for instance, you can link "documents:myfiles/newlink.txt" to "../readme.txt" or "folder/readme.txt". The ".." path component must be used when making references to parent directories.

The permission flags for the link are inherited from the file that you are linking to. If the file location referenced at From already exists as a file or directory, the function will fail with an ERR_FileExists error code.

This function does not automatically create directories in circumstances where new folders are required to complete the From link. You will need to call MakeDirectory() to ensure that the necessary paths exist beforehand. If the file referenced at To does not exist, the link will be created without error, but any attempts to open the link will fail until the target file or directory exists.

Result
ERR_Okay  The link was created successfully.
ERR_Args  Invalid arguments were specified.
ERR_NoSupport  The file system or the host operating system does not support symbolic links.
ERR_NoPermission  The user does not have permission to create the link, or the file system is mounted read-only.
ERR_ResolveAssign  Path resolution error.
ERR_LowCapacity  There is no room on the device to create the new link.
ERR_Memory  Not enough memory was available to perform the operation.
ERR_BufferOverflow  One or both of the provided arguments is too long.
ERR_FileExists  The location referenced at From already exists.

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.

This function does not allow filename approximation.

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 internal filename comparisons 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:FileFeedback()
Short:Enables continual feedback when performing lengthy file operations.
Synopsis:LONG FileFeedback(APTR Routine, APTR Data, LONG Flags)
Arguments:
Routine  Pointer to a routine that will receive feedback from the file system.
Data  Private user data to be returned in the User field of the FileFeedback structure.
Flags  Optional flags, currently zero.

The FileFeedback() function is used to receive feedback from the file system when performing lengthy file operations. Feedback is currently supported for delete, move and copy operations, specifically: DeleteFile(), MoveLocation(), CopyLocation() and equivalent methods in the File class.

The prototype for the Routine is as follows:

   LONG Feedback(struct FileFeedback *)

When receiving feedback, you can read the FileFeedback structure for progress information. The arrangement of the structure is as follows:

FieldDescription
LONG FeedbackIDEither FDB_MoveFile, FDB_DeleteFile or FDB_CopyFile.
STRING LocationThe complete path of the file being processed.
STRING DestinationThe destination for the file, if applicable.
LARGE SizeThe size of the file.
LARGE PositionThe position within the file when copying or moving.
APTR UserIf you set the Data argument when calling FileFeedback(), the User field will reflect the data value that you specified.

Your routine is required to return an integer that you can use to affect file processing. These values are FFR_Okay (do nothing), FFR_Skip (don't do anything further with the current file) and FFR_Abort (abort the file process completely and return ERR_Cancelled as an error code).

Setting the file feedback routine is not permanent - it is only good for the next filesystem call that you make. Thus you will need to call this routine prior to any situation where you need feedback from the file system.

Result
ERR_Okay  Feedback routine set successfully.
ERR_Args  The Routine argument was not set.

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:OpenDirectory()
Short:Opens a directory for content scanning.
Synopsis:ERROR OpenDirectory(STRING Location, LONG Flags, struct DirInfo **Info)
Arguments:
Location  The directory location to be scanned.
Flags  Optional flags.
Handle  The resulting directory handle will be returned in the variable referred to here.

The OpenDirectory() function is used to open a directory for scanning via the ScanDirectory() function. You are required to specify the path of the directory that you want to scan, as well as options that affect the scan process. A DirInfo structure will be returned in the Info parameter, which you will need to pass to ScanDirectory(). Once you have completed the scanning process, you will need to call the CloseDirectory() function.

When opening a directory, you need to indicate the type of files you are interested in scanning for. If you do not set any flags, the scan process will return file and directory names only. The following table lists all supported flags:

FlagDescription
RDF_SIZE Retrieve the byte size of each file.
RDF_DATE Retrieve the date stamp from each file.
RDF_PERMISSIONSRetrieve file permissions and the user/group ID.
RDF_FILE List known files in the directory.
RDF_DIRECTORY List known folders and assignments in the directory.
RDF_TAGS Receive additional information for each file, such as comments, author and copyright. The results are stored in the Tags array for each file, using the string format 'TAGNAME:Description' for each entry.
Result
ERR_Okay  The directory was opened successfully.
ERR_Args  The Location or Handle arguments were not specified.
ERR_DirectoryEmpty  The directory that you want to scan is empty.
ERR_AllocMemory  Memory for the directory handle could not be allocated.

Function:ReadDirectory()
Short:Reads the contents of a directory in the file system.
Synopsis:ERROR ReadDirectory(STRING Location, LONG Flags, struct FileInfo **Array)
Arguments:
Location  The path that you want to read.
Flags  Flags indicating the information that you want.
Array  Must refer to an empty pointer that will receive the resulting array.

The ReadDirectory() function is used to read directory content (files and folders) according to your requirements. The resulting information is provided in a convenient array that can be scanned for file names, sizes, permissions and date stamps. The list can be automatically sorted for your convenience.

This function will return an allocated array that you will need to free via FreeMemory() once you are finished with it. The following table describes the structure of each entry in the array:

TypeFieldDescription
*FileInfoNext Pointer to the next file entry in the list.
STRING Name The name of the file or directory.
STRING * Tags A list of special tag strings that are file-specific.
LONG Flags Refer to the flags section for further information.
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)

When calling the ReadDirectory() function you can specify a number of flags that affect the function's behaviour. Certain flags are essential for receiving optional information, such as the date and file permissions. Some of these flags are also set in the Flags field of the FileInfo entries for informative purposes. The following table indicates the available flag options.

FlagDescription
RDF_ASSIGN For the file list structure only. Indicates an assignment.
RDF_DIRECTORY List known folders in the directory. Also used to indicate folders in the file list.
RDF_DATE Retrieve the date and time stamp on each file.
RDF_FILE List known files in the directory. Also used to indicate files in the file list.
RDF_LINK Used in the FileList structure only. Indicates that the file or directory is actually a symbolic link.
RDF_PERMISSIONS Retrieve file permissions and the user/group ID.
RDF_QUALIFY Tells the function to produce fully qualified directory names (i.e. trailing slash or colon for each name).
RDF_SIZE Retrieve the byte size of each file.
RDF_SORT Sorts the results by name (ascending)
RDF_TAGS Receive additional information for each file, such as comments, author and copyright. The results are stored in the Tags array for each file, using the string format 'TAGNAME:Description' for each entry.

The correct way to scan the resulting file list is to trawl the Next field pointers until you run out of entries. Do not, under any circumstance, use indexes to scan the array. The following example illustrates the correct way to scan the list:

   if (ReadDirectory("athene:", NULL, &fileinfo) IS ERR_Okay) {
      for (list=fileinfo; list; list=list->Next) {
         ...
      }
   }

To retrieve a list of assignments (shortcuts) at the root level, use a Location string of ":".

Result
ERR_Okay  Information was found in the directory and can be scanned from the resulting array.
ERR_DirectoryEmpty  No information was found in the directory that matched your parameters.
ERR_Args  Invalid arguments were specified.

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:ScanDirectory()
Short:Scans the content of a directory, by item.
Synopsis:ERROR ScanDirectory(struct DirInfo *Info)
Arguments:
Info  Pointer to a DirInfo structure for storing scan results.

The ScanDirectory() function is used to scan for files and folders in a directory that you have opened using the OpenDirectory() function. The ScanDirectory() function is intended to be used in a simple loop, returning a single item for each function call that you make. The following code sample illustrates typical usage:

   struct DirInfo *info;

   if (OpenDirectory(location, RDF_FILE|RDF_DIRECTORY, &info) IS ERR_Okay) {
      while (ScanDirectory(info) IS ERR_Okay) {
         DPrintF("File:","%s", info->Name);
      }
      CloseDirectory(info);
   }

For each item that you scan, you will be able to read the Info structure for information on that item. The Info structure consists of the following fields (any field that requires a retrieval flag is marked in brackets):

TypeFieldDescription
STRING Name The name of the file or directory.
STRING * Tags A list of special tag strings that are file-specific (RDF_TAGS).
LONG Flags Refer to the flags section for further information.
LONG PermissionsStandard permission flags (RDF_PERMISSIONS).
LARGE Size The size of the structure (note 64-bit quantity) (RDF_SIZE).
FileTime Time Time structure, consists of Year, Month, Day, Hour, Minute and Second information (RDF_DATE).
LARGE TimeStamp 64-bit time stamp - usable only for comparison (e.g. sorting) (RDF_DATE).
LONG UserID User ID (Unix systems only) (RDF_PERMISSIONS)
LONG GroupID Group ID (Unix systems only) (RDF_PERMISSIONS)

Flags that may be returned in the Info structure's Flags field are as follows:

FlagDescription
RDF_ASSIGN Indicates that the item is a directory assignment.
RDF_DIRECTORYThe item is a directory.
RDF_FILE The item is a file.
RDF_LINK The item is a symbolic link (used in accompanient with RDF_DIRECTORY and RDF_FILE).
Result
ERR_Okay  An item was successfully scanned from the directory.
ERR_Args  One or more of the required arguments were not supplied.
ERR_DirectoryEmpty  There are no more items to scan.

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.
AST_LABELAn optional label or short comment may be applied to the assignment. This may be useful if the assignment name has little meaning to the user (e.g. drive1, drive2 ...).

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.