CInternetFile 类

允许访问使用 Internet 协议的远程系统上的文件。

语法

class CInternetFile : public CStdioFile

成员

受保护构造函数

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

公共方法

名称	描述
CInternetFile::Abort	关闭文件，忽略所有警告和错误。
CInternetFile::Close	关闭 CInternetFile 并释放其资源。
CInternetFile::Flush	刷新写入缓冲区的内容，并确保内存中的数据写入目标计算机。
CInternetFile::GetLength	返回文件的大小。
CInternetFile::Read	读取指定字节数。
CInternetFile::ReadString	读取字符流。
CInternetFile::Seek	在打开的文件中重新定位指针。
CInternetFile::SetReadBufferSize	设置要在其中读取数据的缓冲区的大小。
CInternetFile::SetWriteBufferSize	设置将写入数据的缓冲区的大小。
CInternetFile::Write	写入指定字节数。
CInternetFile::WriteString	向文件写入一个以 null 结尾的字符串。

公共运算符

“属性”	描述
CInternetFile::operator HINTERNET	Internet 句柄的强制转换运算符。

受保护的数据成员

名称	描述
CInternetFile::m_hFile	文件的句柄。

注解

为 CHttpFile 和 CGopherFile 文件类提供基类。 请勿直接创建 CInternetFile 对象。 相反，通过调用 CGoherConnection::OpenFile 或 CHttpConnection::OpenRequest 创建其派生类之一的对象。 还可以通过调用 CFtpConnection::OpenFile 创建一个 CInternetFile 对象。

CInternetFile 成员函数 Open、LockRange、UnlockRange 和 Duplicate 未针对 CInternetFile 实现。 如果在 CInternetFile 对象上调用这些函数，将收到 CNotSupportedException。

若要详细了解 CInternetFile 如何与其他 MFC Internet 类配合工作，请参阅使用 WinInet 进行 Internet 编程一文。

继承层次结构

CObject

CFile

CStdioFile

CInternetFile

要求

标头：afxinet.h

CInternetFile::Abort

关闭与此对象关联的文件并使该文件不可读取或写入。

virtual void Abort();

备注

如果在销毁对象之前尚未关闭文件，析构函数会为你关闭该文件。

在处理异常时，Abort 在两个重要方面不同于 Close。 首先，Abort 函数不会在失败时引发异常，因为它会忽略失败。 其次，如果文件尚未打开或之前已关闭，Abort 不会断言。

CInternetFile::CInternetFile

创建 CInternetFile 对象时会调用此成员函数。

CInternetFile(
    HINTERNET hFile,
    LPCTSTR pstrFileName,
    CInternetConnection* pConnection,
    BOOL bReadMode);

CInternetFile(
    HINTERNET hFile,
    HINTERNET hSession,
    LPCTSTR pstrFileName,
    LPCTSTR pstrServer,
    DWORD_PTR dwContext,
    BOOL bReadMode);

参数

hFile
Internet 文件的句柄。

pstrFileName
指向包含文件名的字符串的指针。

pConnection
指向 CInternetConnection 对象的指针。

bReadMode
指示文件是否为只读文件。

hSession
Internet 会话的句柄。

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

dwContext
CInternetFile 对象的上下文标识符。 有关上下文标识符的详细信息，请参阅 WinInet 基础知识。

备注

请勿直接创建 CInternetFile 对象。 相反，通过调用 CGoherConnection::OpenFile 或 CHttpConnection::OpenRequest 创建其派生类之一的对象。 还可以通过调用 CFtpConnection::OpenFile 创建一个 CInternetFile 对象。

CInternetFile::Close

关闭 CInternetFile 并释放其所有资源。

virtual void Close();

备注

如果已打开文件以供写入，则会隐式调用 Flush 以确保将所有缓冲数据写入主机。 使用完文件后应调用 Close。

CInternetFile::Flush

调用此成员函数以刷新写入缓冲区的内容。

virtual void Flush();

注解

使用 Flush 确保内存中的所有数据确实已写入目标计算机，并确保你已完成与主机的事务。 Flush 仅对打开以供写入的 CInternetFile 对象有效。

CInternetFile::GetLength

返回文件的大小。

virtual ULONGLONG GetLength() const;

CInternetFile::m_hFile

与此对象关联的文件的句柄。

HINTERNET m_hFile;

CInternetFile::operator HINTERNET

使用此运算符获取当前 Internet 会话的 Windows 句柄。

operator HINTERNET() const;

CInternetFile::Read

调用此成员函数以将指定字节数 nCount 读入给定内存（从 lpvBuf 开始）。

virtual UINT Read(
    void* lpBuf,
    UINT nCount);

参数

lpBuf
指向将文件数据读取到的内存地址的指针。

nCount
要写入的字节数。

返回值

传输到缓冲区的字节数。 如果已到达文件末尾，则返回值可能小于 nCount。

注解

函数返回实际读取的字节数（一个数字，在文件结束时可能小于 nCount）。 如果读取文件时出现错误，则函数会引发描述错误的 CInternetException 对象。 请注意，不会将越过文件末尾的读取视为错误，不会引发异常。

若要确保检索所有数据，应用程序必须继续调用 CInternetFile::Read 方法，直到该方法返回零。

CInternetFile::ReadString

