CFtpConnection 类

管理与 Internet 服务器的 FTP 连接，并允许直接操作此服务器上的目录与文件。

语法

class CFtpConnection : public CInternetConnection

成员

公共构造函数

名称	描述
CFtpConnection::CFtpConnection	构造 CFtpConnection 对象。

公共方法

名称	描述
CFtpConnection::Command	向 FTP 服务器直接发送命令。
CFtpConnection::CreateDirectory	在服务器上创建目录。
CFtpConnection::GetCurrentDirectory	获取此连接的当前目录。
CFtpConnection::GetCurrentDirectoryAsURL	获取此连接的当前目录作为 URL。
CFtpConnection::GetFile	从连接的服务器中获取文件
CFtpConnection::OpenFile	打开连接的服务器上的文件。
CFtpConnection::PutFile	将文件放在服务器上。
CFtpConnection::Remove	从服务器中删除文件。
CFtpConnection::RemoveDirectory	从服务器中删除指定的目录。
CFtpConnection::Rename	重命名服务器上的文件。
CFtpConnection::SetCurrentDirectory	设置当前 FTP 目录。

备注

FTP 是 MFC WinInet 类识别的三项 Internet 服务之一。

若要与 FTP Internet 服务器通信，必须先创建 CInternetSession 的实例，然后创建 CFtpConnection 对象。 请勿直接创建 CFtpConnection 对象，而应调用 CInternetSession::GetFtpConnection，后者将创建 CFtpConnection 对象并返回指向它的指针。

若要详细了解 CFtpConnection 如何与其他 MFC Internet 类配合工作，请参阅使用 WinInet 进行 Internet 编程一文。 有关与其他两个受支持的服务（HTTP 和 gopher）通信的详细信息，请参阅 CHttpConnection 和 CGopherConnection 类。

示例

请参阅 CFtpFileFind 类概述中的示例。

继承层次结构

CObject

CInternetConnection

CFtpConnection

要求

标头：afxinet.h

CFtpConnection::CFtpConnection

调用此成员函数来构造 CFtpConnection 对象。

CFtpConnection(
    CInternetSession* pSession,
    HINTERNET hConnected,
    LPCTSTR pstrServer,
    DWORD_PTR dwContext);

CFtpConnection(
    CInternetSession* pSession,
    LPCTSTR pstrServer,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL,
    DWORD_PTR dwContext = 0,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
    BOOL bPassive = FALSE);

参数

pSession
指向相关 CInternetSession 对象的指针。

hConnected
当前 Internet 会话的 Windows 句柄。

pstrServer
指向包含 FTP 服务器名称的字符串的指针。

dwContext
操作的上下文标识符。 dwContext 标识 CInternetSession::OnStatusCallback 返回的操作的状态信息。 默认设置为 1；但是，可以为操作显式分配特定的上下文 ID。 该对象及其执行的任何工作都将与该上下文 ID 相关联。

pstrUserName
指向一个以 NULL 结尾的字符串的指针，该字符串指定要登录的用户的名称。 如果为 NULL，默认为匿名。

pstrPassword
指向一个以 NULL 结尾的字符串的指针，该字符串指定用于登录的密码。 如果 pstrPassword 和 pstrUserName 均为 NULL，则默认匿名密码是用户的电子邮件名称。 如果 pstrPassword 为 NULL（或空字符串），但 pstrUserName 不是 NULL，则使用空白密码。 下表描述了 pstrUserName 和 pstrPassword 的四种可能设置的行为：

pstrUserName	pstrPassword	发送到 FTP 服务器的用户名	发送到 FTP 服务器的密码
NULL 或“ ”	NULL 或“ ”	“匿名”	用户的电子邮件名称
非 NULL 字符串	NULL 或“ ”	pstrUserName	[.]
NULL 非 NULL 字符串	ERROR	ERROR
非 NULL 字符串	非 NULL 字符串	pstrUserName	pstrPassword

nPort
标识要在服务器上使用的 TCP/IP 端口的数字。

bPassive
为此 FTP 会话指定被动模式或主动模式。 如果设置为 TRUE，则会将 Win32 API dwFlag 设置为 INTERNET_FLAG_PASSIVE。

注解

请勿直接创建 CFtpConnection 对象。 请改为调用可创建 CFptConnection 对象的 CInternetSession::GetFtpConnection。

CFtpConnection::Command

向 FTP 服务器直接发送命令。

