FTP Functions

FTP Functions


The FTP functions deal with FTP file and directory manipulation and navigation. Applications that use a CERN proxy exclusively must use the InternetOpenUrl function because CERN proxies do not support FTP. For more information on how to use InternetOpenUrl, see Accessing URLs directly.
FtpCreateDirectory
FtpDeleteFile
FtpFindFirstFile
FtpGetCurrentDirectory
FtpGetFile
FtpOpenFile
FtpPutFile
FtpRemoveDirectory
FtpRenameFile
FtpSetCurrentDirectory

FtpCreateDirectory

BOOL FtpCreateDirectory(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszDirectory
);

Creates a new directory on the FTP server.

hFtpSession
Valid handle to an FTP session. This handle must have been returned from a previous call to InternetConnect.
lpszDirectory
Address of a null-terminated string that contains the name of the directory to create on the remote system. This can be either a fully qualified path or a name relative to the current directory.

An application should use FtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpCreateDirectory translates the directory name separators to the appropriate character before they are used.

FtpDeleteFile

BOOL FtpDeleteFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszFileName
);

Deletes a file stored on the FTP server.

hFtpSession
Valid handle to an FTP session. This handle must have been returned from a previous call to InternetConnect.
lpszFileName
Address of a null-terminated string that contains the name of the file to delete on the remote system.

The lpszFile parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpDeleteFile translates the directory name separators to the appropriate character before they are used.

FtpFindFirstFile

HINTERNET FtpFindFirstFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszSearchFile,
    OUT LPWIN32_FIND_DATA lpFindFileData,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Searches the specified directory of the given FTP session. File and directory entries are returned to the application in the WIN32_FIND_DATA structure.

hFtpSession
Valid handle to an FTP session returned from InternetConnect.
lpszSearchFile
Address of 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, it will find the first file in the current directory on the server.
lpFindFileData
Address of a WIN32_FIND_DATA structure that receives information about the found file or directory.
dwFlags
Application-defined value that associates this search with any application. Can be one of the following values:
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 from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
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
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.

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 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 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.

The InternetCloseHandle function is used to close the handle returned from 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, 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 will often be the same as the file's modification date.

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

See also InternetSetStatusCallback

FtpGetCurrentDirectory

BOOL FtpGetCurrentDirectory(
    IN HINTERNET hFtpSession,
    OUT LPSTR lpszCurrentDirectory,
    IN OUT LPDWORD lpdwCurrentDirectory
);

Retrieves the current directory for the specified FTP session.

hFtpSession
Valid handle to an FTP session.
lpszCurrentDirectory
Address of a buffer that receives the current directory string, which specifies the absolute path to the current directory. The string is null terminated.
lpdwCurrentDirectory
Address of a variable that specifies the length, in characters, of the buffer for the current directory string. The buffer length must include room for a terminating null character. Using a length of MAX_PATH is sufficient for all paths. When the function returns, the variable receives the number of characters copied into the buffer.

If the lpszCurrentDirectory buffer is not large enough, lpdwCurrentDirectory receives the number of bytes required to retrieve the full, current directory name.

FtpGetFile

BOOL FtpGetFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszRemoteFile,
    IN LPCSTR lpszNewFile,
    IN BOOL fFailIfExists,
    IN DWORD dwLocalFlagsAndAttributes,
    IN DWORD dwInternetFlags,
    IN DWORD dwContext
);

Retrieves a file from the FTP server and stores it under the specified file name, creating a new local file in the process.

hFtpSession
Valid handle to an FTP session.
lpszRemoteFile
Address of a null-terminated string that contains the name of the file to retrieve from the remote system.
lpszNewFile
Address of a null-terminated string that contains the name of the file to create on the local system.
fFailIfExists
Boolean flag that indicates whether the function should proceed if a local file of the specified name already exists. If fFailIfExists is TRUE and the local file exists, FtpGetFile fails.
dwLocalFlagsAndAttributes
File attributes for the new file. Can be any combination of the FILE_ATTRIBUTE_* flags used by the CreateFile function. For more information on FILE_ATTRIBUTE_* attributes, see CreateFile in the Platform SDK.
dwInternetFlags
Flags that control how the function will handle the file download. The first set of flag values indicates the conditions under which the transfer occurs. These transfer type flags can be used in combination with the second set of flags that control caching. The application can select one of these transfer type values:
FTP_TRANSFER_TYPE_ASCII
Transfers the file using FTP's ASCII (Type A) transfer method. Control and formatting information is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY
Transfers the file using FTP's Image (Type I) transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.
FTP_TRANSFER_TYPE_UNKNOWN
Defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII
Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY
Transfers the file as binary.
The following flags determine how the caching of this file will be done. Any combination of the following flags can be used with the transfer type flag. The possible values are:
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 from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
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
Application-defined value that associates this search with any application data. This is used only if the application has already called InternetSetStatusCallback to set up a status callback function.

