| INT EnumFiles( |
| |
LPCTSTR lpszDirectory, |
|
| |
LPCTSTR lpszFileMask, |
|
| |
DWORD dwOptions, |
|
| |
LPFTPFILESTATUSEX lpFileList, |
|
| |
INT nMaxFiles |
|
| ); |
The EnumFiles method populates an array of structures
that contain information about the files in a directory.
Parameters
- lpszDirectory
- A null-terminated string that specifies the name of
a directory on the server. If this parameter is NULL or points to an
empty string, the method will return the files in the current
working directory. This string cannot contain wildcard characters
and must specify a valid directory name that exists on the server.
- lpszFileMask
- A null-terminated string that specifies a wildcard
file mask that is used to return a subset of files in the directory.
If this parameter is NULL or an empty string then all of the files
in the directory will be returned.
- dwOptions
- An unsigned integer value that specifies one or more options.
This parameter can be a combination of one or more of the following
values:
| Value |
Description |
| FTP_ENUM_DEFAULT |
The method will return both regular files and
subdirectories. |
| FTP_ENUM_FILE |
The method will return only regular files. |
| FTP_ENUM_DIRECTORY |
The method will return only subdirectories. |
| FTP_ENUM_FULLPATH |
The method will return the full path of the file or
subdirectory. |
- lpFileList
- A pointer to an array of
FTPFILESTATUSEX structures
which contains information about each of the files in the
specified directory. This parameter cannot be NULL, and the
array must be large enough to store the number of files specified
by the nMaxFiles parameter.
- nMaxFiles
- An integer value that specifies the maximum number of files that
should be returned. This value must be greater than zero and the
lpFileList parameter must provide an array that is large enough
to store information about each file.
Return Value
If the method succeeds, the return value is the number of files
returned by the method. If the directory is empty or there are no
files that match the specified wildcard file mask, the method will
return zero. If the method fails, the return value is FTP_ERROR.
To get extended error information, call GetLastError.
Remarks
The EnumFiles method provides a high-level interface
for obtaining a list of available files in a directory on the server
in a single function call. This is an alternative to opening a
directory and returning information about each file by calling the
GetNextFile method in a loop.
This method temporarily changes the current working directory to
the directory specified by the lpszDirectory parameter. The
current working directory will be restored to its original value when
the method returns. The user must have the appropriate permissions
to access the directory or this method will fail.
To obtain information on a subset of files in the directory, you
can specify a wildcard file mask. For FTP and FTPS (SSL) sessions,
this value is passed as a parameter to the LIST command and the server
performs the wildcard matching. For SFTP (SSH) sessions the wildcard
matching is performed by the library, and the standard conventions for
Windows file wildcards are used.
By default, the szFileName member for each
FTPFILESTATUSEX structure will contain the base file name. If the
FTP_ENUM_FULLPATH option is specified, the method will return the
full path name to the file. The library must be able to automatically
determine the path delimiter that is used by the server. This is done
by examining how the server identifies itself, the current directory
format and the path the server returns for the current working
directory. For example, UNIX based servers use the forward slash
as a path delimiter. If the method cannot determine what the
appropriate path delimiter is, it will ignore this option and return
only the base file name.
This method will cause the current thread to block until the file
listing completes, a timeout occurs or the operation is canceled.
Example
LPFTPFILESTATUSEX lpFileList = new FTPFILESTATUSEX[MAXFILECOUNT];
// Return all of the regular files in the current working directory
INT nResult = pClient->EnumFiles(FTP_ENUM_FILE, lpFileList, MAXFILECOUNT);
if (nResult == FTP_ERROR)
{
DWORD dwError = pClient->GetLastError();
_tprintf(_T("EnumFiles failed, error 0x%08lx\n"), dwError);
return;
}
_tprintf(_T("EnumFiles returned %d files\n"), nResult);
for (INT nIndex = 0; nIndex < nResult; nIndex++)
{
_tprintf(_T("file=\"%s\" size=%I64d\n"), lpFileList[nIndex].szFileName,
lpFileList[nIndex].uiFileSize);
}
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: csftpv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
GetFileStatus,
GetFirstFile,
GetNextFile,
OpenDirectory
|