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 通訊協定。例如，除非用戶端特別啟用 SSL2，否則 WinHTTP 5.1 版不支援 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參數中設定的通知會指出將資料傳送至伺服器時的進度：

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

嘗試 POST (或 PUT) 資料到使用 NTLM 或交涉驗證的 Proxy 或伺服器時，可能會發生兩個問題。首先，這些 Proxy 或伺服器可能會傳送 401/407 挑戰，並在所有資料都可以 POST 之前關閉連線，在此情況下， WinHttpWriteData 不會失敗，也 WinHTTP 無法處理驗證挑戰。 NTLM 和 Negotiate 要求在相同的通訊端連線上結算所有驗證交握，因此如果連線提前中斷，驗證就會失敗。

其次，NTLM 和 Negotiate 可能需要多個交握才能完成驗證，這需要針對每個驗證回合重新張貼資料。對於大型資料上傳而言，這可能會非常沒有效率。

若要解決這兩個問題，其中一個解決方案是先將等冪的準備要求傳送至驗證 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
程式庫	WinHTTP.lib
Dll	Winhttp.dll
可轉散發套件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更新版本。