CInternetFile* Command(
    LPCTSTR pszCommand,
    CmdResponseType eResponse = CmdRespNone,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

参数

pszCommand
指向包含待发送命令的字符串的指针。

eResponse
指定是否预期从 FTP 服务器获得响应。 可以是以下其中一个值：

• CmdRespNone 不会有响应。
• CmdRespRead 预计有响应。
• CmdRespWrite 未使用。

CmdResponseType 是 CFtpConnection 的成员，在 afxinet.h 中定义。

dwFlags
包含控制此函数的标志的值。 有关完整列表，请参阅 FTPCommand。

dwContext
指向一个值的指针，该值包含用于在回调中标识应用程序上下文的应用程序定义的值。

返回值

如果成功，则不为 0；否则为 0。

备注

此成员函数模拟 FTPCommand 函数的功能，如 Windows SDK 中所述。

如果出现错误，则 MFC 会引发 CInternetException 类型的异常。

CFtpConnection::CreateDirectory

调用此成员函数以在连接的服务器上创建目录。

BOOL CreateDirectory(LPCTSTR pstrDirName);

参数

pstrDirName
一个指针，指向包含要创建的目录名称的字符串。

返回值

如果成功，则不为 0；否则为 0。 如果调用失败，可能会调用 Windows 函数 GetLastError 以确定错误原因。

备注

使用 GetCurrentDirectory 确定此服务器连接的当前工作目录。 请勿假定远程系统已将你连接到根目录。

pstrDirName 参数可以是部分或完全限定的文件名（相对于当前目录）。 反斜杠 (\) 或正斜杠 (/) 可用作任一名称的目录分隔符。 CreateDirectory 在使用目录名称分隔符之前先将其转换为适当的字符。

CFtpConnection::GetCurrentDirectory

调用此成员函数，获取当前目录的名称。

BOOL GetCurrentDirectory(CString& strDirName) const;

BOOL GetCurrentDirectory(
    LPTSTR pstrDirName,
    LPDWORD lpdwLen) const;

参数

strDirName
对将接收目录名称的字符串的引用。

pstrDirName
指向将接收目录名称的字符串的指针。

lpdwLen
指向包含以下信息的 DWORD 的指针：

输入时：pstrDirName 引用的缓冲区大小。

返回时：存储到 pstrDirName 的字符数。 如果成员函数失败并返回 ERROR_INSUFFICIENT_BUFFER，则 lpdwLen 包含字节数，应用程序必须分配该字节数才能接收字符串。

返回值

如果成功，则不为 0；否则为 0。 如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

注解

若要改为以 URL 的形式获取目录名称，请调用 GetCurrentDirectoryAsURL。

参数 pstrDirName 或 strDirName 可以是部分限定文件名（相对于当前目录）或完全限定文件名。 反斜杠 (\) 或正斜杠 (/) 可用作任一名称的目录分隔符。 GetCurrentDirectory 在使用目录名称分隔符之前先将其转换为适当的字符。

CFtpConnection::GetCurrentDirectoryAsURL

调用此成员函数，以 URL 的形式获取当前目录的名称。

BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;

BOOL GetCurrentDirectoryAsURL(
    LPTSTR pstrName,
    LPDWORD lpdwLen) const;

参数

strDirName
对将接收目录名称的字符串的引用。

pstrDirName
指向将接收目录名称的字符串的指针。

lpdwLen
指向包含以下信息的 DWORD 的指针：

输入时：pstrDirName 引用的缓冲区大小。

返回时：存储到 pstrDirName 的字符数。 如果成员函数失败并返回 ERROR_INSUFFICIENT_BUFFER，则 lpdwLen 包含字节数，应用程序必须分配该字节数才能接收字符串。

返回值

如果成功，则不为 0；否则为 0。 如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

备注

GetCurrentDirectoryAsURL 与 GetCurrentDirectory 的行为相同

参数 strDirName 可以是部分限定文件名（相对于当前目录）或完全限定文件名。 反斜杠 (\) 或正斜杠 (/) 可用作任一名称的目录分隔符。 GetCurrentDirectoryAsURL 在使用目录名称分隔符之前先将其转换为适当的字符。

CFtpConnection::GetFile

调用此成员函数，从 FTP 服务器获取文件，并将其存储在本地计算机上。

BOOL GetFile(
    LPCTSTR pstrRemoteFile,
    LPCTSTR pstrLocalFile,
    BOOL bFailIfExists = TRUE,
    DWORD dwAttributes = FILE_ATTRIBUTE_NORMAL,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

参数

pstrRemoteFile
指向以 NULL 结尾的字符串的指针，该字符串包含要从 FTP 服务器检索的文件名。

pstrLocalFile
指向以 NULL 结尾的字符串的指针，该字符串包含要在本地系统上创建的文件的名称。

bFailIfExists
指示文件名是否已被现有文件使用。 如果本地文件名已存在，并且此参数为 TRUE，则 GetFile 失败。 否则，GetFile 将清除文件的现有副本。

dwAttributes
指示文件的属性。 可以是以下 FILE_ATTRIBUTE_* 标志任何组合。

• FILE_ATTRIBUTE_ARCHIVE 文件是存档文件。 应用程序使用此属性来标记要备份或删除的文件。

• FILE_ATTRIBUTE_COMPRESSED 文件或目录已被压缩。 对于文件，压缩意味着文件中的所有数据都会压缩。 对于目录，压缩是新建文件和子目录的默认设置。

• FILE_ATTRIBUTE_DIRECTORY 文件是一个目录。

• FILE_ATTRIBUTE_NORMAL 文件没有设置其他属性。 此属性仅在单独使用时有效。 所有其他文件属性替代 FILE_ATTRIBUTE_NORMAL：

• FILE_ATTRIBUTE_HIDDEN 文件被隐藏。 该文件不会包括在普通的目录列表中。

• FILE_ATTRIBUTE_READONLY 文件是只读文件。 应用程序可以读取该文件，但无法写入或删除该文件。

• FILE_ATTRIBUTE_SYSTEM 文件是操作系统的一部分，或者仅由操作系统使用。

• FILE_ATTRIBUTE_TEMPORARY 文件用于临时存储。 只有绝对必要时，应用程序才应写入文件。 文件的大部分数据保留在内存中，而不会刷新到媒体，因为文件很快就会删除。

dwFlags
指定传输所依据的条件。 此参数可以是 Windows SDK 的 FtpGetFile 中所述的任何 dwFlags 值。

dwContext
文件检索的上下文标识符。 有关 dwContext 的详细信息，请参阅“注解”。

返回值

如果成功，则不为 0；否则为 0。 如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

备注

GetFile 是一个高级例程，用于处理与从 FTP 服务器读取文件并在本地存储文件相关的所有开销。 仅检索文件数据或需要对文件传输进行密切控制的应用程序应改用 OpenFile 和 CInternetFile::Read。

如果 dwFlags 是 FILE_TRANSFER_TYPE_ASCII，则文件数据的转换也会将控制和格式化字符转换为 Windows 等效项。 默认传输是二进制模式，其中文件以与服务器上存储格式相同的格式下载。

pstrRemoteFile 和 pstrLocalFile 可以是部分限定文件名（相对于当前目录）或完全限定文件名。 反斜杠 (\) 或正斜杠 (/) 可用作任一名称的目录分隔符。 GetFile 在使用目录名称分隔符之前先将其转换为适当的字符。

替代 dwContext 默认值，以将上下文标识符设置为所选值。 上下文标识符与其 CInternetSession 对象创建的 CFtpConnection 对象的这个特定操作相关联。 值返回到 CInternetSession::OnStatusCallback，以提供标识它的操作的状态。 有关上下文标识符的详细信息，请参阅 Internet 首要步骤：WinInet 一文。

CFtpConnection::OpenFile

调用此成员函数以打开位于 FTP 服务器上的文件进行读取或写入。

CInternetFile* OpenFile(
    LPCTSTR pstrFileName,
    DWORD dwAccess = GENERIC_READ,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

参数

pstrFileName
一个指针，指向包含要打开文件的名称的字符串。

dwAccess
确定文件的访问方式。 可以是 GENERIC_READ 或 GENERIC_WRITE，但不能同时是两者。

dwFlags
指定后续传输所依据的条件。 可以是以下任一 FTP_TRANSFER_* 常量：

• FTP_TRANSFER_TYPE_ASCII 文件传输使用 FTP ASCII (Type A) 传输方法。 将控件和格式设置信息转换为本地等效项。

• FTP_TRANSFER_TYPE_BINARY 文件使用 FTP 的 Image (Type I) 传输方法传输数据。 文件完全按照其存在的方式传输数据，没有任何更改。 这是默认传输方法。

dwContext
用于打开文件的上下文标识符。 有关 dwContext 的详细信息，请参阅“注解”。

返回值

指向 CInternetFile 对象的指针。

注解

OpenFile 应在以下情况下使用：

• 应用程序具有需要在 FTP 服务器上作为文件发送和创建的数据，但该数据不在本地文件中。 OpenFile 打开文件后，应用程序使用 CInternetFile::Write 将 FTP 文件数据发送到服务器。

• 应用程序必须从服务器检索文件并将其放入应用程序控制的内存中，而不是将其写入磁盘。 应用程序在使用 OpenFile 打开文件后使用 CInternetFile::Read。

• 应用程序需要对文件传输进行精细的控制。 例如，应用程序可能想要在下载文件时显示一个进度控件，以指示文件传输状态的进度。

在调用 OpenFile 之后以及调用 CInternetFile::Close 前，应用程序只能调用 CInternetFile::Read、CInternetFile::Write、CInternetConnection::Close 或 CFtpFileFind::FindFile。 对同一 FTP 会话的其他 FTP 函数的调用将失败，并会将错误代码设置为 FTP_ETRANSFER_IN_PROGRESS。

pstrFileName 参数可以是部分限定文件名（相对于当前目录）或完全限定文件名。 反斜杠 (\) 或正斜杠 (/) 可用作任一名称的目录分隔符。 OpenFile 在使用之前将目录名称分隔符转换为适当的字符。

替代 dwContext 默认值，以将上下文标识符设置为所选值。 上下文标识符与其 CInternetSession 对象创建的 CFtpConnection 对象的这个特定操作相关联。 值返回到 CInternetSession::OnStatusCallback，以提供标识它的操作的状态。 有关上下文标识符的详细信息，请参阅 Internet 首要步骤：WinInet 一文。

CFtpConnection::PutFile

调用此成员函数，将文件存储在 FTP 服务器上。

BOOL PutFile(
    LPCTSTR pstrLocalFile,
    LPCTSTR pstrRemoteFile,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

参数

pstrLocalFile
一个指针，指向包含要从本地系统发送的文件名称的字符串。

pstrRemoteFile
一个指针，指向包含要在 FTP 服务器上创建的文件名称的字符串。

dwFlags
指定文件传输发生的条件。 可以是 OpenFile 中描述的任何 FTP_TRANSFER_* 常量。

dwContext
用于放置文件的上下文标识符。 有关 dwContext 的详细信息，请参阅“注解”。

返回值

如果成功，则不为 0；否则为 0。 如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

备注

PutFile 是一个高级例程，用于处理与在 FTP 服务器上存储文件相关联的所有操作。 对于仅发送数据或需要更密切地控制文件传输的应用程序，应使用 OpenFile 和 CInternetFile::Write。

替代 dwContext 默认值，以将上下文标识符设置为所选值。 上下文标识符与其 CInternetSession 对象创建的 CFtpConnection 对象的这个特定操作相关联。 值返回到 CInternetSession::OnStatusCallback，以提供标识它的操作的状态。 有关上下文标识符的详细信息，请参阅 Internet 首要步骤：WinInet 一文。

CFtpConnection::Remove

调用此成员函数，从连接的服务器中删除指定的文件。

BOOL Remove(LPCTSTR pstrFileName);

参数

pstrFileName
一个指针，指向包含要删除文件的名称的字符串。

返回值

如果成功，则不为 0；否则为 0。 如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

备注

pstrFileName 参数可以是部分限定文件名（相对于当前目录）或完全限定文件名。 反斜杠 (\) 或正斜杠 (/) 可用作任一名称的目录分隔符。 Remove 函数在使用目录名称分隔符之前先将其转换为适当的字符。

CFtpConnection::RemoveDirectory

调用此成员函数，从连接的服务器中移除指定的目录。

BOOL RemoveDirectory(LPCTSTR pstrDirName);

参数

pstrDirName
一个指针，指向包含要移除的目录的字符串。

返回值

如果成功，则不为 0；否则为 0。 如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

注解

使用 GetCurrentDirectory 确定服务器的当前工作目录。 请勿假定远程系统已将你连接到根目录。

pstrDirName 参数可以是部分或完全限定的文件名（相对于当前目录）。 反斜杠 (\) 或正斜杠 (/) 可用作任一名称的目录分隔符。 RemoveDirectory 在使用目录名称分隔符之前先将其转换为适当的字符。

CFtpConnection::Rename

调用此成员函数，重命名连接服务器上的指定文件。

BOOL Rename(
    LPCTSTR pstrExisting,
    LPCTSTR pstrNew);

参数

pstrExisting
一个指针，指向包含要重命名的文件名称的字符串。

pstrNew
指向包含文件的新名称的字符串的指针。

返回值

如果成功，则不为 0；否则为 0。 如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

注解

pstrExisting 和 pstrNew 参数可以是部分限定文件名（相对于当前目录）或完全限定文件名。 反斜杠 (\) 或正斜杠 (/) 可用作任一名称的目录分隔符。 Rename 在使用目录名称分隔符之前先将其转换为适当的字符。

CFtpConnection::SetCurrentDirectory

调用此成员函数，更改为 FTP 服务器上的其他目录。

BOOL SetCurrentDirectory(LPCTSTR pstrDirName);

参数

pstrDirName
指向包含目录名称的字符串的指针。

返回值

如果成功，则不为 0；否则为 0。 如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

备注

pstrDirName 参数可以是部分或完全限定的文件名（相对于当前目录）。 反斜杠 (\) 或正斜杠 (/) 可用作任一名称的目录分隔符。 SetCurrentDirectory 在使用目录名称分隔符之前先将其转换为适当的字符。

使用 GetCurrentDirectory 确定 FTP 服务器的当前工作目录。 请勿假定远程系统已将你连接到根目录。

另请参阅

CInternetConnection 类
层次结构图
CInternetConnection 类
CInternetSession 类