Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function searches the specified directory of the specified FTP session. File and directory entries are returned to the application in the WIN32_FIND_DATAstructure.

Syntax 

HINTERNET FtpFindFirstFile(
  HINTERNET 
hConnect, 
  LPCTSTR 
lpszSearchFile, 
  LPWIN32_FIND_DATA 
lpFindFileData, 
  DWORD 
dwFlags, 
  DWORD 
dwContext
);

Parameters

hConnect

[in] Valid handle to an FTP session returned by the InternetConnectfunction.

lpszSearchFile

[in] Long pointer to a null-terminated string that specifies a valid directory path or file name for the FTP server file system. The string can contain wildcards, but blank spaces are not accepted. If the value of lpszSearchFileis NULL or if it is an empty string, it will find the first file in the current directory on the server.

lpFindFileData

[out] Long pointer to a WIN32_FIND_DATAstructure that receives data about the found file or directory.

dwFlags

[in] Specifies an application-defined value that associates this search with an application. The following table shows the possible values. This parameter is one of these values.

Value Description

INTERNET_FLAG_DONT_CACHE

Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.

INTERNET_FLAG_HYPERLINK

Forces a reload if there was no Expires time and no Last-Modified time returned by the server when determining whether to reload the item from the network.

INTERNET_FLAG_MUST_CACHE_REQUEST

Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.

INTERNET_FLAG_NEED_FILE

Causes a temporary file to be created if the file cannot be cached.

INTERNET_FLAG_NO_CACHE_WRITE

Does not add the returned entity to the cache. If the INTERNET_FLAG_HYPERLINK is also specified, WinInet will create the cache file but will not commit it.

INTERNET_FLAG_RELOAD

Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.

INTERNET_FLAG_RESYNCHRONIZE

Causes the FTP resource to be reloaded from the server.
dwContext

[in] Specifies an application-defined value that associates this search with application data. This parameter is used only if the application has already called the InternetSetStatusCallbackfunction to set up a status callback function. All status requests are handled synchronously.

Return Value

If the directory enumeration was started, a valid handle for the request indicates success. NULL indicates failure. To get extended error data, call GetLastError. If the function finds no matching files, GetLastErrorreturns ERROR_NO_MORE_FILES.

Remarks

This function enumerates both files and directories.

FtpFindFirstFileis similar to the Win32 FindFirstFilefunction. However, only one FtpFindFirstFilecan occur at a time within a given FTP session. Therefore, because the FTP protocol accepts only one directory enumeration per session, the enumerations are correlated with the FTP session handle. After calling this function and until calling the InternetCloseHandlefunction, the application cannot call FtpFindFirstFileagain on the given FTP session handle. If a call is made, , the function will fail with ERROR_FTP_TRANSFER_IN_PROGRESS.

After beginning a directory enumeration with FtpFindFirstFile, the InternetFindNextFilefunction can be used to continue the enumeration.

InternetCloseHandlecloses the handle returned by FtpFindFirstFile. If it closes the handle before InternetFindNextFilefails with ERROR_NO_MORE_FILES, the directory enumeration will be terminated.

Because the FTP protocol provides no standard means of enumerating, common file data, such as file creation date and time, is not always available or correct. When this happens, FtpFindFirstFileand InternetFindNextFilefill unavailable data with an estimate. For example, creation and last access dates will often be the same as the file modification date.

The application cannot call FtpFindFirstFilebetween calls to FtpOpenFileand InternetCloseHandle.

Requirements

Header wininet.h
Library wininet.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also