FtpGetFile is a high-level routine that handles all the bookkeeping and overhead associated with reading a file from an FTP server and storing it locally. An application that needs to retrieve file data only or that requires close control over the file transfer should use the FtpOpenFile and InternetReadFile functions.

If the dwTransferType parameter specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data converts control and formatting characters to local equivalents. The default transfer is binary mode, where the file is downloaded in the same format as it is stored on the server.

Both lpszRemoteFile and lpszNewFile can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpGetFile translates the directory name separators to the appropriate character before they are used.

FtpOpenFile

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

Initiates access to a remote file for writing or reading.

hFtpSession
Valid handle to an FTP session.
lpszFileName
Address of a null-terminated string that contains the name of the file to access on the remote system.
fdwAccess
Value that determines how the file will be accessed. This can be GENERIC_READ or GENERIC_WRITE, but not both.
dwFlags
Conditions under which the transfers occur. The application should select one transfer type and any of the flags that control how the caching of the file will be controlled. The transfer type can be any one of the following values:
FTP_TRANSFER_TYPE_ASCII
Transfers the file using FTP's ASCII (Type A) transfer method. Control and formatting information is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY
Transfers the file using FTP's Image (Type I) transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.
FTP_TRANSFER_TYPE_UNKNOWN
Defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII
Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY
Transfers the file as binary.

The following values are used to control the caching of the file. The application can use one or more of the following values:

INTERNET_FLAG_DONT_CACHE
Does not cache the data, either locally or in any gateways. 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 from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
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 cache the data, either locally or in any gateways.
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
Application-defined value that associates this search with any application data. This is only used if the application has already called InternetSetStatusCallback to set up a status callback function.

FtpOpenFile should be used in the following situations:

After calling FtpOpenFile and until calling InternetCloseHandle, all other calls to FTP functions on the same FTP session handle will fail and set the error message to ERROR_FTP_TRANSFER_IN_PROGRESS.

Only one file can be open in a single FTP session. Therefore, no file handle is returned and the application simply uses the FTP session handle when necessary.

The lpszFile parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpOpenFile translates the directory name separators to the appropriate character before they are used.

The InternetCloseHandle function is used to close the handle returned from FtpOpenFile. If InternetCloseHandle closes the handle before all the data has been transferred, the transfer is terminated.

FtpPutFile

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

Stores a file on the FTP server.

hFtpSession
Valid handle to an FTP session.
lpszLocalFile
Address of a null-terminated string that contains the name of the file to send from the local system.
lpszNewRemoteFile
Address of a null-terminated string that contains the name of the file to create on the remote system.
dwFlags
Conditions under which the transfer occurs. Can be any combination of the following values:
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 from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
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
Performs a conditional download of the file.
INTERNET_FLAG_TRANSFER_ASCII
Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY
Transfers the file as binary.
dwContext
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.

FtpPutFile is a high-level routine that handles all the bookkeeping and overhead associated with reading a file locally and storing it on an FTP server. An application that needs to send file data only, or that requires close control over the file transfer, should use the FtpOpenFile and InternetWriteFile functions.

If the dwTransferType parameter specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data converts control and formatting characters to local equivalents.

Both lpszNewRemoteFile and lpszLocalFile can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpPutFile translates the directory name separators to the appropriate character before they are used.

FtpRemoveDirectory

BOOL FtpRemoveDirectory(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszDirectory
);

Removes the specified directory on the FTP server.

hFtpSession
Valid handle to an FTP session.
lpszDirectory
Address of a null-terminated string that contains the name of the directory to remove on the remote system. This can be either a fully qualified path or a name relative to the current directory.

An application should use FtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpRemoveDirectory translates the directory name separators to the appropriate character before they are used.

FtpRenameFile

BOOL FtpRenameFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszExisting,
    IN LPCSTR lpszNew
);

Renames a file stored on the FTP server.

hFtpSession
Valid handle to an FTP session.
lpszExisting
Address of a null-terminated string that contains the name of the file that will have its name changed on the remote FTP server.
lpszNew
Address of a null-terminated string that contains the new name for the remote file.

The lpszExisting and lpszNew parameters can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpRenameFile translates the directory name separators to the appropriate character before they are used.

FtpSetCurrentDirectory

BOOL FtpSetCurrentDirectory(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszDirectory
);

Changes to a different working directory on the FTP server.

hFtpSession
Valid handle to an FTP session.
lpszDirectory
Address of a null-terminated string that contains the name of the directory to change to on the remote system. This can be either a fully qualified path or a name relative to the current directory.

An application should use FtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpSetCurrentDirectory translates the directory name separators to the appropriate character before they are used.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.