Searches the specified directory of the given FTP session. File and directory entries are returned to the application in the WIN32_FIND_DATA structure.
Syntax
HINTERNET FtpFindFirstFile( IN HINTERNET hConnect, IN LPCTSTR lpszSearchFile, OUT LPWIN32_FIND_DATA lpFindFileData, IN DWORD dwFlags, IN DWORD_PTR dwContext );The actual syntax of this function varies between its ANSI and Unicode implementations. For more information, see Win32 Internet Functions Syntax.
Parameters
- hConnect
- Valid handle to an FTP session returned from InternetConnect.
- lpszSearchFile
- Address of a null-terminated string that specifies a valid directory path or file name for the FTP server's file system. The string can contain wildcards, but no blank spaces are allowed. If the value of lpszSearchFile is NULL or if it is an empty string, it will find the first file in the current directory on the server.
- lpFindFileData
- Address of a WIN32_FIND_DATA structure that receives information about the found file or directory.
- dwFlags
- Unsigned long integer value that contains the flags that control the behavior of this function. This can be a combination of the following values:
- dwContext
- Address of an unsigned long integer value that contains the application-defined value that associates this search with any application data. This parameter is used only if the application has already called InternetSetStatusCallback to set up a status callback function.
Return Value
Returns a valid handle for the request if the directory enumeration was started successfully, or returns NULL otherwise. To get a specific error message, call GetLastError. If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.
Remarks
For FtpFindFirstFile, file times returned in the WIN32_FIND_DATA structure are in the local time zone, not in a time zone independent (UTC) format.
FtpFindFirstFile is similar to the Win32® FindFirstFile function. Note, however, that only one FtpFindFirstFile can occur at a time within a given FTP session. The enumerations, therefore, are correlated with the FTP session handle. This is because the FTP protocol allows only a single directory enumeration per session.
After calling FtpFindFirstFile and until calling InternetCloseHandle, the application cannot call FtpFindFirstFile again on the given FTP session handle. If a call is made to FtpFindFirstFile on that handle, the function will fail with ERROR_FTP_TRANSFER_IN_PROGRESS.
After beginning a directory enumeration with FtpFindFirstFile, the InternetFindNextFile function can be used to continue the enumeration.
Because the FTP protocol provides no standard means of enumerating, some of the common information about files, such as file creation date and time, is not always available or correct. When this happens, FtpFindFirstFile and InternetFindNextFile fill in unavailable information with a best guess based on available information. For example, creation and last access dates will often be the same as the file's modification date.
The application cannot call FtpFindFirstFile between calls to FtpOpenFile and InternetCloseHandle.
Function Information
Windows NT Use version 4.0. Implemented as ANSI and Unicode functions. Windows Use Windows 95 and later. Implemented as ANSI and Unicode functions. Header Wininet.h Import library Wininet.lib Minimum availability Internet Explorer 3.0 (ANSI only), 5 (ANSI and Unicode)
Windows CE
Windows CE Use version 2.12 and later. Implemented as ANSI and Unicode functions. Minimum availability Internet Explorer 4.0
See Also
Microsoft Win32 Internet Functions Overview, FTP Sessions, Microsoft Win32 Internet Functions Reference, FTP Functions