File server


Section contents


Overview

Defined in

cfile.oxh

Description

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

Illegal paths

When using the functions provided by this class, whenever a path is specified, the following restrictions apply to it and to its components: —


Construction / destruction


NewFs - Constructor

Usage

this& = NewFs&:

Description

Creates a file server object and returns a handle which allows the object to be manipulated.

Return Value
this& An value which represents the created file server
Error Handling

If the object could not be created then an error is generated which should be trapped by an ONERR handler.

Example
  LOCAL this&

  this& = NewFs&:
  DeleteFs:(this&) 

DeleteFs - Destructor

Usage

DeleteFs:(BYREF this&)

Description

Destroys the file server object.

Arguments
BYREF this& A handle to a size object
Example
  LOCAL this&

  this& = NewSize&:(50,50)
  DeleteSize:(this&) 

Methods provided


FsAddFileSystem - add a file system

Usage

err% = FsAaddFileSystem%:(this&,name$)

Description

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.

Arguments
this& A handle to a file server object
name$ The name of the file system .FSY to install.
Return value
err% An error code

FsAtt - get file attributes

Usage

err% = FsAtt%:(this&,name$,BYREF attributes&)

Description

Gets the file attributes.

Arguments
this& A handle to a file server object
name$ Name of file
BYREF attributes& The file attributes
Return value
err% An error code
See also

FsSetAtt


FsCheckDisk - check disk for errors

Usage

err% = FsCheckDisk%:(this&,drive$)

Description

Use this function to check the integrity of the disk contained in drive$.

Arguments
this& A handle to a file server object
drive$ Path indicating the drive which contains the disk to check
Return value
err% An error code. If the drive specified is empty, returns K32ErrNotReady&. Any other value except K32ErrNone& indicates that the disk is corrupt.

FsClose - close connection to file server

Usage

FsConnect:(this&)

Description

Closes a connection to the file server.

Arguments
this& A handle to a file server object

FsConnect - connect to file server

Usage

err% = FsConnect%:(this&,slots&)

Description

Establishes a connection to the file server.

Arguments
this& A handle to a file server object
slots& The number of message slots
Return value
err% An error code
Notes

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.

See Also

FsClose


FsDefaultPath - get system default path

Usage

err% = FsDefaultPath%:(this&,des&)

Description

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.

Arguments
this& A handle to a file server object
des& A descriptor which on return, contains the system default path, including a trailing backslash
Return value
err% An error code

FsDelete - delete a file

Usage

err% = FsDelete%:(this&,name$)

Description

Deletes the file specified by name$..

Arguments
this& A handle to a file server object
name$ The name of the file to delete
Return value
err% An error code

FsDrive - get drive information

Usage

err% = FsDrive%:(this&,info&,drive&)

Description

Use this function to get information about a drive and the medium mounted on it.

Arguments
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.
Return value
err% An error code
Notes

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.


FsDriveList - get list of valid drives

Usage

err% = FsDriveList%:(this&,list&)

Description

Get the list of valid drives.

Arguments
this& A handle to a file server object
list& A drive list
Return value
err% An error code

FsGetDir - get list of directory entries

Usage

err% = FsGetDir%:(this&,name$,mask&,sortKey&,BYREF list&)

Description

Use this function to get a filtered list of a directory’s contents. The bitmask determines which file and directory entry types should be listed. The sort key determines the order in which they are listed.

Arguments
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
Return value
err% An error code

FsGetDirById - get list of files by UID type

Usage

err% = FsGetDirId%:(this&,name$,uid&,sortKey&,BYREF list&)

Description

Use this function to get a filtered list of a directory’s contents. The uid& parameter determines which file entry types should be listed. The sort key determines the order in which they are listed.

Arguments
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
Return value
err% An error code

FsGetDirSeperate - get seperate directory entry list

Usage

err% = FsGetDirSeperate%:(this&,name$,mask&,sortKey&,BYREF list&,BYREF dirlist&)

Description

Use this function to get a filtered list of a directory’s contents. The bitmask determines which file and directory entry types should be listed. The sort key determines the order in which they are listed.

Arguments
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.
Return value
err% An error code

FsGetDriveName - get drive name

Usage

err% = FsGetDriveName%:(this&,drive&,des&)

Description

Get the name associated with the specified drive.

Arguments
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
Return value
err% An error code

FsGetLongName - get long file name

Usage

err% = FsGetLongName%:(this&,name$,des&)

Description

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.

Arguments
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$.
Return value
err% An error code

FsIsFileOpen - get whether file open

Usage

bool% = FsIsFileOpen%:(this&,name$,BYREF answer%)

Description

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.

Arguments
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.
Return value
err% An error code

FsIsValidDrive - get whether drive valid

Usage

bool% = FsIsDriveValid%:(drive&)

Description

Use this function to get whether a drive number is valid. A valid drive number is any number between 0 and 25 inclusive.

Arguments
drive& Drive number. Specify KDefaultDrive& for the session default drive
Return value
bool% True if the drive specified is between KDriveA& and KDriveZ& inclusive; false if not

FsMkDir - create a directory

Usage

err% = FsMkDir%:(this&,name$)

Description

Create a directory.

