描述

 

WinHttpSendRequest功能将指定的请求发送到HTTP服务器。

 

C / C ++语法

 

 

PowerBASIC 语法

 

 

参数

 

hRequest

 

[in]由WinHttpOpenRequest返回的HINTERNET句柄。

 

pwszHeaders

 

[in, optional]指向一个字符串的指针，该字符串包含附加标头以附加到请求。如果没有额外的标题来附加，此参数可以是WINHTTP_NO_ADDITIONAL_HEADERS。

 

dwHeadersLength

 

[in]无符号长整数值，其中包含附加标题的长度（以字符为单位）。如果此参数为-1 &（&HFFFFFFFF）和pwszHeaders不为NULL，则此函数假定pwszHeaders为空终止，并计算长度。

 

lpOptional

 

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

 

如果dwOptionalLength参数为0，则忽略此参数并将其设置为NULL。

 

该缓冲区必须保持可用，直到请求句柄关闭或对WinHttpReceiveResponse的调用完成。

 

dwOptionalLength

 

[in]无符号长整数值，其包含可选数据的长度（以字节为单位）。如果没有可选数据发送，该参数可以为零。

 

当lpOptional参数不是NULL时，此参数必须包含有效的长度。否则，lpOptional将被忽略并设置为NULL.

 

dwTotalLength

 

[in]无符号长整型值，包含发送总数据的长度（以字节为单位）。此参数指定请求的Content-Length头。如果此参数的值大于dwOptionalLength指定的长度，则可以使用WinHttpWriteData发送其他数据。

 

dwContext

 

[in]指向一个指针大小的变量的指针，该变量包含一个应用程序定义的值，该值与请求句柄一起传递给任何回调函数。

 

返回值

 

如果成功，返回一个有效的会话句柄，否则返回NULL。要检索扩展错误信息，请调用GetLastError.返回的错误代码有：

 

ERROR_WINHTTP_CANNOT_CONNECT

 

如果与服务器的连接失败返回。

 

ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED

 

安全HTTP服务器需要客户端证书。该应用程序通过使用WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST选项调用WinHttpQueryOption来检索证书颁发者列表。

 

如果服务器请求客户端证书但不要求它，则应用程序可以使用WINHTTP_OPTION_CLIENT_CERT_CONTEXT选项来调用WinHttpSetOption.在这种情况下，应用程序在WinHttpSetOption的lpBuffer参数中指定WINHTTP_NO_CLIENT_CERT_CONTEXT宏。有关详细信息，请参阅WINHTTP_OPTION_CLIENT_CERT_CONTEXT选项。

 

Windows Server 2003 SP1和Windows XP SP2： 不支持此错误。

 

ERROR_WINHTTP_CONNECTION_ERROR

 

与服务器的连接已重置或终止，或遇到不兼容的SSL协议。例如，WinHTTP版本5.1不支持SSL2，除非客户端专门启用它。

 

ERROR_WINHTTP_INCORRECT_HANDLE_STATE

 

所请求的操作不能执行，因为提供的手柄不在正确的状态。

 

ERROR_WINHTTP_INCORRECT_HANDLE_TYPE

 

提供的手柄类型对于此操作是不正确的。

 

ERROR_WINHTTP_INTERNAL_ERROR

 

发生内部错误。

 

ERROR_WINHTTP_INVALID_URL

 

网址无效

 

ERROR_WINHTTP_LOGIN_FAILURE

 

登录尝试失败。遇到此错误时，应使用WinHttpCloseHandle关闭请求句柄。必须先创建一个新的请求句柄，然后再重试最初产生此错误的函数。

 

ERROR_WINHTTP_RESPONSE_DRAIN_OVERFLOW

 

传入响应超过内部WinHTTP大小限制时返回。

 

ERROR_WINHTTP_SECURE_FAILURE

 

在服务器发送的安全套接字层（SSL）证书中发现一个或多个错误。要确定遇到什么类型的错误，请检查状态回调函数中的WINHTTP_CALLBACK_STATUS_SECURE_FAILURE通知。有关详细信息，请参阅WINHTTP_STATUS_CALLBACK.

 

ERROR_WINHTTP_SHUTDOWN

 

 

ERROR_WINHTTP_TIMEOUT

 

请求已超时。

 

ERROR_WINHTTP_UNRECOGNIZED_SCHEME

 

URL指定了除“http：”或“https：”之外的方案。

 

ERROR_NOT_ENOUGH_MEMORY

 

没有足够的内存来完成请求的操作。（Windows错误代码）

 

ERROR_INVALID_PARAMETER

 

dwTotalLength参数中指定的内容长度与Content-Length标头中指定的长度不匹配。（Windows错误代码）

 

dwTotalLength参数中指定的内容长度与Content-Length标头中指定的长度不匹配。

 

当传输编码头部存在时，lpOptional参数必须为NULL，并且dwOptionalLength参数必须为零。

 

当Transfer-Encoding头部存在时，Content-Length头不能出现。

 

ERROR_WINHTTP_RESEND_REQUEST

 