调用此成员函数以读取字符流，直到找到换行符。

virtual BOOL ReadString(CString& rString);

virtual LPTSTR ReadString(
    LPTSTR pstr,
    UINT nMax);

参数

pstr
指向将接收正在读取的行的字符串的指针。

nMax
要读取的最大字符数。

rString
对接收读取行的 CString 对象的引用。

返回值

指向包含检索自 CInternetFile 对象的纯数据的缓冲区的指针。 无论传递给此方法的缓冲区的数据类型如何，它都不会对数据执行任何操作（例如转换为 Unicode），因此必须将返回的数据映射到预期的结构，就像void*返回的类型一样。

如果在没有读取任何数据的情况下到达文件尾，则为 NULL；或者，如果是布尔值，在没有读取任何数据的情况下到达文件尾，则为 FALSE。

备注

该函数将生成的行放入 pstr 参数引用的内存中。 当达到由 nMax 指定的最大字符数时，它将停止读取字符。 缓冲区始终接收终止 null 字符。

如果在未先调用 SetReadBufferSize 的情况下调用 ReadString，则会得到一个 4096 字节的缓冲区。

CInternetFile::Seek

调用此成员函数以在以前打开的文件中重新定位指针。

virtual ULONGLONG Seek(
    LONGLONG lOffset,
    UINT nFrom);

参数

lOffset
要移动文件中读/写指针的偏移量（以字节为单位）。

nFrom
偏移量的相对引用。 必须是以下值之一：

• CFile::begin 将文件指针从文件开头向前移动 lOff 个字节。

• CFile::current 将文件指针从文件的当前位置移动 lOff 个字节。

• CFile::end 将文件指针从文件末尾移动 lOff 个字节。 lOff 必须为负值才能搜索现有文件；正值将在文件末尾后面搜索。

返回值

如果请求的位置合法，则为文件开头的新字节偏移量；否则，该值为未定义并会引发 CInternetException 对象。

备注

Seek 函数允许通过将指针绝对或相对移动指定的量来随机访问文件的内容。 在搜索期间，实际上不会读取任何数据。

目前，仅支持与 CHttpFile 对象关联的数据调用此成员函数。 FTP 或 gopher 请求不支持它。 如果为这些不受支持的服务之一调用 Seek，它将传回 Win32 错误代码 ERROR_INTERNET_INVALID_OPERATION。

打开文件时，文件指针位于偏移量 0 处，即文件的开头。

注意

使用 Seek 可能会致使隐式调用 Flush。

示例

请参阅基类实现示例 (CFile::Seek)。

CInternetFile::SetReadBufferSize

调用此成员函数来设置由 CInternetFile 派生的对象使用的临时读取缓冲区的大小。

BOOL SetReadBufferSize(UINT nReadSize);

参数

nReadSize
所需的缓冲区大小（以字节为单位）。

返回值

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

备注

基础 WinInet API 不执行缓冲，因此请选择一个缓冲区大小，使应用程序能够高效读取数据，而不管要读取的数据量如何。 如果每次调用 Read 通常都会涉及大量数据（例如 4 KB 或更多），则你应该不需要缓冲区。 但是，如果调用 Read 来获取小块数据，或者如果使用 ReadString 一次读取单个行，则读取缓冲区会提高应用程序的性能。

默认情况下，CInternetFile 对象不为读取提供任何缓冲。 如果调用此成员函数，则必须确保已打开文件以进行读取访问。

可以随时增加缓冲区大小，但收缩缓冲区将不起作用。 如果在未先调用 SetReadBufferSize 的情况下调用 ReadString，则会得到一个 4096 字节的缓冲区。

CInternetFile::SetWriteBufferSize

调用此成员函数来设置由 CInternetFile 派生的对象使用的临时写入缓冲区的大小。

BOOL SetWriteBufferSize(UINT nWriteSize);

参数

nWriteSize
缓冲区的大小（字节）。

返回值

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

备注

基础 WinInet API 不执行缓冲，因此请选择一个缓冲区大小，使应用程序能够高效写入数据，而不管要写入的数据量如何。 如果每次调用 Write 通常都会涉及大量数据（例如 4 KB 或更多），则你应该不需要缓冲区。 但是，如果调用 Write 来写入小块数据，则写入缓冲区可提高应用程序的性能。

默认情况下，CInternetFile 对象不为写入提供任何缓冲。 如果调用此成员函数，则必须确保已打开文件以进行写入访问。 可以随时更改写入缓冲区的大小，但这样做会导致隐式调用 Flush。

CInternetFile::Write

调用此成员函数以将指定字节数 nCount 写入给定内存 lpvBuf。

virtual void Write(
    const void* lpBuf,
    UINT nCount);

参数

lpBuf
指向要写入的第一个字节的指针。

nCount
指定要写入的字节数。

备注

如果在写入数据时发生任何错误，该函数会引发一个描述错误的 CInternetException 对象。

CInternetFile::WriteString

此函数将以 null 结尾的字符串写入关联文件。

virtual void WriteString(LPCTSTR pstr);

参数

pstr
指向包含要写入内容的字符串的指针。

备注

如果在写入数据时发生任何错误，该函数会引发一个描述错误的 CInternetException 对象。

另请参阅

CStdioFile 类
层次结构图
CInternetConnection 类