WinHttpWriteData 函数 (winhttp.h)

项目
08/27/2023

WinHttpWriteData 函数将请求数据写入 HTTP 服务器。

语法

WINHTTPAPI BOOL WinHttpWriteData(
  [in]  HINTERNET hRequest,
  [in]  LPCVOID   lpBuffer,
  [in]  DWORD     dwNumberOfBytesToWrite,
  [out] LPDWORD   lpdwNumberOfBytesWritten
);

参数

[in] hRequest

WinHttpOpenRequest 返回的有效 HINTERNET 句柄。等待 WinHttpSendRequest 完成，再调用此函数。

[in] lpBuffer

指向缓冲区的指针，该缓冲区包含要发送到服务器的数据。确保此缓冲区在 WinHttpWriteData 完成后保持有效。

[in] dwNumberOfBytesToWrite

包含要写入文件的字节数的无符号长整数值。

[out] lpdwNumberOfBytesWritten

指向接收写入缓冲区的字节数的无符号长整数变量的指针。 WinHttpWriteData 函数在执行任何工作或错误检查之前将此值设置为零。异步使用 WinHTTP 时，此参数必须设置为 NULL ，并在回调函数中检索信息。否则可能会导致内存故障。

返回值

如果成功，则返回 TRUE ，否则返回 FALSE 。有关扩展的错误信息，请调用 GetLastError。返回的错误代码包括：

错误代码	说明
ERROR_WINHTTP_CONNECTION_ERROR	与服务器的连接已重置或终止，或者遇到不兼容的 SSL 协议。例如，WinHTTP 版本 5.1 不支持 SSL2，除非客户端专门启用 SSL2。
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	无法执行请求的操作，因为提供的句柄未处于正确的状态。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	此操作提供的句柄类型不正确。
ERROR_WINHTTP_INTERNAL_ERROR	发生了内部错误。
ERROR_WINHTTP_OPERATION_CANCELLED	操作被取消，通常是因为操作之前关闭了操作请求的句柄。
ERROR_WINHTTP_TIMEOUT	请求已超时。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法完成请求的操作。 (Windows 错误代码)

备注

即使在异步模式下使用 WinHTTP， (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC，此函数也可以同步或异步运行。如果此函数返回 FALSE，则可以调用 GetLastError 以获取扩展错误信息。如果此函数返回 TRUE，请使用WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE完成来确定此函数是否成功以及参数的值。 WINHTTP_CALLBACK_STATUS_REQUEST_ERROR完成指示操作异步完成，但失败。

警告异步使用 WinHTTP 时，始终将 lpdwNumberOfBytesWritten 参数设置为 NULL ，并检索在回调函数中写入的字节;否则，可能会发生内存故障。

当应用程序发送数据时，它可以调用 WinHttpReceiveResponse 以结束数据传输。如果调用 WinHttpCloseHandle ，则数据传输将中止。

如果状态回调函数已随 WinHttpSetStatusCallback 一起安装，则在 WinHttpSetStatusCallback 的 dwNotificationFlags 参数中设置的以下通知指示向服务器发送数据的进度：

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
WINHTTP_CALLBACK_STATUS_DATA_WRITTEN
WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
WINHTTP_CALLBACK_STATUS_REQUEST_SENT
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

尝试将 (或 PUT) 数据 POST 到使用 NTLM 或协商身份验证进行质询的代理或服务器时，可能会出现两个问题。首先，这些代理或服务器可能会发送 401/407 质询并关闭连接，然后才能对所有数据进行 POST 处理，在这种情况下， 不仅 WinHttpWriteData 会失败，而且 WinHTTP 也无法处理身份验证质询。 NTLM 和 Negotiate 要求在同一套接字连接上交换所有身份验证握手，因此，如果连接过早断开，身份验证将失败。

其次，NTLM 和 Negotiate 可能需要多次握手才能完成身份验证，这要求为每个身份验证段重新 POST 数据。对于大型数据上传，这可能非常低效。

若要解决这两个问题，一种解决方案是先将幂等预热请求（如HEAD）发送到身份验证 v-dir，处理与此请求关联的身份验证质询，然后仅 POST 数据。只要重新使用同一套接字来处理 POST，就不应遇到进一步的身份验证质询，并且可以一次性上传所有数据。由于经过身份验证的套接字只能重复用于同一会话中的后续请求，因此，只要该套接字未与与之竞争的并发请求共用，POST 就应该在同一套接字中退出。

注意对于 Windows XP 和 Windows 2000，请参阅 WinHTTP 起始页的运行时要求部分。

示例

此示例演示将数据写入 HTTP 服务器的代码。示例中提供的服务器名称（www.wingtiptoys.com）是虚构的，必须替换为你对其具有写入访问权限的服务器的名称。

    PCSTR pszData = "WinHttpWriteData Example";
    DWORD dwBytesWritten = 0;
    BOOL  bResults = FALSE;
    HINTERNET hSession = NULL,
              hConnect = NULL,
              hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen(  L"A WinHTTP Example Program/1.0", 
                             WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                             WINHTTP_NO_PROXY_NAME, 
                             WINHTTP_NO_PROXY_BYPASS, 0);

    // Specify an HTTP server.
    if (hSession)
        hConnect = WinHttpConnect( hSession, L"www.wingtiptoys.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

    // Create an HTTP Request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"PUT", 
                                       L"/writetst.txt", 
                                       NULL, WINHTTP_NO_REFERER, 
                                       WINHTTP_DEFAULT_ACCEPT_TYPES, 
                                       0);

    // Send a Request.
    if (hRequest) 
        bResults = WinHttpSendRequest( hRequest, 
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0, 
                                       (DWORD)strlen(pszData), 0);

    // Write data to the server.
    if (bResults)
        bResults = WinHttpWriteData( hRequest, pszData, 
                                     (DWORD)strlen(pszData), 
                                     &dwBytesWritten);

    // End the request.
    if (bResults)
        bResults = WinHttpReceiveResponse( hRequest, NULL);

    // Report any errors.
    if (!bResults)
        printf("Error %d has occurred.\n",GetLastError());


    // Close any open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

要求


最低受支持的客户端	Windows XP、Windows 2000 Professional SP3 [仅限桌面应用]
最低受支持的服务器	Windows Server 2003、Windows 2000 Server SP3 [仅限桌面应用]
目标平台	Windows
标头	winhttp.h
Library	Winhttp.lib
DLL	Winhttp.dll
可再发行组件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。