Export (0) Print
Expand All
Expand Minimize
6 out of 9 rated this helpful - Rate this topic

FtpFindFirstFile function

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
);

Parameters

hConnect [in]

Handle to an FTP session returned from InternetConnect.

lpszSearchFile [in]

Pointer to 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, the function finds the first file in the current directory on the server.

lpFindFileData [out]

Pointer to a WIN32_FIND_DATA structure that receives information about the found file or directory.

dwFlags [in]

Controls the behavior of this function. This parameter can be a combination of the following values.

INTERNET_FLAG_HYPERLINK

INTERNET_FLAG_NEED_FILE

INTERNET_FLAG_NO_CACHE_WRITE

INTERNET_FLAG_RELOAD

INTERNET_FLAG_RESYNCHRONIZE

dwContext [in]

Pointer to a variable that specifies 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 GetLastError returns ERROR_INTERNET_EXTENDED_ERROR, as in the case where the function finds no matching files, call the InternetGetLastResponseInfo function to retrieve the extended error text, as documented in Handling Errors.

Remarks

For FtpFindFirstFile, file times returned in the WIN32_FIND_DATA structure are in the local time zone, not in a coordinated universal time (UTC) format.

FtpFindFirstFile is similar to the 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 fails with ERROR_FTP_TRANSFER_IN_PROGRESS. After the calling application has finished using the HINTERNET handle returned by FtpFindFirstFile, it must be closed using the InternetCloseHandle function.

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 are often the same as the file's modification date.

The application cannot call FtpFindFirstFile between calls to FtpOpenFile and InternetCloseHandle.

Like all other aspects of the WinINet API, this function cannot be safely called from within DllMain or the constructors and destructors of global objects.

Note  WinINet does not support server implementations. In addition, it should not be used from a service. For server implementations or services use Microsoft Windows HTTP Services (WinHTTP).

Requirements

Minimum supported client

Windows 2000 Professional

Minimum supported server

Windows 2000 Server

Header

Wininet.h

Library

Wininet.lib

DLL

Wininet.dll

Unicode and ANSI names

FtpFindFirstFileW (Unicode) and FtpFindFirstFileA (ANSI)

See also

FTP Sessions
WinINet Functions

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.