FS_OpenFile

FS_OpenFile(
 PIOREQ pir
 )

All file open and create operations are handled through FS_OpenFile. This routine handles the Win32 functions: OpenFile(), and CreateFile(); and INT 21h functions: 0Fh, 16h, 3Ch, 3Dh, 5Ah, 5Bh, 6Ch and 716Ch.

ir_ppath

Supplies a pointer to the canonicalized unicode pathname to the file that is to be opened. Wildcards are not allowed on the pathname.

If ir_ppath is NULL, it indicates that this is a special kind of open where there is no path available, only cluster and directory information is available. This special kind of open is issued by the IFS manager when it is taking over a file handle left open by a TSR before booting into Windows. For such files, the IFS manager extracts the information from DOS about the cluster number and the directory position for the open file. The FSD needs to locate the file given this information. A pointer to a structure containing this information is passed in ir_uFName. Note that this kind of open can be issued only on FAT file systems because the only native system supported by MS-DOS is the FAT file system.

ir_rh

Supplies handle to disk volume or network resource where the file is to be opened.

ir_sfn

Supplies system file number.

ir_flags

Supplies desired access & sharing mode info.

Value	Meaning
Desired Access Values: One of the following values may be specified.
ACCESS_READONLY	Open for read-only access.
ACCESS_WRITEONLY	Open for write-only access.
ACCESS_READWRITE	Open for read and write access.
ACCESS_EXECUTE	Open for execute access.
Sharing Mode Values: This defines the file access granted to other processes. One of the following modes may be specified.
SHARE_COMPATIBILITY	Open in compatibility mode.
SHARE_DENYREADWRITE	Open for exclusive access.
SHARE_DENYWRITE	Open allowing read-only access.
SHARE_DENYREAD	Open allowing write-only access.
SHARE_DENYNONE	Open allowing other processes access.
SHARE_FCB	Open in the special FCB mode.

ir_options

Supplies the open action to take if file exists or not. Also supplies some special options that are independent of the open action.

Value	Meaning
Open Action Values: One of the following actions or a combination of actions may be specified. Specifies the action to take if the file exists or not exists.
ACTION_CREATENEW	Create a new file. Fail if the file already exists.
ACTION_CREATEALWAYS	Create a new file. If the file already exists open it and set its new length and attributes.
ACTION_OPENEXISTING	Open an existing file. Fail if the file does not exist.
ACTION_OPENALWAYS	Open an existing file. If the file does not exist, create a new file.
ACTION_REPLACEEXISTING	Open an existing file and set its new length. Fail if the file does not exists.
Special Options: The following special options can also be passed in on this API.
Value	Meaning
OPEN_FLAGS_COMMIT	The file should be opened in writethrough mode, that is, all data should be written synchronously to the disk. The data can be cached, but no dirty data should remain in the cache across calls to write to the file.
OPEN_FLAGS_NO_CACHE	Read/write operations to this file should not be cached. There should be no data kept in the cache for this file. This also means that the file system should not do read-aheads and other optimizing techniques on this file.
OPEN_FLAGS_NO_COMPRESS	The file should not be compressed when it is created or changed.
OPEN_FLAGS_ALIAS_HINT	This is valid only on a create operation. The caller can pass in a number from 0 to 65535 to be used as a hint by the FSD for the numeric tail if it is auto-generating names. If the FSD does not auto-generate names, this flag should be ignored. This is purely an advisory option.
OPEN_FLAGS_REOPEN	The file is being reopened by IFS Manager when a level 3 volume lock is released (the file was temporarily closed by IFS Manager for the duration of the level 3 volume lock).
R0_SWAPPER_CALL	This operation is on the swap file. The swap file needs special handling as has already been discussed in section 8.3.4.

ir_attr

Supplies new file attribute for create operations. These attributes should be ignored when an existing file is opened or truncated. It also supplies advisory path parsing flags.

Value	Meaning
Attribute Values: Any combination of the following attributes may be specified or returned.
FILE_ATTRIBUTE_READONLY	Read-Only file.
FILE_ATTRIBUTE_HIDDEN	Hidden file.
FILE_ATTRIBUTE_SYSTEM	System file.
FILE_ATTRIBUTE_DIRECTORY	Subdirectory. The following attribute will only be specified by itself. It will not be combined with any of the other attributes.
FILE_ATTRIBUTE_VOLUMELABEL	Volume label.
Path Parsing Flags: The following path parsing flags are passed in.
FILE_FLAG_LONG_PATH	Path has a longname component.
FILE_FLAG_KEEP_CASE	Preserve the case of the filename passed in when storing on disk. This also implies that this call should use longname semantics for its processing.
FILE_FLAG_HAS_DOT	Filename component has a dot in its name.
FILE_FLAG_IS_LFN	Filename component is a longname.

ir_uFName

Pointer to the case-preserved filename component in unicode if ir_ppath is a valid pointer. If ir_ppath is NULL, then this field contains a pointer to an open information structure SFTOpenInfo as described below.

Value	Meaning
SFTOpenInfo Structure:
soi_dirclus	Supplies the logical cluster number of the directory cluster for the open file.
soi_dirind	Supplies the index of the directory entry of the open file in the directory cluster pointed at by soi_dirclus.

