WINHTTP

原文地址：http://blog.sina.com.cn/s/blog_b74670be0102v3yd.html

WinHTTP的全称是Microsoft Windows HTTP Services, 它提供给开发者一个HTTP客户端应用程序接口(API), 通过这种API借助HTTP协议给其他的HTTP服务器发送请求.

 

WinHTTP支持桌面应用程序, Windows系统服务, 和Windows服务器端应用程序.对于基于Microsoft .NET Framework的应用程序, 不推荐使用WinHTTP服务, 因为.NET Framework应用程序应该使用在System.Net命名空间下的网络基础设施类型.WinHTTP提供了两种编程方式, 一种是C\C++的API, 另一种是COM组件.

 

WinHTTP Functions

BOOL WINAPI WinHttpAddRequestHeaders(
  _In_  HINTERNET hRequest,
  _In_  LPCWSTR pwszHeaders,
  _In_  DWORD dwHeadersLength,
  _In_  DWORD dwModifiers
);
作用：添加一个HTTP的请求头域。
参数说明：
hRequest [in]
一个HINTERNET句柄通过调用WinHttpOpenRequest返回。

pwszHeaders [in]
请求的头域字符串，每个头域(多个头域以)使用回车换行(\r\n)结束

dwHeadersLength [in]
无符号长整型变量，指向pwszHeaders的长度，如果该参数为(ulong)-1L时，自动以"/0"结束来计算pwszHeaders的长度。

dwModifiers [in]
头域的修改模式。包括如下值：
WINHTTP_ADDREQ_FLAG_ADD       添加一个头域，如果头域存在时值将被新添加的值替换。与WINHTTP_ADDREQ_FLAG_REPLAC一起使用
WINHTTP_ADDREQ_FLAG_ADD_IF_NEW     添加一个不存在头域，如果该头域存在则返回一个错误。
WINHTTP_ADDREQ_FLAG_COALESCE     将同名的头域进行合并。
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA   合并同名的头域，值使用逗号隔开。
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON  合并同名的头域，值使用分号隔开。
WINHTTP_ADDREQ_FLAG_REPLACE      替换和删除一个头域，如果值为空，则删除，否则被替换。

返回值为假时，使用getlasterror来得到错误信息。
err code:
ERROR_WINHTTP_INCORRECT_HANDLE_STATE   请求不能被执行，因为句柄的状态不正确
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE    请求的句柄类型不正确
ERROR_WINHTTP_INTERNAL_ERROR     内部错误
ERROR_NOT_ENOUGH_MEMORY       没有足够的内存来完成操作。

 

BOOL WinHttpCheckPlatform(void);
作用：判断是否是微软支持的平台。
返回值：TRUE支持，否则不支持。

BOOL WINAPI WinHttpCloseHandle(
  _In_  HINTERNET hInternet
);
作用：关闭一个HINTERNET句柄。
参考：
hInternet [in]
待关闭HINTERNET的句柄。

当返回false时可以调用getlasterror来得到相关信息。
err code:
ERROR_WINHTTP_SHUTDOWN       winhttp已关闭或卸载
ERROR_WINHTTP_INTERNAL_ERROR     INTERNAL错误
ERROR_NOT_ENOUGH_MEMORY       内存不够

 

HINTERNET WINAPI WinHttpConnect(
  _In_        HINTERNET hSession,
  _In_        LPCWSTR pswzServerName,
  _In_        INTERNET_PORT nServerPort,
  _Reserved_  DWORD dwReserved
);
作用：建立一个http的连接会话。
参数：
hSession [in]
通过调用winHttpOpen返回的session句柄。

pswzServerName [in]
主机或域名。可以有IP地址也可以是站点域名。

nServerPort [in]
主机的端口;
取值：
INTERNET_DEFAULT_HTTP_PORT      默认的HTTP端口80。
INTERNET_DEFAULT_HTTPS_PORT      默认的HTTPS端口443。可以通过调用WinHttpOpenRequest函数中的WINHTTP_FLAG_SECURE 开启HTTPS
INTERNET_DEFAULT_PORT       默认HTTP为80，HTTPS为443

dwReserved [in]
保留参数，设置为0;

返回值：如果调用成功则返回一个HTTP连接会话的句柄，否则为NULL，为NULL时可以调用getlasterror查看。
err code：
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE    句柄的类型不正确。
ERROR_WINHTTP_INTERNAL_ERROR     INTERNAL错误。
ERROR_WINHTTP_INVALID_URL      无效的URL
ERROR_WINHTTP_OPERATION_CANCELLED    操作被取消，通常用于操作完成前。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME    URL不能被识别或不支持。
ERROR_WINHTTP_SHUTDOWN       winhttp已关闭或卸载
ERROR_NOT_ENOUGH_MEMORY       内存不够

 

BOOL WINAPI WinHttpCrackUrl(
  _In_     LPCWSTR pwszUrl,
  _In_     DWORD dwUrlLength,
  _In_     DWORD dwFlags,
  _Inout_  LPURL_COMPONENTS lpUrlComponents
);
作用：分离host和路径
参数：
pwszUrl [in]
将正确规范的URL进行分离，但不对URL做有效性验证。

dwUrlLength [in]
pwszUrl的长度，如果设为0，则默认pwszUrl字符以NULL结束来计算长度。

