FtpFindFirstFile

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

BOOL WINAPI 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 InternetConnect function.

• 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 lpszSearchFile is 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_DATA structure that receives data about the found file or directory.

• dwFlags
  [in] Specifies an application-defined value that associates this search with an application. It is one of the following 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.
  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 InternetSetStatusCallback function to set up a status callback function. All status requests are handled synchronously.

Return Values

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

Remarks

Inetftp.dll is available only for Intel x86 processors.

This function enumerates both files and directories.

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 accepts only one directory enumeration per session.

After calling FtpFindFirstFile and until calling the InternetCloseHandle function, 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.

InternetCloseHandle closes the handle returned by FtpFindFirstFile. If InternetCloseHandle closes the handle before InternetFindNextFile fails 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, FtpFindFirstFile and InternetFindNextFile fill in 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 FtpFindFirstFile between calls to FtpOpenFile and InternetCloseHandle.

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

FindFirstFile, FtpFindFirstFile, FtpOpenFile, GetLastError, InternetCloseHandle, InternetConnect, InternetFindNextFile, InternetSetStatusCallback, WIN32_FIND_DATA

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.