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.