dwFlags [in]
操作标识，可取值：
ICU_DECODE          字符转换，但不解编码，如UTF-8。如果使用，可以通过传入URL_COMPONENTS结构。
ICU_ESCAPE          忽略字符转议，同样可以传入URL_COMPONENTS结构进行设置。
ICU_REJECT_USERPWD        拒绝的URL输入包含用户名，密码，或两者。如果函数失败，因为一个无效的URL，随后调用GetLastError函数将返回ERROR_WINHTTP_INVALID_URL的。

lpUrlComponents [in, out]
指向URL_COMPONENTS 结构的指针

返回值：
当返回false时可以调用getlasterror来得到相关信息。
err code:
ERROR_WINHTTP_INTERNAL_ERROR    
ERROR_WINHTTP_INVALID_URL     
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
ERROR_NOT_ENOUGH_MEMORY

 

DWORD WinHttpCreateProxyResolver(
  _In_   HINTERNET hSession,
  _Out_  HINTERNET *phResolver
);
作用：创建代理解释器
参数：
hSession [in]
成功调用WinHttpOpen返回的句柄。该句柄必须打开WINHTTP_FLAG_ASYNC标识。

phResolver [out]
通过调用WinHttpGetProxyForUrlEx返回的一个新句柄。当完成或取消时可调用WinHttpCloseHandle来关闭。

返回值：返回操作的状态
ERROR_SUCCESS          操作成功
ERROR_INVALID_HANDLE        hSession 为NULL
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE     hSession 不是调用 WinHttpOpen 返回或 hSession 没有开启异步标识 WINHTTP_FLAG_ASYNC

 

BOOL WINAPI WinHttpCreateUrl(
  _In_     LPURL_COMPONENTS lpUrlComponents,
  _In_     DWORD dwFlags,
  _Out_    LPWSTR pwszUrl,
  _Inout_  LPDWORD lpdwUrlLength
);
作用：创建一个URL。
参数：
lpUrlComponents [in]
指向一个包含要创建的URL的 URL_COMPONENTS 结构体指针

dwFlags [in]
操作模式，取值：
ICU_ESCAPE          转换结构体中的lpszUrlPath 和 lpszExtraInfo中的所有不安全的转议字符。
ICU_REJECT_USERPWD        拒绝的URL输入包含用户名，密码，或两者。如果函数失败，因为一个无效的URL，随后调用GetLastError函数将返回ERROR_WINHTTP_INVALID_URL的。

pwszUrl [out]
指向一个宽字节的字符串。

lpdwUrlLength [in, out]
设定可以接收pwszUrl字符的长度。

返回值：
当返回false时可以调用getlasterror来得到相关信息。
err code:
ERROR_WINHTTP_INTERNAL_ERROR
ERROR_NOT_ENOUGH_MEMORY

BOOL WINAPI WinHttpDetectAutoProxyConfigUrl(
  _In_   DWORD dwAutoDetectFlags,
  _Out_  LPWSTR *ppwszAutoConfigUrl
);
作用：删除自动代理配置的URL
参数：
dwAutoDetectFlags [in]
使用本地PAC文件协议，如果DHCP和DNS都被检测到，则优先使用DHCP，如果PAC URL 使用DHCP检测不到再使用DNS。
取值：
WINHTTP_AUTO_DETECT_TYPE_DHCP       使用DHCP
WINHTTP_AUTO_DETECT_TYPE_DNS_A       使用DNS

ppwszAutoConfigUrl [out]
返回一个代理数据URL的宽字节字符串，必须调用 GlobalFree 来释放该字符串。

返回值：
当返回false时可以调用getlasterror来得到相关信息。
err code:
ERROR_WINHTTP_AUTODETECTION_FAILED      返回WinHTTP的代理自动配置（PAC）文件是无法发现的URL。
ERROR_WINHTTP_INTERNAL_ERROR
ERROR_NOT_ENOUGH_MEMORY

VOID WINAPI WinHttpFreeProxyResult(
  _Inout_  WINHTTP_PROXY_RESULT *pProxyResult
);
作用：释放代理
参数：
pProxyResult [in, out]
指向 WINHTTP_PROXY_RESULT 结构的指针，该结构调用 WinHttpGetProxyResult得到。

BOOL WINAPI WinHttpGetDefaultProxyConfiguration(
  _Inout_  WINHTTP_PROXY_INFO *pProxyInfo
);
作用：获了以默认代理配置。
参数：
pProxyInfo [in, out]
指向WINHTTP_PROXY_INFO结构的指针。

返回值：
当返回false时可以调用getlasterror来得到相关信息。
err code:
ERROR_WINHTTP_INTERNAL_ERROR
ERROR_NOT_ENOUGH_MEMORY

 

BOOL WINAPI WinHttpGetIEProxyConfigForCurrentUser(
  _Inout_  WINHTTP_CURRENT_USER_IE_PROXY_CONFIG *pProxyConfig
);
作用：得到当前用户的IE代理配置
参数：
pProxyConfig [in, out]
指向WINHTTP_CURRENT_USER_IE_PROXY_CONFIG 结构的指针，作为传出参数时，包括当前IE网络连接的代理配置信息。如VPN，LAN, 拔号连接等。

返回值：
当返回false时可以调用getlasterror来得到相关信息。
err code:
ERROR_FILE_NOT_FOUND      IE设置文件没有发现。
ERROR_WINHTTP_INTERNAL_ERROR
ERROR_NOT_ENOUGH_MEMORY

 

BOOL WINAPI WinHttpGetProxyForUrl(
  _In_   HINTERNET hSession,
  _In_   LPCWSTR lpcwszUrl,
  _In_   WINHTTP_AUTOPROXY_OPTIONS *pAutoProxyOptions,
  _Out_  WINHTTP_PROXY_INFO *pProxyInfo
);
作用：通过URL得到代理信息。
参数：
hSession [in]
通过调用WinHttpOpen函数返回的hSession句柄。