soi_dirname

Supplies the 11-character name of the open file in FCB format.

ir_upath

Pointer to the unparsed user pathname in unicode.

ir_hfunc

Supplies a pointer to a function pointer structure.

ir_ptuninfo

Supplies a pointer to a tunnelling structure. A NULL pointer is passed in this field if there is no tunnelling information. The tunnelling structure is described below.

Value	Meaning
Tunnelling Structure:
tuni_bfContents	Specifies flags for the tunnelling information passed in.

Value	Meaning
Tunnelling Info Flag Values:
TUNI_CONTAINS_ALTNAME	Alternate unicode name is available in structure.
TUNI_CONTAINS_CREATIONT	Creation time for file available.
TUNI_CONTAINS_LASTACCESST	Last access time for file available.
TUNI_CONTAINS_LASTWRITET	Last modification time for file available.

tuni_pAltName

Supplies the alternate name in unicode that should be used for this file.

tuni_ftCreationTime

Supplies the creation time in the Win32 FileTime structure format specified below.

Value	Meaning
Win32 FileTime Structure:
dwLowDateTime	Supplies the low double word of the time in Win32 format.
dwHighDateTime	Supplies the low double word of the time in Win32 format.

tuni_ftLastAccessTime

Supplies the last access time in the Win32 FileTime structure format described above.

tuni_ftLastWriteTime

Supplies the last modification time in the Win32 FileTime structure format described above.

ir_pos

Supplies the pointer to the list of file record locks returned previously on FS_CloseFile when a volume lock is in progress. This parameter is NULL if there were no file record locks active on the file at the time it was closed. If the OPEN_FLAGS_ALIAS_HINT flag is set, this field supplies the hint value to be used for the numeric tail. FSDs should first check for the OPEN_FLAGS_ALIAS_HINT flag. If it is set, this field provides the hint value. If not set, this field supplies the pointer to the lock list.

ir_fh

Supplies the FSD file handle associated with this file before the file was closed. This parameter should be used only if there were file record locks active on the file, in other words, ir_pos is non-NULL. This parameter is passed in to the FSD so that it can identify the lock corresponding to the handle that is being reopened and keep its data structures consistent. Volume locking is described in detail in the volume locking specification.

ir_user

Supplies user ID for this request.

ir_pid

Supplies process ID for this request.

ir_error	Returns status of the operation ( 0 if no error, errorcode otherwise ).
ir_fh	Returns the FSD file handle identifying the opened file.
ir_dostime	Returns the file modification date and time (in DOS format).
ir_hfunc	Returns a filled in function pointer structure. The structure is filled in as follows:

Value	Meaning
Function Pointer Structure:
hf_read	Returns pointer to FS_ReadFile function.
hf_write	Returns pointer to FS_WriteFile function.
hf_misc	Returns a pointer to a function table structure, in the FSD, containing a list of the remaining FSD handle based file I/O entry points.

Value	Meaning
Function Table Structure:
hm_version	IFS version number.
hm_revision	IFS interface revision number.
hm_size	Number of function entry points in table.
hm_func[NUM_HNDLMISC]	Returns an array of pointers to the handle-based functions as described below:
hm_func[HM_SEEK]	Pointer to FS_SeekFile function.
hm_func[HM_CLOSE]	Pointer to FS_CloseFile function.
hm_func[HM_COMMIT]	Pointer to FS_CommitFile function.
hm_func[HM_FILELOCKS]	Pointer to FS_LockFile function.
hm_func[HM_FILETIMES]	Pointer to FS_FileTime function.
hm_func[HM_PIPEREQUEST]	Pointer to FS_NamedPipeUNCRequest function.
hm_func[HM_HANDLEINFO]	Pointer to FS_NamedPipeHandleInfo function.
hm_func[HM_ENUMHANDLE]	Pointer to FS_EnumerateHandle function.

ir_options

Returns the action performed by the FSD.

Value	Meaning
Return Action Values: One of the following actions may be returned.
ACTION_OPENED	An existing file has been opened.
ACTION_CREATED	A new file has been created.
ACTION_REPLACED	An existing file has been truncated.

ir_size	Returns the file size when an existing file is opened. The size is currently placed in the SFT in the DOS data structures.
ir_attr	Returns the file attribute (state for named pipes).

Value	Meaning
Return Attribute Values: Any combination of the following attributes may be returned.
FILE_ATTRIBUTE_READONLY	Read-Only file.
FILE_ATTRIBUTE_HIDDEN	Hidden file.
FILE_ATTRIBUTE_SYSTEM	System file.
FILE_ATTRIBUTE_DIRECTORY	Subdirectory.
FILE_ATTRIBUTE_ARCHIVE	Archive file. This attribute cannot be returned in combination with other attributes.
FILE_ATTRIBUTE_VOLUMELABEL	Volume label.

If an FS does not support long filenames on a volume and it gets a LFN API call on that volume, it should fail the call. Tunnelling is described separately in another section. Tunnelling is supported only on local drives. Therefore, network FSDs do not need to honor the tunnelling information.