FS_FindFirstFile

FS_FindFirstFile(
 PIOREQ pir
 )

A Win32 find first operation is performed through FS_FindFirstFile. A find context handle is created and is passed on FS_FindNextFile to continue the search. This routine handles the Win32 function: FindFirstFile() and the int 21h function 714Eh.

ir_ppath

Supplies a pointer to the canonicalized unicode pathname that the search is to begin at. Wildcards are allowed on the pathname.

ir_rh

Supplies handle to disk volume or network resource where the search is being done.

ir_attr

Supplies must-match and search attributes. Path parsing flags are also provided as advisory information for the FSDs.

Value	Meaning
Search Attribute Values: Any combination of the following attributes may be specified, causing those files to be included with normal files in the search.
FILE_ATTRIBUTE_HIDDEN	Include hidden file in search.
FILE_ATTRIBUTE_SYSTEM	Include system file in search.
FILE_ATTRIBUTE_DIRECTORY	Include subdirectories in search.
FILE_ATTRIBUTE_VOLUMELABEL	Search for volume label.
Must-Match Attribute Values: The must-match attributes can be any of the following attributes.
FILE_ATTRIBUTE_READONLY	Match read-only files.
FILE_ATTRIBUTE_HIDDEN	Match hidden files.
FILE_ATTRIBUTE_SYSTEM	Match system files.
FILE_ATTRIBUTE_DIRECTORY	Match subdirectories.
FILE_ATTRIBUTE_ARCHIVE	Match archived files.
FILE_ATTRIBUTE_VOLUMELABEL	Match volume label.
Path Parsing Flags: The following path parsing flags are passed in.
Value	Meaning
FILE_FLAG_WILDCARDS	Wildcard characters present in pathname.
FILE_FLAG_HAS_STAR	Path has the asterisk as a wildcard character.
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.

ir_upath

Pointer to the unparsed user pathname in unicode.

ir_hfunc

Supplies a pointer to a function pointer structure, containing a list of the FSD find file entry points.

ir_data

Supplies a pointer to buffer where the find data for a file that is found is returned.

ir_sfn

Supplies system file number.

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 find context handle that is passed in by the IFS manager on subsequent calls to FS_FindNextFile and FS_FindClose.
ir_hfunc	Returns a filled in function pointer structure, containing a list of the FSD find file entry points. The structure is filled in as follows:

Value	Meaning
Function Pointer Structure:
hf_read	Returns pointer to FS_FindNextFile function.
hf_write	Function is not defined, FSD must return pointer to an error 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.

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]	Undefined function, must return pointer to an error function.
hm_func[HM_CLOSE]	Returns pointer to FS_FindClose function.
hm_func[HM_COMMIT]	Undefined function, must return pointer to an error function.
hm_func[HM_FILELOCKS]	Undefined function, must return pointer to an error function.
hm_func[HM_FILETIMES]	Undefined function, must return pointer to an error function.
hm_func[HM_PIPEREQUEST]	Undefined function, must return pointer to an error function.
hm_func[HM_HANDLEINFO]	Undefined function, must return pointer to an error function.
hm_func[HM_ENUMHANDLE]	Returns a pointer to the FS_EnumerateHandle function.

ir_data

Returns find data for a file filled in the buffer in the following format if there was no error.

Find Data Structure:
dwFileAttributes	Returns the file attributes of the file found.

Value	Meaning
Attribute Values: Any valid 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.
FILE_ATTRIBUTE_VOLUMELABEL	Volume label found.

ftCreationTime

Returns the file creation time in the Win32 FileTime structure format.

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

ftLastAccessTime	Returns the file last access time in Win32 FileTime structure format defined above.
ftLastWriteTime	Returns the file last write time in Win32 FileTime structure format defined above.
nFileSizeHigh	Returns the high 32-bits of the file size.
nFileSizeLow	Returns the low 32-bits of the file size.
cFileName	Returns the unicode long filename that was found.
CAlternateFileName	Returns the unicode alternate alias name (short file name) of the file that was found.

ir_pos

Returns the find resume key for this find next operation. The operation of this key is described below.

Local FSDs need to return and also be able to take a find resume key as a parameter. This has been provided to optimize finds across the network by the server. The server typically does a bunch of find first/next operations and stores the information for each of them in a buffer, effectively providing some buffering on find next operations to prevent every find next operation from causing net traffic. However, the network redirector might discard or reuse the buffers if necessary. In that case, the find operation needs to be resumed at that point where a findnext buffer is not valid, which is different from the point at which the find next operation was stopped at the server machine. To facilitate this, the server passes in a find resume key to the IFS which is then passed in to the FSDs, so that they can throw away their current find next state and restart the find next at the point specified by the resume key. This means that the resume key must store enough information so that the find can be restarted at a particular point. For example, on a FAT file system, the find resume key could be a combination of the cluster number and the index within the cluster of the directory entry last found. This way, when the resume key is passed in, the find next can be restarted at the correct spot. This does not need to be done by network FSDs, it is only local FSDs that handle drives that can be shared that need to implement this functionality.

This API should use LFN matching semantics for its operations only if either or both the FILE_FLAG_KEEP_CASE and FILE_FLAG_IS_LFN are set. The FSD should not assume that this API will always use LFN matching semantics by default. These flags are passed in by the IFS to indicate that LFN matching semantics need to be used. By default, this API will have LFN matching semantics. However, there are certain special cases, such as on the peer server, where a call that comes in via an LFN API still needs shortname matching semantics. If the FSD does not support LFNs on the volume, it should return an error on this function.