lpcwszUrl [in]
宽字节的URL

pAutoProxyOptions [in]
指向使用自动代理选项的WINHTTP_AUTOPROXY_OPTIONS 结构体指针。

pProxyInfo [out]
指向 WINHTTP_PROXY_INFO 结构的指针。这信结构体将应用到WINHTTP_OPTION_PROXY结构中的option项。
释放结构中的lpszProxy和lpszProxyBypass字符串，使用  GlobalFree 函数。

返回值：
当返回false时可以调用getlasterror来得到相关信息。
err code:
ERROR_WINHTTP_AUTO_PROXY_SERVICE_ERROR      URL无法指定代理，找不到代理服务器错误。
ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT       在自动代理配置文件中出错PAC文件。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE       句柄类型不正确。
ERROR_WINHTTP_INTERNAL_ERROR        网络异常。
ERROR_WINHTTP_INVALID_URL         URL无效。
ERROR_WINHTTP_LOGIN_FAILURE         登录尝试失败。当遇到此错误时，关闭请求句柄调用WinHttpCloseHandle。必须创建一个新的请求进行重试。
ERROR_WINHTTP_OPERATION_CANCELLED       操作被取消
ERROR_WINHTTP_UNABLE_TO_DOWNLOAD_SCRIPT      找不到PAC文件或返回404 not found。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME       PAC文件指定的URL不是http或https开头的请求
ERROR_NOT_ENOUGH_MEMORY          内存不够

DWORD WinHttpGetProxyForUrlEx(
  _In_  HINTERNET hResolver,
  _In_  PCWSTR pcwszUrl,
  _In_  WINHTTP_AUTOPROXY_OPTIONS *pAutoProxyOptions,
  _In_  DWORD_PTR pContext
);
作用：通过URL获取代理信息。
参数：
hResolver [in]
通过调用WinHttpCreateProxyResolver函数返回的句柄。

pcwszUrl [in]
unicode URL字符串。

pAutoProxyOptions [in]
指向使用自动代理选项的WINHTTP_AUTOPROXY_OPTIONS结构体指针。

pContext [in]
上下文数据将被回调函数进行回调。

返回值：返回操作结果的状态值。
取值：
ERROR_IO_PENDING          异步操作正在进行中。
ERROR_WINHTTP_AUTO_PROXY_SERVICE_ERROR     URL定位不到代理服务器。
ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT      自动代理配置文件出错(PAC)。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE      句柄类型不正确。
ERROR_WINHTTP_INVALID_URL        无效的URL。
ERROR_WINHTTP_OPERATION_CANCELLED      操作被取消。
ERROR_WINHTTP_UNABLE_TO_DOWNLOAD_SCRIPT     URL未搜索到或服务器返回404 not found。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME      PAC文件指定的URL不是http或https开头的请求
ERROR_NOT_ENOUGH_MEMORY

 

DWORD WINAPI WinHttpGetProxyResult(
  _In_   HINTERNET hResolver,
  _Out_  WINHTTP_PROXY_RESULT *pProxyResult
);
作用：获取代理结果。
参数：
hResolver [in]
调用WinHttpGetProxyForUrlEx函数返回的句柄。

pProxyResult [out]
指向WINHTTP_PROXY_RESULT的结构体指针。该结构包括内调用WinHttpGetProxyForUrlEx后得到的代理结果数据，这个结果数据必须调用WinHttpFreeProxyResult进行释放。

返回值：返回操作结果的状态值。
取值：
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE      句柄类型不正确。
ERROR_WINHTTP_INCORRECT_HANDLE_STATE     调用WinHttpGetProxyForUrlEx返回的句柄状态不正确。

 

HINTERNET WINAPI WinHttpOpen(
  _In_opt_  LPCWSTR pwszUserAgent,
  _In_      DWORD dwAccessType,
  _In_      LPCWSTR pwszProxyName,
  _In_      LPCWSTR pwszProxyBypass,
  _In_      DWORD dwFlags
);
作用：HTTP初始化。
参数：
pwszUserAgent [in, optional]
HTTP协议中的User-Agent的字符串变量。

dwAccessType [in]
请求类型，取值：
WINHTTP_ACCESS_TYPE_NO_PROXY       解决了所有不使用代理服务器的主机名。
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY      检测静态代理或注册表配置代理，不继承和不共享IE的代理设置，调用WinHttpSetDefaultProxyConfiguration进行设置。
WINHTTP_ACCESS_TYPE_NAMED_PROXY       通过路由列表指定的名称进行代理。

pwszProxyName [in]
当dwAccessType设置为WINHTTP_ACCESS_TYPE_NAMED_PROXY时，必须指定代理名称，winHttp函数库只支持CERN前缀的HTTP代理。
如果dwAccessType不设置WINHTTP_ACCESS_TYPE_NAMED_PROXY，则该参数必须设置为WINHTTP_NO_PROXY_NAME

pwszProxyBypass [in]
代理的主机名或IP地址，如果dwAccessType设置为WINHTTP_ACCESS_TYPE_NAMED_PROXY不使用路由代理。
可以使用通配符字串，不要使用空字符串，如果指定为""宏作为入口，该功能通过任何主机。
如果dwAccessType不设置为WINHTTP_ACCESS_TYPE_NAMED_PROXY则该参数值必须为WINHTTP_NO_PROXY_BYPASS。

