InformIT: Visual C++ 6 Unleashed > FTP Client Functions

Table of Contents

FTP Client Functions

The following functions are provided by the WinInet API to work with connections to an FTP server. The connection handle (hFtpSession) used in these calls is obtained by a call to InternetConnect(), as you saw earlier.

The Current Directory

You can retrieve the current directory for an FTP connection by calling FtpGetCurrentDirectory():

BOOL FtpGetCurrentDirectory(HINTERNET hFtpSession,
    LPCTSTR lpszCurrentDirectory, LPDWORD lpdwCurrentDirectory);

The lpdwCurrentDirectory parameter should point to a DWORD containing the size of the buffer at lpszCurrentDirectory, which will receive a null-terminated ASCII string containing the absolute path to the current directory. A buffer of size MAX_PATH is sufficient for all pathnames.

You can set the current directory for an FTP connection with the FtpSetCurrentDirectory() function:

BOOL FtpSetCurrentDirectory(HINTERNET hFtpSession,
    LPCTSTR lpszDirectory);

lpszDirectory points to a null-terminated ASCII string containing either an absolute or relative path to the new current directory.

Creating and Removing Directories

You can create a new directory on the FTP server with the FtpCreateDirectory() function:

BOOL FtpCreateDirectory(HINTERNET hFtpSession,
    LPCTSTR lpszDirectory);

You can specify either an absolute path or a path relative to the current directory in the null-terminated string passed by lpszDirectory.

You can remove a directory from the FTP server with the FtpRemoveDirectory() function:

BOOL FtpRemoveDirectory(HINTERNET hFtpSession,
    LPCTSTR lpszDirectory);

lpszDirectory points to a null-terminated string containing either an absolute path or a path relative to the current directory for the directory to be removed.

Finding Files

You can begin a search for a file or a general listing of files on an FTP server with the FtpFindFirstFile() function:

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

You can specify a valid directory or filename in the null-terminated string at lpszSearchFile. Additionally, you may specify a NULL or empty string to begin retrieving a listing of files in the current directory.

Information about the first file found is returned in a WIN32_FIND_DATA structure at lpFindFileData.

To retrieve information on additional files found, you can call InternetFindNextFile():

BOOL InternetFindNextFile(HINTERNET hFind, LPVOID lpvFindData);

The hFind parameter gives the find handle returned by FtpFindFirstFile(), and a WIN32_FIND_DATA structure is returned via lpvFindData with information on the next file in the listing.

If no more matching files are found, InternetFindNextFile() returns FALSE, and a call to GetLastError() returns ERROR_NO_MORE_FILES.

The nature of the FTP protocol dictates that only one find handle be open at any given time for any particular FTP connection handle. Thus, you must call InternetCloseHandle() to close one find handle before starting a new search. You also cannot begin a search with FtpFindFirstFile() while there is an open file handle returned by FtpOpenFile().

Retrieving a File

You can copy files from the FTP server to a local drive with the FtpGetFile() function:

BOOL FtpGetFile(HINTERNET hFtpSession, LPCSTR lpszRemoteFile,
    LPCSTR lpszNewFile, BOOL fFailIfExists,
    DWORD dwFlagsAndAttributes, DWORD dwFlags,
    DWORD dwContext);

Null-terminated strings containing the source and destination filenames are passed in lpszRemoteFile and lpszNewFile. You can specify a value of TRUE for fFailIfExists to cancel the operation if a local file with the name passed in lpszNewFile already exists.

The dwFlagsAndAttributes parameter contains flags for the file attributes of the new file. These can be any of the file attribute flags used with the Win32 CreateFile() function.

The dwFlags parameter may contain the following flags, which control the transfer mode, as well as several other flags that control the caching operation:

FTP_TRANSFER_TYPE_ASCII performs an ASCII transfer, converting control and formatting information to local formats, such as replacing newlines with carriage return/linefeed pairs.
FTP_TRANSFER_TYPE_BINARY transfers the file in binary mode; no changes are made to the data. This is the default.
FTP_TRANSFER_TYPE_UNKNOWN defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAGE_TRANSFER_ASCII transfers the file in ASCII format.
INTERNET_FLAGE_TRANSFER_BINARY transfers the file in binary format.

Sending a File

You can copy a file from a local drive to the FTP server with the FtpPutFile() function:

BOOL FtpPutFile(HINTERNET hFtpSession, LPCTSTR lpszLocalFile,
    LPCTSTR lpszNewRemoteFile, DWORD dwFlags, DWORD dwContext);

lpszLocalFile and lpszNewRemoteFile point to null-terminated strings containing the local and remote filenames, respectively. The dwFlags parameter may specify one of the transfer type constants used in FtpGetFile().

Opening a File on the FTP Server

The WinInet API enables you to access a file in place on the FTP server, which can be useful when you want to read or write data using memory buffers rather than a local file. You also can have more control over the progress of a file transfer by handling the read or write operations manually. You can open a file for reading or writing in-place on the FTP server with a call to FtpOpenFile():

HINTERNET FtpOpenFile(HINTERNET hFtpSession, LPCSTR lpszFileName,
    DWORD fdwAccess, DWORD dwFlags, DWORD dwContext);

The hFtpSession parameter should be a handle returned by InternetConnect(). The name of the file is passed in lpszFileName().

To open the file for reading, you should specify GENERIC_READ in fdwAccess. For writing, you should set fdwAccess to GENERIC_WRITE. You cannot use both for a given handle.

You can use the dwFlags parameter to specify the transfer mode for the file by using either FTP_FLAG_TRANSFER_ASCII or FTP_FLAG_TRANSFER_BINARY. In addition, you may specify other flags that dictate how caching will be used with this file.

FtpOpenFile() returns a handle to the file on the server, which can be used in calls such as InternetReadFile() or InternetWriteFile().

When you are finished with this handle, you should call InternetCloseHandle() to release the handle. This is particularly important, because the FTP protocol allows only one file transfer at a time for a given connection. Because of this, most other FTP functions that you call while a file handle is open will fail with an error code of ERROR_FTP_TRANSFER_IN_PROGRESS.

Other FTP File Operations

You can delete a file on the FTP server with FtpDeleteFile():

BOOL FtpDeleteFile(HINTERNET hFtpSession, LPCTSTR lpszFileName);

You also can rename files on the FTP server with FtpRenameFile():

BOOL FtpRenameFile(HINTERNET hFtpSession,
    LPCTSTR lpszExisting, LPCTSTR lpszNew);

HTTP Client Functions | Next Section

Previous Section