WINHTTP的API接口说明。

时间:2022-07-06 21:56:55

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]

主机的port;

取值:

INTERNET_DEFAULT_HTTP_PORT      默认的HTTPport80。

INTERNET_DEFAULT_HTTPS_PORT      默认的HTTPSport443。能够通过调用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输入包括username,password,或两者。假设函数失败,由于一个无效的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输入包括username,password,或两者。假设函数失败,由于一个无效的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无法指定代理,找不到代理server错误。

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定位不到代理server。

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未搜索到或server返回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       攻克了全部不使用代理server的主机名。

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不使用路由代理。

能够使用通配符字串,不要使用空字符串,假设指定为"<local>"宏作为入口,该功能通过不论什么主机。

假设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

);

作用:函数返回的server所支持的授权方案。

參数:

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      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         server连接失败。

ERROR_WINHTTP_CHUNKED_ENCODING_HEADER_SIZE_OVERFLOW    

ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED       请求须要进行授权认证。

ERROR_WINHTTP_CONNECTION_ERROR         server重置或关闭或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操作。

可选的数据能够被发送到server的资源或数据。假设没有可选的数据发送这參数能够是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        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]

证书的username

pwszPassword [in]

证书的password

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       当检測到server时激活该通知。

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      当接收到一个来自server的消息中间状态代码(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]

发送到server的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     server响应无效。 

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     操作将异步完毕。

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