dwFlags [in]
标志值，取值：
WINHTTP_FLAG_ASYNC          默认情况下是同步请求过程，如果使用异步请求，需要调用WinHttpSetStatusCallback来设定回调函数。

返回值：
如果成功返回一个session句柄，否则返回NULL。

HINTERNET WINAPI WinHttpOpenRequest(
  _In_  HINTERNET hConnect,
  _In_  LPCWSTR pwszVerb,
  _In_  LPCWSTR pwszObjectName,
  _In_  LPCWSTR pwszVersion,
  _In_  LPCWSTR pwszReferrer,
  _In_  LPCWSTR *ppwszAcceptTypes,
  _In_  DWORD dwFlags
);
作用：建立一个http请求，返回成功请求句柄。
hConnect [in]
通过调用WinHttpConnect返回的句柄。

pwszVerb [in]
HTTP请求动作，如get,post等，如果设为NULL，则默认为GET请求。

pwszObjectName [in]
包含指定的HTTP请求的目标资源的名称。这通常是一个文件名，可执行模块，或搜索符。

pwszVersion [in]
HTTP的版本，如果为NULL，默认为 HTTP/1.1.

pwszReferrer [in]
指向一个字符串，该字符串指定的文件的URL，该URL的要求填写pwszObjectName。
如果没有设定规定的文件，这参数设置为WINHTTP_NO_REFERER。

ppwszAcceptTypes [in]
设置为WINHTTP_DEFAULT_ACCEPT_TYPES接收类型，默认为纯文本的图片和二进制，如果是多媒体数据接收，需要进行类型指定。请参考：http://www.iana.org/assignments/media-types/

dwFlags [in]
标识，取值：
WINHTTP_FLAG_BYPASS_PROXY_CACHE     与WINHTTP_FLAG_REFRESH的行为相同，进行刷新。
WINHTTP_FLAG_ESCAPE_DISABLE      pwszObjectName中的字符被进行转议。
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY    查询pwszObjectName中的字符需要进行字符转义。
WINHTTP_FLAG_ESCAPE_PERCENT      pwszObjectName中传递的字符串从LPCWSTR转换为LPSTR。所有不安全的字符转换为转义序列，包括百分比符号。默认情况下，所有不安全的百分比符号之外的字符转换为转义序列。
WINHTTP_FLAG_NULL_CODEPAGE      pwszObjectName中的ANSI字符替换为WCHAR字符，不对转议进行检测。
WINHTTP_FLAG_REFRESH       当使用此标志时，一个“的Pragma：no-cache的”头添加到请求句柄。当创建一个HTTP请求头，一个“的Cache-Control：no-cache的”也增加了。
WINHTTP_FLAG_SECURE        启用SSL/TLS安全。

返回值：成功返回请求的句柄，否则为NULL。

 

BOOL WINAPI WinHttpQueryAuthSchemes(
  _In_   HINTERNET hRequest,
  _Out_  LPDWORD lpdwSupportedSchemes,
  _Out_  LPDWORD lpdwFirstScheme,
  _Out_  LPDWORD pdwAuthTarget
);
作用：函数返回的服务器所支持的授权方案。
参数：
hRequest [in]
调用WinHttpOpenRequest返回的句柄。

lpdwSupportedSchemes [out]
当前支持的授权方式，取值：
WINHTTP_AUTH_SCHEME_BASIC      BASIC认证方式。
WINHTTP_AUTH_SCHEME_NTLM      NTLM认证方式。
WINHTTP_AUTH_SCHEME_PASSPORT     PASSPORT认证方式。
WINHTTP_AUTH_SCHEME_DIGEST      DIGEST认证方式。
WINHTTP_AUTH_SCHEME_NEGOTIATE     在NTLM ， Kerberos之间的认证方式。

lpdwFirstScheme [out]
首选授权方式，取值：
WINHTTP_AUTH_SCHEME_BASIC      BASIC认证方式。
WINHTTP_AUTH_SCHEME_NTLM      NTLM认证方式。
WINHTTP_AUTH_SCHEME_PASSPORT     PASSPORT认证方式。
WINHTTP_AUTH_SCHEME_DIGEST      DIGEST认证方式。
WINHTTP_AUTH_SCHEME_NEGOTIATE     在NTLM ， Kerberos之间的认证方式。

pdwAuthTarget [out]
授权目标，取值：
WINHTTP_AUTH_TARGET_SERVER      服务器授权。
WINHTTP_AUTH_TARGET_PROXY      代理授权。

返回值：TRUE or FALSE。

BOOL WINAPI WinHttpQueryDataAvailable(
  _In_   HINTERNET hRequest,
  _Out_  LPDWORD lpdwNumberOfBytesAvailable
);
作用：请求返回的数据量，以字节为位进行读取。
参数：
hRequest [in]
调用WinHttpOpenRequest返回的句本。在调用WinHttpQueryDataAvailable之前，必须先调用WinHttpReceiveResponse。

lpdwNumberOfBytesAvailable [out]
字节流数据，如果设置为异步接收，则这里为NULL，通过回调函数进行处理。

返回值：TRUE or FALSE。

BOOL WINAPI WinHttpQueryHeaders(
  _In_      HINTERNET hRequest,
  _In_      DWORD dwInfoLevel,
  _In_opt_  LPCWSTR pwszName,
  _Out_     LPVOID lpBuffer,
  _Inout_   LPDWORD lpdwBufferLength,
  _Inout_   LPDWORD lpdwIndex
);
作用：HTTP头域数据。
参数：
hRequest [in]
调用WinHttpOpenRequest返回的句柄。在使用WinHttpQueryHeaders前必须等WinHttpReceiveResponse调用完成。

