Section contents
cfile.oxh
Before any operations with the file server can be performed, a session must be opened. This is done by connecting the client process to the file server. The Fs class represents a session with the file server. Note that for the majority of functions described in this chapter, when a file or directory name is passed as an argument to the function, if no drive letter or directory is specified, the missing path component will be taken from the session path.
This class represents a session with the file server. A program, or thread, may have arbitrarily many sessions open simultaneously.
Use this class for all file system manipulation, including
These include when the file or directory was last written, its size, and various file attribute flags such as read-only, hidden, archive or system.
This can be used for programs which maintain file lists, but must update those lists when change occurs.
When using the functions provided by this class, whenever a path is specified, the following restrictions apply to it and to its components:
<
>
"
/
|
this& = NewFs&:
Creates a file server object and returns a handle which allows the object to be manipulated.
this& |
An value which represents the created file server |
If the object could not be created then an error is generated
which should be trapped by an ONERR
handler.
LOCAL this& this& = NewFs&: DeleteFs:(this&)
DeleteFs:(BYREF this&)
Destroys the file server object.
BYREF this& |
A handle to a size object |
LOCAL this& this& = NewSize&:(50,50) DeleteSize:(this&)
err% = FsAaddFileSystem%:(this&,name$)
Use this function to add a file system to the file server. After calling this function, use FsMountFileSystem to mount the file system on a drive.
this& |
A handle to a file server object |
name$ |
The name of the file system .FSY to
install. |
err% |
An error code |
err% = FsAtt%:(this&,name$,BYREF attributes&)
Gets the file attributes.
this& |
A handle to a file server object |
name$ |
Name of file |
BYREF attributes& |
The file attributes |
err% |
An error code |
err% = FsCheckDisk%:(this&,drive$)
Use this function to check the integrity of the disk contained in drive$.
this& |
A handle to a file server object |
drive$ |
Path indicating the drive which contains the disk to check |
err% |
An error code. If the drive specified is empty, returns K32ErrNotReady&. Any other value except K32ErrNone& indicates that the disk is corrupt. |
FsConnect:(this&)
Closes a connection to the file server.
this& |
A handle to a file server object |
err% = FsConnect%:(this&,slots&)
Establishes a connection to the file server.
this& |
A handle to a file server object |
slots& |
The number of message slots |
err% |
An error code |
The number of message slots represents the number of operations that can be outstanding at once. The default value four slots allows an asynchronous read, write, and another operation to be outstanding at the same time, and a spare slot for a cancel.
If you wish to have more asynchronous operations outstanding than this, use more message slots. You should always provide an extra slot for the cancel operation.
Often, specification of extra slots is not required because several file server objects are used in a program, each carrying its own message slots.
err% = FsDefaultPath%:(this&,des&)
Use this function to get the system default path. This path is assigned as the session path to new clients when they connect to the file server. There is a single system default path rather than one for each drive.
this& |
A handle to a file server object |
des& |
A descriptor which on return, contains the system default path, including a trailing backslash |
err% |
An error code |
err% = FsDelete%:(this&,name$)
Deletes the file specified by name$
..
this& |
A handle to a file server object |
name$ |
The name of the file to delete |
err% |
An error code |
err% = FsDrive%:(this&,info&,drive&)
Use this function to get information about a drive and the medium mounted on it.
this& |
A handle to a file server object |
info& |
On return, contains information describing drive drive|& and the medium mounted on it. The value of the DriveInfoMediaType function shows whether the drive contains media. |
drive& |
The drive for which information is requested. Specify KDefaultDrive& for the session default drive; specify a drive in range KDriveA& to KDriveZ& for drives A to Z. |
err% |
An error code |
FsVolume may also be used, to give information about the drive and the volume mounted in it. These functions are separate because, while the characteristics of a drive cannot be changed, those of a volume can be changed by mounting different media, reformatting etc.
err% = FsDriveList%:(this&,list&)
Get the list of valid drives.
this& |
A handle to a file server object |
list& |
A drive list |
err% |
An error code |
err% = FsGetDir%:(this&,name$,mask&,sortKey&,BYREF
list&)
Use this function to get a filtered list of a directorys contents. The bitmask determines which file and directory entry types should be listed. The sort key determines the order in which they are listed.
this& |
A handle to a file server object |
name$ |
Name of the directory for which a listing is required. Wildcards may be used to specify particular files. |
mask& |
Bitmask of file or directory attributes |
sortKey& |
Order of directory entries |
BYREF list& |
On return contains a list of directory and file entries |
err% |
An error code |
err% = FsGetDirId%:(this&,name$,uid&,sortKey&,BYREF
list&)
Use this function to get a filtered list of a directorys contents. The uid& parameter determines which file entry types should be listed. The sort key determines the order in which they are listed.
this& |
A handle to a file server object |
name$ |
Name of the directory for which a listing is required. Wildcards may be used to specify particular files. |
uid& |
Only those files whose UIDs match those specified here will be included in the file list. Any or all of the three UIDs may be omitted. Any UID which is omitted will act in a similar manner to a wildcard character, matching to all UIDs. |
sortKey& |
Order of directory entries |
BYREF list& |
On return contains a list of directory and file entries |
err% |
An error code |
err% = FsGetDirSeperate%:(this&,name$,mask&,sortKey&,BYREF
list&,BYREF dirlist&)
Use this function to get a filtered list of a directorys contents. The bitmask determines which file and directory entry types should be listed. The sort key determines the order in which they are listed.
this& |
A handle to a file server object |
name$ |
Name of the directory for which a listing is required. Wildcards may be used to specify particular files. |
mask& |
Bitmask of file or directory attributes |
sortKey& |
Order of directory entries |
BYREF list& |
On return contains a filtered list of directory and file entries |
BYREF dirlist& |
On return contains a list of directory entries only. |
err% |
An error code |
err% = FsGetDriveName%:(this&,drive&,des&)
Get the name associated with the specified drive.
this& |
A handle to a file server object |
drive& |
Drive number. Specify KDefaultDrive& for the session default drive; specify a drive in the range KDriveA& to KDriveZ& for drives A to Z. |
des& |
A descriptor for the drive name |
err% |
An error code |
err% = FsGetLongName%:(this&,name$,des&)
Use this function to get the long filename associated with a short (8.3) filename. A long filename has a limit of 256 characters for each component, a well as a limit of 256 characters for the entire path.
this& |
A handle to a file server object |
name$ |
The short file name. Any path components which are not specified here will be taken from the session path. If path specifies a directory, may or may not be followed by a trailing backslash. |
des& |
A descriptor which on return, contains the long version of filename name$. |
err% |
An error code |
bool% = FsIsFileOpen%:(this&,name$,BYREF answer%)
Use this function to get whether a file is open. This function is useful because several file based operations provided by the file server class, for instance FsDelete, FsRename and FsReplace depend for their success on the file being closed.
this& |
A handle to a file server object |
name$ |
Name of the file to test. Any path components which are not specified here will be taken from the session path. |
BYREF answer% |
Returns true if the file is open,false if closed. |
err% |
An error code |
bool% = FsIsDriveValid%:(drive&)
Use this function to get whether a drive number is valid. A valid drive number is any number between 0 and 25 inclusive.
drive& |
Drive number. Specify KDefaultDrive& for the session default drive |
bool% |
True if the drive specified is between KDriveA& and KDriveZ& inclusive; false if not |
err% = FsMkDir%:(this&,name$)
Create a directory.
this& |
A handle to a file server object |
name$ |
The name of the directory to create |
err% |
An error code |
err% = FsMkDirAll%:(this&,name$)
Create all the directories in the path specified in name$
.
this& |
A handle to a file server object |
name$ |
The pathname of the directories to create |
err% |
An error code |
err% = FsMkDirAll%:(this&,name$,time&)
Use this function to get the date and time the contents of a file or directory were last modified, or if there has been no modification, the date and time of the file or directory's creation.
this& |
A handle to a file server object |
name$ |
File or directory name |
time& |
A handle to a time object which on return, contains the date and time of the file or directorys latest modification |
err% |
An error code |
err% = FsMountFileSystem%:(this&,name$,drive&)
Use this function to mount a file system on a drive. The file system must first have been added to the file server, using FsAddFileSystem.
this& |
A handle to a file server object |
name$ |
The filename of the file system to be mounted |
drive& |
Drive on which the file system is to be mounted. KDriveA& to KDriveZ& |
err% |
An error code |
FsNotifyChange:(this&,type&,BYREF status&)
Use this function to request a notification of change either following any change in the file system at all or only following the addition or deletion of a directory entry or after a disk has been formatted or changed.
Such notification is useful for programs that maintain displays of file lists which must be dynamically updated. The alternative would be either no updating at all or periodic monitoring for change which would be wasteful.
This call is an asynchronous request and, as such, results in precisely one signal to the request status passed as a parameter. In order to avoid missing any change, this request should be issued before the first file list is constructed: when the request completes, a new request should be issued before the next file list is constructed. When the file server session is closed, this request is implicitly cancelled: otherwise, FsNotifyChangeCancel can be used to explicitly cancel it.
this& |
A handle to a file server object |
type& |
Indicates what kind of change should result in notification. KNotifyEntry& causes notification only when an entry is added or deleted or when a disk is formatted or changed. KNotifyAll& causes notification following any type of change, for instance when a file is written to, or when a file's attributes are changed. |
BYREF status& |
If the status&
object cannot be created then
an error is generated which should be trapped by an ONERR
handler.
FsNotifyChangeCancel:(this&)
Use this function to cancel a requested change notification.
this& |
A handle to a file server object |
err% = FsParse%:(this&,name$,related$,parse&)
Use these functions to begin parsing a filename using the session path as the default directory.
Parsing is done with wildcard resolution, using the session path as the default. You may then use Parses getter functions to extract individual components of the resulting name. All the path components which are included in name$ are put into the resulting filename; then, any missing components are taken from the optional related$ argument, which has next order of precedence; finally, any components still missing are taken from the session path. See class Parse for more information on parsing file specifications.
this& |
A handle to a file server object |
name$ |
The file name to be parsed, using the session path and the related path to provide the missing components. |
releated$ |
If specified, the related file specification |
parse& |
Instance of Parse, providing functions for extracting individual components of the resulting file name. |
err% |
An error code |
err% = FsRealName%:(this&,name$,des&)
Use this function to get the real name of a file, in circumstances where a file system mangles EPOC32 natural names, in order to be able to store them on a file system which is not entirely compatible, or, if a substituted drive is specified in name$.
this& |
A handle to a file server object |
name$ |
Contains the name by which the file is normally referred to |
des& |
A handle to a descriptor object which on return, contains the real name of the file, comprising the full path, including the drive letter. |
err% |
An error code |
err% = FsRemoveFileSystem%:(this&,name$)
Use this function to remove a file system from the file server.
this& |
A handle to a file server object |
name$ |
The filename of the file system to be removed |
err% |
An error code |
err% = FsRename%:(this&,oldName$,newName$)
Renames the file or directory oldName$
to newname$
..
this& |
A handle to a file server object |
oldName$ |
The old name of the file or directory |
newName$ |
The new name of the file or directory |
err% |
An error code |
err% = FsReplace%:(this&,oldName$,newName$)
Replace the file oldName$
with the file newName$
.
this& |
A handle to a file server object |
oldName$ |
The old name of the file or directory |
newName$ |
The new name of the file or directory |
err% |
An error code |
count& = FsResourceCount&:(this&)
Use this function to get the number of resources currently open. The resource count is incremented by one each time a file or directory is opened, when a device is opened in preparation for formatting, or when a direct access channel to a disk is opened.
this& |
A handle to a file server object |
count& |
The number of resources currently open |
FsResourceCountMarkEnd:(this&)
Use this function to end resource count checking. A panic will occur if the number of resources opened since the start of resource count checking is not equal to the number of resources closed. Typically, this function should be called immediately before closing a session with the file server.
this& |
A handle to a file server object |
FsResourceCountMarkStart:(this&)
Use this function to begin resource count checking. Typically, this function should be called immediately after a client process is connected to the file server, and before any resources are opened.
this& |
A handle to a file server object |
err% = FsRmDir%:(this&,name$)
Deletes the directory specified in name$
.
this& |
A handle to a file server object |
name$ |
The name of the directory to delete |
err% |
An error code |
err% = FsSessionPath%:(this&,des&)
Use this function to get the session path. When a client connects to the file server, its session path is initialized to the system default path. The session path of an existing client can only be changed by FsSetSessionPath().
this& |
A handle to a file server object |
des& |
A descriptor which on return, contains the session path, including a trailing backslash |
err% |
An error code |
err% = FsSetAtt%:(this&,name$,set&,clear&)
Sets the file attributes set&
and clears the
file file attributes clear&
on the file name$,.
this& |
A handle to a file server object |
set& |
The attributes to set |
clear& |
The attributes to clear |
err% |
An error code |
err% = FsSetDefaultPath%:(this&,name$)
Use this function to set the system default path. This path is assigned as the session path to new clients when they connect to the file server. The session paths of existing clients remain unchanged. There is a single system default path rather than one for each drive.
this& |
A handle to a file server object |
name$ |
The new system default path. Consists of a drive and path. Normally, a drive should be specified, but if not, the system default drive is set to the drive specified in the existing session path. If a file is specified in the path, the function fails and returns an error. Therefore, the final component in the path must have a trailing backslash to indicate that it is a directory. All components of the path must be syntactically correct, for example wildcard characters and double backslashes are not allowed in any part of it. |
err% |
An error code |
err% = FsSetDriveName%:(this&,drive&,name$)
Use this function to set the name of a drive. Drive naming is optional. Any drive may be assigned a name and more than one drive may share the same name.
this& |
A handle to a file server object |
drive& |
Drive number. Specify KDefaultDrive& for the session default drive; specify a drive in the range KDriveA& to KDriveZ& for drives A to Z. |
name$ |
The name of the drive. |
err% |
An error code |
err% = FsSetModified%:(this&,name$,time&)
Use this function to set the date and time the contents of a file or directory were last modified. If the file is open the operation will fail, returning K32ErrInUse&.
this& |
A handle to a file server object |
name$ |
File or directory name |
time& |
The new date and time of the file or directory's latest modification |
err% |
An error code |
FsSetNotifyUser%:(this&,bool%)
Use this function to set whether the user should be notified of file read or write failure.
this& |
A handle to a file server object |
bool% |
True if user is to be notified of read or write failures, false for no notification |
err% = FsSetSessionPath%:(this&,name$)
Use this function to set the session path for the current file server client. When the client first connects to the file server, its session path is initialized to the system default path.
this& |
A handle to a file server object |
name$ |
The new session path. Consists of a drive and path. Normally, a drive should be specified, but if not, the drive specified in the existing session path is preserved. If a file is specified, the function fails and returns an error code. Therefore, the final component in the path must have a trailing backslash to indicate that it is a directory. All components of the path must be syntactically correct, for example wildcard characters and double backslashes are not allowed in any part of it. |
err% |
An error code |
err% = FsSetSubst%:(this&,name$,drive&)
Use this function to assign a path to a drive letter. Whenever that drive letter is used, it will be translated into a reference to the path specified here. To clear a drive substitution, specify an empty descriptor for name$.
this& |
A handle to a file server object |
name$ |
The path to be assigned to the drive letter. If a
drive letter is specified in the path, it must not itself
be substituted or redirected, or the function will return
an error. If no drive is specified, the drive contained
in the default session path is used, and if no path is
specified, the default session path is used. If a filename or extension is included in the path, the function will return an error. Therefore, the final component in the path must have a trailing backslash to indicate that it is a directory. |
drive& |
The drive to which a path is to be assigned. Specify a number in the range 0 (KDriveA&) to 25 (KDriveZ&) for drives A to Z. Must not be local, ROM, or redirected, or an error is returned. May be substituted, but only if the function is being used to clear the substitution. If the same drive is specified in the path, the function will return an error. |
err% |
An error code |
err% = FsSetVolumeLabel%:(this&,name$,drive&)
Use this function to set the label for a volume.
this& |
A handle to a file server object |
name$ |
The volume label |
drive& |
The drive containing the media whose label is to be
set. Specify KDefaultDrive&
for the session default drive; specify a drive in the
range KDriveA& to KDriveZ& for
drives A to Z . |
err% |
An error code K32ErrNotReady& if the drive contains no media. |
err% = FsSubst%:(this&,des&,drive&)
Use this function to get the path assigned to a drive letter by FsSetSubst.
this& |
A handle to a file server object |
des& |
A handle to a descriptor object which on return, contains the path which has been assigned to the drive. If the drive letter has not been substituted, this argument returns an empty descriptor. |
drive& |
The drive containing the media whose label is to be
set. Specify KDefaultDrive&
for the session default drive; specify a drive in the
range KDriveA& to KDriveZ& for
drives A to Z . |
err% |
An error code K32ErrNotReady& if the drive contains no media. |
err% = FsVolume%:(this&,info&,drive&)
Use this function to get volume information for a formatted device. This function provides additional information to that given by FsDrive, including the volume label, if set, and the amount of free space on the disk.
this& |
A handle to a file server object |
info& |
A handle to a volume information object which on return, contains the volume information. |
drive& |
The drive which contains the media for which you want
to display volume information. Specify KDefaultDrive&
for the session default drive; specify a drive in the
range KDriveA& to KDriveZ& for
drives A to Z . |
err% |
An error code |