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.

Search Attribute Values:

Any combination of the following attributes may be specified, causing those files to be included with normal files in the search.

Value

Meaning

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 which 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:


Function Pointer Structure:

Value

Meaning

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.


Attribute Values:

Any valid combination of the following attributes may be returned.

Value

Meaning

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.


Win32 FileTime Structure:

Value

Meaning

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 and 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 e.g., on a FAT filesystem, 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.