dwInfoLevel [in]
类型为DWORD值，指定查询信息标志页上列出的属性和修饰符标志的组合。这些属性和修饰符标志指示被请求的信息，以及它是如何被格式化。

pwszName [in, optional] 可选
头域名，如果dwInfoLevel参数不是WINHTTP_QUERY_CUSTOM，则设置为WINHTTP_HEADER_NAME_BY_INDEX。

lpBuffer [out]
接收该信息的缓冲区的指针。将该参数设置为WINHTTP_NO_OUTPUT_BUFFER导致该函数返回FALSE。调用GetLastError，然后返回ERROR_INSUFFICIENT_BUFFER和lpdwBufferLength包含的字节数必须持有所要求的信息。

lpdwBufferLength [in, out]
指针类型为DWORD的值指定的数据缓冲区的长度，以字节为单位。当函数返回时，此参数包含指针的值，指定的信息写入到缓冲区的长度。
当函数返回字符串，下面的规则适用
1、如果函数调用成功，lpdwBufferLength指定字符串的长度，以字节为单位，减去终止空。
2、如果函数调用失败，则返回ERROR_INSUFFICIENT_BUFFER，lpdwBufferLength指定的字节数，应用程序必须分配给接收字符串。
 
lpdwIndex [in, out]
指针用于列举多个具有相同名称的头一个从零开始的头索引。当调用该函数时，这个参数是返回指定的头的索引。当函数返回时，此参数是该指数下一个标头。
如果无法找到的下一个索引，则返回ERROR_WINHTTP_HEADER_NOT_FOUND。设置此参数WINHTTP_NO_HEADER_INDEX来指定应返回的头，只有第一次出现。

返回值：TRUE or FALSE。

BOOL WINAPI WinHttpQueryOption(
  _In_     HINTERNET hInternet,
  _In_     DWORD dwOption,
  _Out_    LPVOID lpBuffer,
  _Inout_  LPDWORD lpdwBufferLength
);
作用：查询指定的句柄上的“Internet选项”。
参数：
hInternet [in]
HINTERNET句柄上查询信息。注意，这可能是一个会话句柄或请求句柄，这取决于正在查询的选项，选项标志主题，以确定该句柄是适当的使用中查询特定的选项。

dwOption [in]
无符号长整型值，包含的“Internet选项”查询。

lpBuffer [out]
接收选项设置的缓冲区的指针。返回的字符串的WinHttpQueryOption功能在全球范围内分配的，所以当它完成了使用它的调用应用程序必须在全球范围释放该字符串。将该参数设置为NULL，此函数返回FALSE。
调用GetLastError，然后返回ERROR_INSUFFICIENT_BUFFER和lpdwBufferLength包含的字节数必须持有所要求的信息。

lpdwBufferLength [in, out]
指针指向一个无符号长整型变量，它包含lpBuffer的长度，以字节为单位。在函数返回时，该变量接收的数据放入lpBuffer的长度。
如果GetLastError返回ERROR_INSUFFICIENT_BUFFER的，这个参数接收的字节数必须持有所要求的信息。

返回值：TRUE or FALSE。

BOOL WINAPI WinHttpReadData(
  _In_   HINTERNET hRequest,
  _Out_  LPVOID lpBuffer,
  _In_   DWORD dwNumberOfBytesToRead,
  _Out_  LPDWORD lpdwNumberOfBytesRead
);
作用：读取返回的数据。
能数：
hRequest [in]
调用WinHttpOpenRequest返回的句柄。
在调用该函数之前，必须先调用 WinHttpOpenRequest和WinHttpReceiveResponse 或者 WinHttpQueryDataAvailable函数。

lpBuffer [out]
接收数据的缓冲区。

dwNumberOfBytesToRead [in]
缓冲区大小长度。

lpdwNumberOfBytesRead [out]
传出接收的字节数。如果设置为NULL，则调用回调函数进行读取。

返回值：TRUE or FALSE。

BOOL WINAPI WinHttpReceiveResponse(
  _In_        HINTERNET hRequest,
  _Reserved_  LPVOID lpReserved
);
作用：
参数：
hRequest [in]
通过调用WinHttpOpenRequest且调用WinHttpSendRequest返回的句柄等待WinHttpSendRequest发送完成时调用WinHttpReceiveResponse。

lpReserved [in]
预留参数，设置为NULL。

返回值：TRUE or FALSE
err code：
ERROR_WINHTTP_CANNOT_CONNECT         服务器连接失败。
ERROR_WINHTTP_CHUNKED_ENCODING_HEADER_SIZE_OVERFLOW    
ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED       请求需要进行授权认证。
ERROR_WINHTTP_CONNECTION_ERROR         服务器重置或关闭或SSL不兼容。
ERROR_WINHTTP_HEADER_COUNT_EXCEEDED        
ERROR_WINHTTP_HEADER_SIZE_OVERFLOW        调用 WinHttpReceiveResponse 溢出。
ERROR_WINHTTP_INCORRECT_HANDLE_STATE       
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
ERROR_WINHTTP_INTERNAL_ERROR
ERROR_WINHTTP_INVALID_SERVER_RESPONSE
ERROR_WINHTTP_INVALID_URL
ERROR_WINHTTP_LOGIN_FAILURE
ERROR_WINHTTP_NAME_NOT_RESOLVED
ERROR_WINHTTP_OPERATION_CANCELLED
ERROR_WINHTTP_REDIRECT_FAILED
ERROR_WINHTTP_RESEND_REQUEST
ERROR_WINHTTP_RESPONSE_DRAIN_OVERFLOW
ERROR_WINHTTP_SECURE_FAILURE         SSL认证失败。
ERROR_WINHTTP_TIMEOUT
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
ERROR_NOT_ENOUGH_MEMORY

 

