WindowsAPI “奇葩”的函数传参方式

前段时间使用windows SDK中的wininet写http客户端。遇到了一些个”奇葩”的API函数，InternetSetOption和InternetQueryOption。看看MSDN上这两个API的函数原型：

BOOL InternetSetOption(

  _In_  HINTERNET hInternet,

  _In_  DWORD dwOption,

  _In_  LPVOID lpBuffer,

  _In_  DWORD dwBufferLength

);

BOOL InternetQueryOption(

  _In_     HINTERNET hInternet,

  _In_     DWORD dwOption,

  _Out_    LPVOID lpBuffer,

  _Inout_  LPDWORD lpdwBufferLength

);

这两个函数是用来设置和查询internet选项的。比如代理IP、超时值、最大连接数等等几十种选项都是靠这两个函数来完成设置与查询。第一个参数是标识一个网络连接的句柄，如果为NULL则对全局internet选项进行操作。第二个参数是要设置的选项类型。有几十种选项类型，具体可参阅：

http://msdn.microsoft.com/en-us/library/windows/desktop/aa385328(v=vs.85).aspx

第三、四个参数我一直无法理解，一个void指针和一个DWORD指针。要怎么用呢。

如果要设置或查询代理IP，调用这个函数的时候我们得把字符串传递进去，如果要设置或查询超时值，我们得把整型变量传递进去。按理说这个函数应该写N种重载形式，以对应不同的选项。但要知道，可设置、查询的选项有几十种，近百种。很多选项要传递的参数类型都是不同的，有字符串型的、整型的，还有各种各样的自定义结构体。如果要写几十种，近百种函数重载形式，未免太麻烦了。微软在这里偷了个懒，当然，可能也是有他自己的考虑。他用void*作形参使得任何类型的参数都能传入，但是各种数据类型的大小是不一样的，于是便用第四个参数DWORD，告诉他你传入的参数有多大。

那么，要设置超时值的时候，我们这样用：

DWORD dwTimeOut = 30000;
InternetSetOption(NULL,INTERNET_OPTION_CONNECT_TIMEOUT,&dwTimeOut,sizeof(dwTimeOut));

要设置代理IP时，我们这样用：

INTERNET_PROXY_INFO info;
info.dwAccessType = INTERNET_OPEN_TYPE_PROXY;
info.lpszProxy = "192.168.1.250:8080";
info.lpszProxyBypass = "192.168.1.250:8080";
InternetSetOption(NULL,INTERNET_OPTION_PROXY,&info,sizeof(info));

是不是很巧妙，这个void*使得我们可以根据不同的选项，传入不用的数据类型，当然，第四个参数，我们得告诉他我们传入的数据类型有多大。

要查询超时值的时候，我们这样用：

DWORD dwTimeOut,dwSize = sizeof(dwTimeOut);
InternetQueryOption(NULL,INTERNET_OPTION_CONNECT_TIMEOUT,&dwTimeOut,&dwSize);

你会发现InternetQueryOption和InternetSetOption的第四个参数是不同的，InternetQueryOption的第四个参数是DWORD的指针。为什么这里要用指针，因为调用InternetQueryOption的时候，你是要获取数据，调用的时候，你告诉API你第三个参数有多大，能容纳多少字节的数据。函数返回的时候，API会修改你第四个参数传进去的变量为实际写入的字节数。上面dwTimeOut是32位无符号整型，能容纳4个字节的数据。假如你传递进去的dwSize是5，那么调用后dwSize将变成4，因为实际只写入了4个字节的数据。假如你传递进去的dwSize是3，那么函数将调用失败。

也许你会很疑惑，不就一个DWORD吗，有必要那么麻烦吗？试想，如果你需要InternetQueryOption返回一个字符串，第三个参数传递一个char*进去，这种机制会变得非常有用。

要查询代理IP时，我们这样用：

DWORD dwSize=0;
//第三个参数为NULL，第一次调用，我们的目的是为了知道需要多大的缓冲区
InternetQueryOption(NULL,INTERNET_OPTION_PROXY,NULL,&dwSize);
LPINTERNET_PROXY_INFO pInfo = (LPINTERNET_PROXY_INFO)malloc(dwSize);
//第二次调用，获取数据
InternetQueryOption(NULL,INTERNET_OPTION_PROXY,pInfo,&dwSize);
free(pInfo);

当然，我们也可以在栈上分配足够大的缓冲区，而不用先调用一次以知道需要多大的缓冲区：

DWORD dwSize=1000; 
byte buff[1000];
LPINTERNET_PROXY_INFO pInfo = (LPINTERNET_PROXY_INFO)buff;
InternetQueryOption(NULL,INTERNET_OPTION_PROXY,pInfo,&dwSize);

运行效果如上图。dwSize为50，说明需要50字节的缓冲区。手动计算一下是不是这样。

INTERNET_PROXY_INFO结构有一个DWORD和两个const char *，总共就是12字节。两串字符串"192.168.1.250:8080"共占用19*2=38字节。加起来刚好50字节。

有趣的是INTERNET_PROXY_INFO结构里的两个const char *是用来保存字符串的。我一开始就纳闷，一个指向常量的指针，他要如何通过这个指针写入字符串。看刚才的代码：

LPINTERNET_PROXY_INFO pInfo = (LPINTERNET_PROXY_INFO)malloc(dwSize);

INTERNET_PROXY_INFO只占用12字节，而我们却分配了50字节的空间，并用INTERNET_PROXY_INFO指针指向它。这两串字符串就是写到了后面这32字节上。

仔细看上图。pInfo的内存地址是0x0012fb58。加12字节，刚好就是0x0012fb64。第一个字符串是紧跟在结构体pInfo之后的。第一个字符串的地址0x0012fb64再加19字节（字符串的长度），刚好是0x0012fb77（注意是十六进制）。

微软的这种API设计真是高啊。不过也有缺点，就是类型检查不严，容易因程序员的疏忽而出错。另一个就是很多程序员刚开始不适应这种API调用方式。随便看了一下MSDN上的函数原型就开始按照自己的想法调用。我一开始就是给INTERNET_PROXY_INFO结构的两个const char *分别分配空间后传入。结果老是调用失败。实际上该如何正确调用，MSDN已经给了明确的说明和示例。

http://msdn.microsoft.com/en-us/library/windows/desktop/aa385384(v=vs.85).aspx

可能是因为MSDN全英文的缘故，很多人都没有仔细看。而是不停的到论坛上发问，这个API该怎么用。实际上MSDN上写的很清楚。包括我在内的广大程序员，都应该加强英文阅读能力啊，不然以后根本混不下去！

微软的API设计，类库的设计，都是非常成熟、优秀的。我们不仅要学会使用API，使用类库，以后还应该学会设计API，设计类库。