由于重定向或身份验证问题，应用程序必须重新调用WinHttpSendRequest.

 

Windows Server 2003 SP1和Windows XP SP2： 不支持此错误。

 

备注

 

即使在异步模式下使用WinHTTP，也就是说，当WinHttpOpen中设置了WINHTTP_FLAG_ASYNC时，该函数可以同步或异步操作。在任一情况下，如果请求成功发送，则应用程序将返回，并将完成状态设置为WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE。WINHTTP_CALLBACK_STATUS_REQUEST_ERROR完成表示操作异步完成但失败。收到WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE状态回调后，应用程序可以开始从WinHttpReceiveResponse的服务器接收响应。在此之前，不能调用其他异步函数，否则返回ERROR_WINHTTP_INCORRECT_HANDLE_STATE。

 

应用程序不得删除或更改lpOptional指向的缓冲区，直到请求句柄关闭或者对WinHttpReceiveResponse的调用已经完成，因为在接收响应过程中可能会遇到需要可选数据的身份验证挑战或重定向。如果操作必须使用WinHttpCloseHandle中止，应用程序必须保持缓冲区有效，直到接收到具有ERROR_WINHTTP_OPERATION_CANCELLED错误代码的回调WINHTTP_CALLBACK_STATUS_REQUEST_ERROR为止。

 

如果WinHTTP同步使用，即在WinHttpOpen中未设置WINHTP_FLAG_ASYNC时，即使注册了回调函数，也不会调用应用程序的完成状态。在此模式下，当WinHttpSendRequest返回时，应用程序可以调用WinHttpReceiveResponse.

 

WinHttpSendRequest函数将指定的请求发送到HTTP服务器，并允许客户端指定要与请求一起发送的附加头。

 

此函数还允许客户端指定可选数据，以便在请求标头之后立即发送到HTTP服务器。此函数通常用于写操作，如PUT和POST。

 

应用程序可以在多次调用WinHttpSendRequest中使用相同的HTTP请求句柄来重新发送相同的请求，但是应用程序必须再次调用此函数之前，先读取上一次调用返回的所有数据。

 

使用此函数添加的请求标头的名称和值将被验证。标题必须形成良好。有关有效HTTP标头的更多信息，请参阅RFC 2616。如果使用无效头，则此函数失败，GetLastError返回ERROR_INVALID_PARAMETER.无法添加无效标题。

 

如果已使用WinHttpSetStatusCallback安装了状态回调函数，那么在WinHttpSetStatusCallback的dwNotificationFlags参数中设置的以下通知的状态回显函数表示发送请求的进度：

 

 

如果服务器关闭连接，则还会发送以下通知，前提是它们已在WinHttpSetStatusCallback的dwNotificationFlags参数中设置：

 

 

对于在Windows 2000操作系统上运行的计算机，当从多个线程发送请求时，可能会显着降低网络和CPU性能。有关详细信息，请参阅Q282865 - Winsock关机可以将CPU使用率提高到100％.

 

支持大于4 GB的上传

 

从Windows Vista和Windows Server“Longhorn”开始，WinHttp支持使用Content-Length头文件上传大小为LARGE_INTEGER（2 ^ 64字节）的文件。调用WinHttpSendRequest中指定的有效负载长度限制为DWORD（2 ^ 32字节）的大小。要将数据上传到大于DWORD的URL，应用程序必须在请求的Content-Length头部中提供长度。在这种情况下，WinHttp客户端应用程序调用{??989796360}dwTotalLength参数设置为WINHTTP_IGNORE_TOTAL_LENGTH。

 

如果Content-Length标头指定的长度小于2 ^ 32，则应用程序还必须在调用WinHttpSendRequest中指定内容长度。如果dwTotalLength参数与Content-Length头部中指定的长度不匹配，则调用失败并返回ERROR_INVALID_PARAMETER。

 

Content-Length头可以在WinHttpAddRequestHeaders的调用中添加，或者可以在WinHttpSendRequest的lpszHeader参数中指定，如下面的代码示例所示。

 

LOCAL fRet as LONG

LOCAL wszHeaders AS WSTRINGZ * 260

strHeaders = ”内容长度：68719476735 \\ r \\ n ”

fRet = WinHttpSendRequest（_

           HREQ，_

                      wszHeaders, _

                      -1&, _

                      %WINHTTP_NO_REQUEST_DATA, _

                      0, _

                      %WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH, _

                      pMyContent)

 

传输编码标题

 

从Windows Vista和Windows Server“Longhorn”开始，WinHttp使应用程序能够对发送到服务器的数据执行分块传输编码。当WinHttp请求中存在Transfer-Encoding标头时，调用WinHttpSendRequest中的dwTotalLength参数设置为WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH，并且应用程序将一个或多个调用中的实体主体发送到WinHttpWriteData.WinHttpSendRequest的lpOptional参数必须为NULL，并且dwOptionLength参数必须为零，否则返回ERROR_WINHTTP_INVALID_PARAMETER错误。要终止分块数据传输，应用程序将生成一个零长度块，并将其发送到最后一次调用WinHttpWriteData.