Arguments
this& A handle to a file server object
name$ The name of the directory to create
Return value
err% An error code
See also

FsMkDirAll, FsRmDir


FsMkDirAll - create directories in path

Usage

err% = FsMkDirAll%:(this&,name$)

Description

Create all the directories in the path specified in name$.

Arguments
this& A handle to a file server object
name$ The pathname of the directories to create
Return value
err% An error code
See also

FsMkDir, FsRmDir


FsModified - get modified date and time

Usage

err% = FsMkDirAll%:(this&,name$,time&)

Description

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.

Arguments
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 directory’s latest modification
Return value
err% An error code

FsMountFileSystem - mount a file system

Usage

err% = FsMountFileSystem%:(this&,name$,drive&)

Description

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.

Arguments
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&
Return value
err% An error code

FsNotifyChangeA - request change notification

Usage

FsNotifyChange:(this&,type&,BYREF status&)

Description

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.

Arguments
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&  
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.


FsNotifyChangeCancel - cancel change notification

Usage

FsNotifyChangeCancel:(this&)

Description

Use this function to cancel a requested change notification.

Arguments
this& A handle to a file server object

FsParse - parse a file specification

Usage

err% = FsParse%:(this&,name$,related$,parse&)

Description

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 Parse’s 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.

Arguments
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.
Return value
err% An error code

FsRealName - get real name

Usage

err% = FsRealName%:(this&,name$,des&)

Description

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$.

Arguments
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.
Return value
err% An error code

FsRemoveFileSystem - remove a file system

Usage

err% = FsRemoveFileSystem%:(this&,name$)

Description

Use this function to remove a file system from the file server.

Arguments
this& A handle to a file server object
name$ The filename of the file system to be removed
Return value
err% An error code

FsRename - rename a file or directory

Usage

err% = FsRename%:(this&,oldName$,newName$)

Description

Renames the file or directory oldName$ to newname$..

Arguments
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
Return value
err% An error code
See also

FsReplace


FsReplace - replace a file

Usage

err% = FsReplace%:(this&,oldName$,newName$)

Description

Replace the file oldName$ with the file newName$.

Arguments
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
Return value
err% An error code
See also

FsRename


FsResourceCount - get current resource count

Usage

count& = FsResourceCount&:(this&)

Description

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.

Arguments
this& A handle to a file server object
Return value
count& The number of resources currently open

FsResourceCountMarkEnd - end resource counting

Usage

FsResourceCountMarkEnd:(this&)

Description

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.

Arguments
this& A handle to a file server object

FsResourceCountMarkStart - start resource counting

Usage

FsResourceCountMarkStart:(this&)

Description

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.

Arguments
this& A handle to a file server object

FsRmDir - delete a directory

Usage

err% = FsRmDir%:(this&,name$)

Description

Deletes the directory specified in name$.

Arguments
this& A handle to a file server object
name$ The name of the directory to delete
Return value
err% An error code
See also

FsMkDir, FsMkDirAll


FsSessionPath - get session path

Usage

err% = FsSessionPath%:(this&,des&)

Description

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().

Arguments
this& A handle to a file server object
des& A descriptor which on return, contains the session path, including a trailing backslash
Return value
err% An error code

FsSetAtt - set file attributes

Usage

err% = FsSetAtt%:(this&,name$,set&,clear&)

Description

Sets the file attributes set& and clears the file file attributes clear& on the file name$,.

Arguments
this& A handle to a file server object
set& The attributes to set
clear& The attributes to clear
Return value
err% An error code
See also

FsAttl


FsSetDefaultPath - set system default path

Usage

err% = FsSetDefaultPath%:(this&,name$)

Description

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.

Arguments
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.
Return value
err% An error code

FsSetDriveName - set drive name

Usage

err% = FsSetDriveName%:(this&,drive&,name$)

Description

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.

Arguments
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.
Return value
err% An error code

FsSetModified - set modification date and time

Usage

err% = FsSetModified%:(this&,name$,time&)

Description

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&.

Arguments
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
Return value
err% An error code

FsSetNotifyUser - set failure notification

Usage

FsSetNotifyUser%:(this&,bool%)

Description

Use this function to set whether the user should be notified of file read or write failure.

Arguments
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

FsSetSessionPath - set session path

Usage

err% = FsSetSessionPath%:(this&,name$)

Description

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.

Arguments
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.
Return value
err% An error code

FsSetSubst - assign path to drive letter

Usage

err% = FsSetSubst%:(this&,name$,drive&)

Description

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$.

Arguments
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.
Return value
err% An error code

FsSetVolumeLabel - set volume label

Usage

err% = FsSetVolumeLabel%:(this&,name$,drive&)

Description

Use this function to set the label for a volume.

Arguments
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.
Return value
err% An error code
K32ErrNotReady& if the drive contains no media.

FsSubst - get path assigned to drive

Usage

err% = FsSubst%:(this&,des&,drive&)

Description

Use this function to get the path assigned to a drive letter by FsSetSubst.

Arguments
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.
Return value
err% An error code
K32ErrNotReady& if the drive contains no media.

FsVolume - get volume information

Usage

err% = FsVolume%:(this&,info&,drive&)

Description

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.

Arguments
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.
Return value
err% An error code