DWORD WinHttpResetAutoProxy(
  _In_  HINTERNET hSession,
  _In_  DWORD dwFlags
);
作用：重置自动代理
参数：
hSession [in]
调用WinHttpOpen返回的句柄。

dwFlags [in]
重置标志位，取值：
WINHTTP_RESET_SCRIPT_CACHE          刷新持久的HTTP缓存的代理脚本。
WINHTTP_WRAPPER_RESET_STATE          强制重试网络代理信息。
NHTTP_RESET_OUT_OF_PROC           需要关闭使用WinHttpGetProxyForUrl过程中的缓存需要清除HINTERNET句柄。

返回值：
ERROR_SUCCESS             重置成功。
ERROR_INVALID_HANDLE           hSession句柄无效。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE        hSession不是由WinHttpOpen返回。

 

BOOL WINAPI WinHttpSendRequest(
  _In_      HINTERNET hRequest,
  _In_opt_  LPCWSTR pwszHeaders,
  _In_      DWORD dwHeadersLength,
  _In_opt_  LPVOID lpOptional,
  _In_      DWORD dwOptionalLength,
  _In_      DWORD dwTotalLength,
  _In_      DWORD_PTR dwContext
);
作用：发送请求数据。
参数：
hRequest [in]
调用WinHttpOpenRequest返回的句柄。

pwszHeaders [in, optional]
HTTP请求头域，如果不需要额外的头域，可以设置为：WINHTTP_NO_ADDITIONAL_HEADERS

dwHeadersLength [in]
头域的长度，如果设置为-1L则，将以字符"/0"结束来计算头域的长度。

lpOptional [in, optional]
一个指针，指向一个缓冲区，其中包含可选的数据发送后，立即请求标头。该参数通常用于POST和PUT操作。
可选的数据可以被发送到服务器的资源或数据。如果没有可选的数据发送这参数可以是WINHTTP_NO_REQUEST_DATA的。

如果为0，则参数被忽略，置为NULL。

缓冲区的生命周期必须在调用WinHttpReceiveResponse完成后进行关闭。

dwOptionalLength [in]
如果没有数据发送时，设置为0。
如果lpOptional不为空时，则这个值必须有意义，否则将被忽略变为NULL。

dwTotalLength [in]
无符号长整型值，包含的总发送的数据的长度，以字节为单位。此参数指定Content-Length头的要求。
如果这个参数的值是大于由dwOptionalLength指定的长度，然后WinHttpWriteData可以用于发送额外的数据。

dwContext [in]
一个指针变量，它包含一个应用程序定义的值传递，请求句柄，任何回调函数的指针。

返回值：TRUE or FALSE
err code：
ERROR_WINHTTP_CANNOT_CONNECT
ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED
ERROR_WINHTTP_CONNECTION_ERROR
ERROR_WINHTTP_INCORRECT_HANDLE_STATE
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
ERROR_WINHTTP_INTERNAL_ERROR
ERROR_WINHTTP_INVALID_URL
ERROR_WINHTTP_LOGIN_FAILURE
ERROR_WINHTTP_NAME_NOT_RESOLVED
ERROR_WINHTTP_OPERATION_CANCELLED
ERROR_WINHTTP_RESPONSE_DRAIN_OVERFLOW
ERROR_WINHTTP_SECURE_FAILURE
ERROR_WINHTTP_SHUTDOWN
ERROR_WINHTTP_TIMEOUT
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
ERROR_NOT_ENOUGH_MEMORY
ERROR_INVALID_PARAMETER
ERROR_WINHTTP_RESEND_REQUEST

BOOL WINAPI WinHttpSetCredentials(
  _In_        HINTERNET hRequest,
  _In_        DWORD AuthTargets,
  _In_        DWORD AuthScheme,
  _In_        LPCWSTR pwszUserName,
  _In_        LPCWSTR pwszPassword,
  _Reserved_  LPVOID pAuthParams
);
作用：设置HTTP请求证书。
参数：
hRequest [in]
调用WinHttpOpenRequest返回的句柄。

AuthTargets [in]
授权目标，取值：
WINHTTP_AUTH_TARGET_SERVER        服务器授权
WINHTTP_AUTH_TARGET_PROXY        代理授权

AuthScheme [in]
认证方式，通过 WinHttpQueryAuthSchemes可以得到支持哪些认证方式。
通常有：
WINHTTP_AUTH_SCHEME_BASIC      BASIC认证方式。
WINHTTP_AUTH_SCHEME_NTLM      NTLM认证方式。
WINHTTP_AUTH_SCHEME_PASSPORT     PASSPORT认证方式。
WINHTTP_AUTH_SCHEME_DIGEST      DIGEST认证方式。
WINHTTP_AUTH_SCHEME_NEGOTIATE     在NTLM ， Kerberos之间的认证方式。

pwszUserName [in]
证书的用户名

pwszPassword [in]
证书的密码

pAuthParams [in]
保留参数，设置为NULL。

返回值：TRUE or FALSE
err code：
ERROR_WINHTTP_INCORRECT_HANDLE_STATE
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
ERROR_WINHTTP_INTERNAL_ERROR
ERROR_NOT_ENOUGH_MEMORY

