FindFirstFileExFromApp function

Searches a directory for a file or subdirectory with a name and attributes that match those specified. The behavior of this function is identical to FindFirstFileEx, except that this function adheres to the Universal Windows Platform app security model.

Syntax


HANDLE WINAPI FindFirstFileExFromApp(
  _In_       LPCWSTR            lpFileName,
  _In_       FINDEX_INFO_LEVELS fInfoLevelId,
  _Out_      LPVOID             lpFindFileData,
  _In_       FINDEX_SEARCH_OPS  fSearchOp,
  _Reserved_ LPVOID             lpSearchFilter,
  _In_       DWORD              dwAdditionalFlags
);

Parameters

lpFileName [in]

The directory or path, and the file name. The file name can include wildcard characters, for example, an asterisk (*) or a question mark (?).

This parameter should not be NULL, an invalid string (for example, an empty string or a string that is missing the terminating null character), or end in a trailing backslash (\).

If the string ends with a wildcard, period, or directory name, the user must have access to the root and all subdirectories on the path.

In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to approximately 32,000 wide characters, call the Unicode version of the function (FindFirstFileFromAppExW), and prepend "\\?\" to the path. For more information, see Naming a File.

For the unicode version of this function (FindFirstFileFromAppExW), you can opt-in to remove the MAX_PATH character limitation without prepending "\\?\". See the "Maximum Path Limitation" section of Naming Files, Paths, and Namespaces for details.

fInfoLevelId [in]

The information level of the returned data.

This parameter is one of the FINDEX_INFO_LEVELS enumeration values.

lpFindFileData [out]

A pointer to the buffer that receives the file data.

The pointer type is determined by the level of information that is specified in the fInfoLevelId parameter.

fSearchOp [in]

The type of filtering to perform that is different from wildcard matching.

This parameter is one of the FINDEX_SEARCH_OPS enumeration values.

lpSearchFilter

A pointer to the search criteria if the specified fSearchOp needs structured search information.

At this time, none of the supported fSearchOp values require extended search information. Therefore, this pointer must be NULL.

dwAdditionalFlags [in]

Specifies additional flags that control the search.

ValueMeaning
FIND_FIRST_EX_CASE_SENSITIVE
1

Searches are case-sensitive.

FIND_FIRST_EX_LARGE_FETCH
2

Uses a larger buffer for directory queries, which can increase performance of the find operation.

FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY
4

Limits the results to files that are physically on disk. This flag is only relevant when a file virtualization filter is present.

 

Return value

If the function succeeds, the return value is a search handle used in a subsequent call to FindNextFile or FindClose, and the lpFindFileData parameter contains information about the first file or directory found.

If the function fails or fails to locate files from the search string in the lpFileName parameter, the return value is INVALID_HANDLE_VALUE and the contents of lpFindFileData are indeterminate. To get extended error information, call the GetLastError function.

Requirements

Minimum supported client

Windows 10, version 1803 [desktop apps only]

Minimum supported server

Windows Server [desktop apps only]

Header

WinBase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

FindFirstFileExFromAppW (Unicode) and FindFirstFileExFromAppA (ANSI)

 

 

Show: