公用函数

来源：互联网发布：源码上传工具有哪些编辑：程序博客网时间：2024/04/29 00:31

MSDN 2005 -> Win32 和 COM 开发 -> Networking -> Networking Protocols -> Windows Internet -> About WinINet -> Common Functions

公用函数

FTP、HTTP和Gopher等不同的协议使用一些相同的WinINet函数来处理互联网上的信息。无论应用到什么协议，这些公用函数以一致的方式完成其任务。应用程序可以用这些函数来创建处理跨越不同协议的任务(如在FTP、HTTP和Gopher协议中读取文件)的通用函数。

公用函数可以完成下列任务：

从互联网下载资源(InternetReadFile、InternetSetFilePointer、InternetFindNextFile和InternetQueryDataAvailable)
建立异步操作(InternetSetStatusCallback)
查看和修改选项(InternetSetOption和InternetQueryOption)
关闭所有类型的HINTERNET句柄(InternetCloseHandle)
锁定和解锁资源(InternetLockRequestFile和InternetUnlockRequestFile)

使用公用函数

下表列出了WinINet中的公用函数，它们可以用于不同类型的HINTERNET句柄，或者用于不同类型的会话。

函数描述 InternetFindNextFile 继续文件枚举或者搜索。要求使用FtpFindFirstFile、GopherFindFirstFile或者InternetOpenUrl创建的句柄。 InternetLockRequestFile 锁定要使用的文件。要求使用FtpOpenFile、GopherOpenFile、HttpOpenRequest或者InternetOpenUrl创建的句柄。 InternetQueryDataAvailable 获取可用数据量。要求使用FtpOpenFile、GopherOpenFile或者HttpOpenRequest创建的句柄。 InternetQueryOption 获取选项设置 InternetReadFile 从URL读取数据。要求使用InternetOpenUrl、FtpOpenFile、GopherOpenFile或者HttpOpenRequest创建的句柄。 InternetSetFilePointer 设置下次文件读取位置。要求使用InternetOpenUrl(仅对HTTP URL)或者使用GET动作的HttpOpenRequest创建的句柄。 InternetSetOption 设置选项。 InternetSetStatusCallback 设置用于接收状态信息的回调函数。回调函数被分配给指定的HINTERNET句柄以及继承自它的所有句柄。 InternetUnlockRequestFile 解锁使用InternetLockRequestFile锁定的文件。

读取文件

InternetReadFile函数用于从InternetOpenUrl、FtpOpenFile、GopherOpenFile或者HttpOpenRequest返回的HINTERNET句柄下载资源。它接受一个指向缓冲区的void指针，以及一个指向包含缓冲区尺寸的变量的指针。函数在缓冲区中返回数据，还返回下载到缓冲区的数据量大小。

WinINet提供了两种下载整个资源的技术：

使用InternetQueryDataAvailable函数
使用InternetReadFile的返回值

InternetQueryDataAvailable要求传入由InternetOpenUrl、FtpOpenFile、GopherOpenFile或者HttpOpenRequest(在句柄上调用HttpSendRequest之后)创建的HINTERNET句柄，并返回可用数据量。随后应用程序应该为InternetReadFile分配大小为可用字节数加1(用于表示结束的空字符)的缓冲区。这个方法不总是管用的，因为InternetQueryDataAvailable检查的是列在头部中的文件大小，而不是实际文件大小。头部文件中的信息可能已经过期，或者缺少头文件，因为当前不是所有标准都要求有头文件。

下面的例子读取通过hResource句柄访问的资源内容，并显示到编辑框intCtrlID中。

<…… 省略示例代码 ……>

InternetReadFile在所有可用数据已经读取后会成功返回0字节。这样，可以在一个循环中使用InternetReadFile下载数据，然后在它成功返回0字节的时候退出循环。

下面的例子从互联网读取资源并显示到intCtrlID编辑框中。hInternet是从IneternetOpenUrl、FtpOpenFile、GopherOpenFile或者HttpOpenRequest(在调用HttpSendRequest之后)返回的HINTERNET句柄。

<…… 省略示例代码 ……>

查找下一个文件

InternetFindNextFile使用搜索参数和从FtpFindFirstFile、GopherFindFirstFile或者InternetOpenUrl返回的HINTERNET句柄来在搜索中查找下一个文件。要完成搜索，需要不断调用InternetFindNextFile，直到调用失败，GetLastError返回的扩展错误为ERROR_NO_MORE_FILES为止。

下面的例子在列表框lstDirectory中显示一个FTP目录的内容。hConnect是InternetConnect函数在建立一个FTP会话后返回的HINTERNET句柄。

<…… 省略示例代码 ……>

选项操作

InternetSetOption和InternetQueryOption用于操作WinINet选项。

InternetSetOption接受一个指明要设置的选项的变量、一个存放选项设置的缓冲区和一个指向含有缓冲区长度的变量的指针。

InternetQueryOption接受一个指示要获取的选项的变量、一个存放选项设置的缓冲区和一个指向含有缓冲区长度的变量的指针。

建立异步操作

缺省情况下，WinINet函数进行同步操作。通过在InternetOpen函数中设置INTERNET_FLAG_ASYNC标志，可以请求进行异步操作。这样，继承自InternetOpen返回的句柄的句柄上的所有后续操作都成为异步的了。

与同步操作相比较，异步操作的基本优势在于可以使单线程程序不需要等待网络I/O完成，最大化对CPU的使用。然而，操作可能同步或者异步完成，这跟请求有关。应该程序应该检查返回值。如果函数返回FALSE或者NULL，并且GetLastError返回ERROR_IO_PENDING，则请求成为异步的了，在操作完成时程序会收到INTERNET_STATUS_REQUEST_COMPLETE回调。

要发起异步操作，除了要在InternetOpen调用中设置INTERNET_FLAG_ASYNC标志外，还需要用InternetSetStatusCallback注册一个有效的回调函数。

在创建句柄时提供不为零的上下文值，并且注册了回调函数后，句柄上的所有操作都可以产生状态指示。即使在InternetOpen调用中使用了INTERNET_FLAG_ASYNC标志，如果提供的上下文值为零，操作还是被强制同步完成。

状态指示是给应用程序的关于网络操作进度的反馈，比如说，正在解析主机名、正在连接到服务器、正在接收数据等。句柄上可能有三种类型的特殊状态指示：

INTERNET_STATUS_HANDLE_CLOSING 是句柄上的最后一个状态指示
INTERNET_STATUS_HANDLE_CREATED 指示句柄刚刚被创建
INTERNET_STATUS_REQUEST_COMPLETE 指示某异步操作已经完成

在收到INTERNET_STATUS_REQUEST_COMPLETE状态指示时，应用程序应该检查INTERNET_ASYNC_RESULT结构体来确定操作是成功完成还是失败完成。

下面的例子展示了一个回调函数，以及一个把它注册成回调函数的InternetSetStatusCallback调用。

<…… 省略示例代码 ……>

关闭HINTERNET句柄

所有类型的HINTERNET句柄都可以通过InternetCloseHandle关闭。关闭句柄前必须先关闭所有继承自它的句柄。

下面的例子展示了按层次关闭句柄：

<…… 省略示例代码 ……>

锁定和解锁资源

InternetLockRequestFile可以确保与传给它的HINTERNET句柄相关的资源不会从缓存中消失。如果其他下载请求提交与被锁定文件具有相同URL的资源，缓存会通过安全删除来避免移除文件。程序调用InternetUnlockRequestFile后，缓存才被赋予删除文件的权限。

如果设置了INTERNET_FLAG_NO_CACHE_WRITE或者INTERNET_FLAG_DONT_CACHE标志，而且给定的句柄不是连接到HTTPS资源的，InternetLockRequestFile会创建扩展名为TMP的临时文件。如果在设置了这两个标志时访问https资源，InternetLockRequestFile会失败。

今天你菊子曰了么？