BOOL WINAPI WinHttpSetDefaultProxyConfiguration(
  _In_  WINHTTP_PROXY_INFO *pProxyInfo
);
作用：设置默认代理配置。
参数：
pProxyInfo [in]
一个指向WINHTTP_PROXY_INFO的结构体指针。

返回值：TRUE or FALSE
err code：
ERROR_WINHTTP_INTERNAL_ERROR
ERROR_NOT_ENOUGH_MEMORY

BOOL WINAPI WinHttpSetOption(
  _In_  HINTERNET hInternet,
  _In_  DWORD dwOption,
  _In_  LPVOID lpBuffer,
  _In_  DWORD dwBufferLength
);
作用：IE选项设置。
参数：
hInternet [in]
会话或请求句柄。

dwOption [in]
IE选项，值参考： Option Flags 。

lpBuffer [in]
选项缓冲区。

dwBufferLength [in]
无符号长整型值，包含lpBuffer缓冲区的长度。下列选项中指定的字符缓冲区的长度;所有其他选项，指定的长度（以字节为单位）。

返回值：TRUE or FALSE

WINHTTP_STATUS_CALLBACK WINAPI WinHttpSetStatusCallback(
  _In_        HINTERNET hInternet,
  _In_        WINHTTP_STATUS_CALLBACK lpfnInternetCallback,
  _In_        DWORD dwNotificationFlags,
  _Reserved_  DWORD_PTR dwReserved
);
作用：设置回调函数来得到请求状态。
参数：
hInternet [in]
需要设置回调函数的句柄。

lpfnInternetCallback [in]
回调函数指针，如果设置为NULL，则不使用回调。回调函数声明参考WINHTTP_STATUS_CALLBACK

typedef void ( CALLBACK *WINHTTP_STATUS_CALLBACK)(
  _In_  HINTERNET hInternet,
  _In_  DWORD_PTR dwContext,
  _In_  DWORD dwInternetStatus,
  _In_  LPVOID lpvStatusInformation,
  _In_  DWORD dwStatusInformationLength
);

dwNotificationFlags [in]
回调函数事件通知标识。
取值：
WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS       任何处理完成的通知。
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS       任何状态改变时激活通知。
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME        解释名称完成时激活通知。
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER       当连接到服务时激活该通知。
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY       当检测到服务器时激活该通知。
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE       当获到数据时激知该通知。     
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE       当返回响应头时激活该通知。
WINHTTP_CALLBACK_FLAG_READ_COMPLETE        当数据读取完成时激活通知。
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR        当异步操作请求错误时激活通知。
WINHTTP_CALLBACK_FLAG_SEND_REQUEST        当通过调用WinHttpSendRequest开始发送时激活该通知。
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE      当通过调用WinHttpSendRequest发送完成时激活该通知。
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE       当POST数据操作完成时激活该通知。
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE       当Response响应接收资源时激活该通知。      
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION       当正在关闭连接时激活该通知。
WINHTTP_CALLBACK_FLAG_HANDLES         当HTTP连接创建或关闭时激活通知。
WINHTTP_CALLBACK_FLAG_REDIRECT         当请求重定向时激活通知。
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE      当接收到一个来自服务器的消息中间状态代码（100level）时激活通知。
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE       当证书认证失败时激活该通知。

dwReserved [in]
保留参数，设置为NULL。

返回值：
如果调用成功则返回CALLBACK的函数指针，如果失败返回WINHTTP_INVALID_STATUS_CALLBACK，则调用getlasterror来查询信息。

BOOL WINAPI WinHttpSetTimeouts(
  _In_  HINTERNET hInternet,
  _In_  int dwResolveTimeout,
  _In_  int dwConnectTimeout,
  _In_  int dwSendTimeout,
  _In_  int dwReceiveTimeout
);
作用：设置HTTP请求超时。
参数：
hInternet [in]
通过WinHttpOpen 或 WinHttpOpenRequest返回的句柄。

dwResolveTimeout [in]
设置处理请求超时时间，以毫秒为单位，如果为0，表示不使用超时。
Windows Vista和Windows XP：如果DNS超时时间使用NAME_RESOLUTION_TIMEOUT指定的，是每个请求一个线程的开销。

dwConnectTimeout [in]
设置连接超时时间，以毫秒为单位，默认为60秒。

dwSendTimeout [in]
设置发送请求的超时时间，默认为30秒。

dwReceiveTimeout [in]
设置响应接收的超时时间，默认为30秒。

返回值：TRUE or FALSE

BOOL WINAPI WinHttpTimeFromSystemTime(
  _In_   const SYSTEMTIME *pst,
  _Out_  LPWSTR pwszTime
);
作用：格式化系统时间。
参数：
pst [in]
指向SYSTEMTIME 结构的指针。

pwszTime [out]
缓冲区，缓冲区的大小与WINHTTP_TIME_FORMAT_BUFSIZE相等。

返回值：TRUE or FALSE

BOOL WINAPI WinHttpTimeToSystemTime(
  _In_   LPCWSTR pwszTime,
  _Out_  SYSTEMTIME *pst
);
作用：将本地时间转为系统时间。
参数：
pwszTime [in]
指向一个时间格式的字符串， 这个时间格式必须符合RFC2616中的3.3章节中的格式。

pst [out]
指向转换后的系统时间SYSTEMTIME结构指针。

返回值：TRUE or FALSE

BOOL WINAPI WinHttpWriteData(
  _In_   HINTERNET hRequest,
  _In_   LPCVOID lpBuffer,
  _In_   DWORD dwNumberOfBytesToWrite,
  _Out_  LPDWORD lpdwNumberOfBytesWritten
);
作用：写内存数据。
参数：
hRequest [in]
调用WinHttpOpenRequest返回的句柄。 在调用该方法前必须等待函数 WinHttpSendRequest 调用完成。

lpBuffer [in]
发送到服务器的BUFFER数据，确保数据的有效性必须直到WinHttpWriteData调用完成。

dwNumberOfBytesToWrite [in]
需要写入的数据长度。

lpdwNumberOfBytesWritten [out]
写完成的buffer大小，如果设置为NULL，则使用异步的方式时需要在回调中进行写入。

返回值：TRUE or FALSE

DWORD WINAPI WinHttpWebSocketClose(
  _In_      HINTERNET hWebSocket,
  _In_      USHORT usStatus,
  _In_opt_  PVOID pvReason,
  _In_      DWORD dwReasonLength
);
作用：关闭WEB 的SOCKET
参数：
hWebSocket [in]
web socket句柄。注：如果调用了WinHttpCloseHandle来关闭该句柄，则不用再次调用该函数来关闭。

usStatus [in]
状态代码，见 WINHTTP_WEB_SOCKET_CLOSE_STATUS 中的具体值。

pvReason [in, optional]
详细的关闭原因。

dwReasonLength [in]
原因内容的长度。如果为0。则大为小0-123 即124长度。

 

HINTERNET WINAPI WinHttpWebSocketCompleteUpgrade(
  _In_      HINTERNET hRequest,
  _In_opt_  DWORD_PTR pContext
);
作用：WEBSOCKET更新完成。
hRequest [in]
http 请求句柄。

pContext [in, optional]
上下文关联的新句柄。

返回值：
返回新的WebSocket句柄。

DWORD WINAPI WinHttpWebSocketQueryCloseStatus(
  _In_   HINTERNET hWebSocket,
  _Out_  USHORT *pusStatus,
  _Out_  PVOID pvReason,
  _In_   DWORD dwReasonLength,
  _Out_  DWORD *pdwReasonLengthConsumed
);
作用：WEBSOCKET关闭状态查询。
参数：
hWebSocket [in]
WebSocket句柄。

pusStatus [out]
状态码，见WINHTTP_WEB_SOCKET_CLOSE_STATUS列表中的值。

pvReason [out]
关闭的原因。

dwReasonLength [in]
原因内容的长度。

pdwReasonLengthConsumed [out]
如果pvReason为空且dwReasonLength为0，则此值将包含由调用应用程序需要分配的缓冲区的大小。

返回值：
如果成功返回NO_ERROR 。
如果失败返回：
ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_OPERATION
ERROR_INVALID_PARAMETER

DWORD WINAPI WinHttpWebSocketReceive(
  _In_   HINTERNET hWebSocket,
  _Out_  PVOID pvBuffer,
  _In_   DWORD dwBufferLength,
  _Out_  DWORD *pdwBytesRead,
  _Out_  WINHTTP_WEB_SOCKET_BUFFER_TYPE *peBufferType
);
作用：接收数据。
参数：
hWebSocket [in]
WebSocket句柄。

pvBuffer [out]
接收数据的缓冲区。

dwBufferLength [in]
缓冲区长度。

pdwBytesRead [out]
读取数据操作，如果调用WinHttpWebSocketReceive 返回NO_ERROR 且句柄为同步模式。

peBufferType [out]
缓冲区指针，这个设置只有当WinHttpWebSocketReceive 同步模式开启且返回NO_ERROR 时才有值。

返回值：
成功调用返回NO_ERROR
失败调用返回错误码：
ERROR_INVALID_OPERATION       操作无效。 
ERROR_INVALID_PARAMETER       参数无效。
ERROR_INVALID_SERVER_RESPONSE     服务器响应无效。 
ERROR_WINHTTP_OPERATION_CANCELLED    操作被取消。

DWORD WINAPI WinHttpWebSocketSend(
  _In_  HINTERNET hWebSocket,
  _In_  WINHTTP_WEB_SOCKET_BUFFER_TYPE eBufferType,
  _In_  PVOID pvBuffer,
  _In_  DWORD dwBufferLength
);
作用：发送数据。
参数：
hWebSocket [in]
websocket句柄。

eBufferType [in]
缓冲区类型，如果不指定WINHTTP_WEB_SOCKET_CLOSE_BUFFER_TYPE，用户需要使用WinHttpWebSocketClose或WinHttpWebSocketShutdown进行关闭连接。

pvBuffer [in]
发送缓冲区，当dwBufferLength为0时，可以设置为NULL。

dwBufferLength [in]
缓冲区的长度。

返回值：
成功返回NO_ERROR
失败返回
ERROR_INVALID_OPERATION       操作无效。
ERROR_INVALID_PARAMETER       参数无效。

DWORD WINAPI WinHttpWebSocketShutdown(
  _In_      HINTERNET hWebSocket,
  _In_      USHORT usStatus,
  _In_opt_  PVOID pvReason,
  _In_      DWORD dwReasonLength
);
作用：关闭SOCKET。
参数：
hWebSocket [in]
WebSocket句柄。

usStatus [in]
参见WINHTTP_WEB_SOCKET_CLOSE_STATUS列表。

pvReason [in, optional]
shutdown的原因。

dwReasonLength [in]
shutdown原因的内容长度。
如果填为NULL，则默信为0-123

返回值：
所有的错误代码表明，底层的TCP连接已中断。

ERROR_IO_PENDING     操作将异步完成。