共用方式為


winHttpSendRequest 函式 (winHTTP.h)

WinHttpSendRequest 函式會將指定的要求傳送至 HTTP 伺服器。

語法

WINHTTPAPI BOOL WinHttpSendRequest(
  [in]           HINTERNET hRequest,
  [in, optional] LPCWSTR   lpszHeaders,
  [in]           DWORD     dwHeadersLength,
  [in, optional] LPVOID    lpOptional,
  [in]           DWORD     dwOptionalLength,
  [in]           DWORD     dwTotalLength,
  [in]           DWORD_PTR dwContext
);

參數

[in] hRequest

WinHttpOpenRequest 傳回的 HINTERNET 句柄。

[in, optional] lpszHeaders

字串的指標,其中包含要附加至要求的其他標頭。 如果沒有附加其他標頭 ,則可以WINHTTP_NO_ADDITIONAL_HEADERS 此參數。

[in] dwHeadersLength

不帶正負號的長整數值,其中包含其他標頭的長度,以字元為單位。 如果此參數為 -1LpwszHeaders 不是 NULL,則此函式會假設 pwszHeadersnull 終止,並計算長度。

[in, optional] lpOptional

緩衝區的指標,其中包含要在要求標頭之後立即傳送的任何選擇性數據。 此參數通常用於 POST 和 PUT 作業。 選擇性數據可以是張貼至伺服器的資源或數據。 如果沒有選擇性的數據可供傳送 ,則可以WINHTTP_NO_REQUEST_DATA 此參數。

如果 dwOptionalLength 參數為 0,則會忽略此參數並設定為 NULL

此緩衝區必須保持可用狀態,直到要求句柄關閉或 WinHttpReceiveResponse 的呼叫完成為止。

[in] dwOptionalLength

不帶正負號的長整數值,其中包含選擇性數據的長度,以位元組為單位。 如果沒有選擇性數據要傳送,此參數可以是零。

lpOptional 參數不是 NULL 時,此參數必須包含有效的長度。 否則會忽略 lpOptional ,並將 設定為 NULL

[in] dwTotalLength

不帶正負號的長整數值,包含傳送之數據總數的長度,以位元組為單位。 此參數會指定要求的 Content-Length 標頭。 如果此參數的值大於 dwOptionalLength 所指定的長度,則可以使用 WinHttpWriteData 來傳送其他數據。

dwTotalLength 在呼叫 WinHttpSendRequest 時不得變更相同的要求。 如果需要變更 dwTotalLength ,呼叫端應該建立新的要求。

[in] dwContext

指標大小變數的指標,其中包含透過要求句柄傳遞至任何回呼函式的應用程式定義值。

傳回值

如果成功,則傳回 TRUE ,否則傳回 FALSE 。 如需擴充錯誤資訊,請呼叫 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。 在此情況下,應用程式會在 WinHttpSetOptionlpBuffer 參數中指定WINHTTP_NO_CLIENT_CERT_CONTEXT宏。 如需詳細資訊,請參閱 WINHTTP_OPTION_CLIENT_CERT_CONTEXT 選項。Windows Server 2003 SP1、Windows XP SP2 和 Windows 2000: 不支援此錯誤。

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_INVALID_URL
URL 無效。
ERROR_WINHTTP_LOGIN_FAILURE
登入嘗試失敗。 發生此錯誤時,應該使用 WinHttpCloseHandle 關閉要求句柄。 必須先建立新的要求句柄,再重試原本產生此錯誤的函式。
ERROR_WINHTTP_NAME_NOT_RESOLVED
無法解析伺服器名稱。
ERROR_WINHTTP_OPERATION_CANCELLED
作業已取消,通常是因為要求在作業完成之前關閉的句柄。
ERROR_WINHTTP_RESPONSE_DRAIN_OVERFLOW
當傳入回應超過內部 WinHTTP 大小限制時傳回。
ERROR_WINHTTP_SECURE_FAILURE
在伺服器所傳送的安全套接字層 (SSL) 憑證中找到一或多個錯誤。 若要判斷發生何種類型的錯誤,請透過狀態回呼函式中的 WINHTTP_CALLBACK_STATUS_SECURE_FAILURE 通知進行驗證。 如需詳細資訊,請參閱 WINHTTP_STATUS_CALLBACK
ERROR_WINHTTP_SHUTDOWN
WinHTTP 函式支援已關閉或卸除。
ERROR_WINHTTP_TIMEOUT
要求逾時。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
URL 指定了 “HTTP:” 或 “https:” 以外的配置。
ERROR_NOT_ENOUGH_MEMORY
記憶體不足,無法完成要求的作業。 (Windows 錯誤碼)

Windows Server 2003、Windows XP 和 Windows 2000: 使用 [WINHTTP_OPTION_PORT_RESERVATION ] 選項設定的 TCP 保留範圍不夠大,無法傳送此要求。

ERROR_INVALID_PARAMETER
dwTotalLength 參數中指定的內容長度不符合 Content-Length 標頭中指定的長度。

lpOptional 參數必須是 NULL,而且當 Transfer-Encoding 標頭存在時,dwOptionalLength 參數必須是零。

當 Transfer-Encoding 標頭存在時,便無法顯示 Content-Length 標頭。

ERROR_WINHTTP_RESEND_REQUEST
應用程式必須因重新導向或驗證挑戰而呼叫 WinHttpSendRequest

Windows Server 2003 SP1、Windows XP SP2 和 Windows 2000: 不支援此錯誤。

備註

即使 WinHTTP 用於異步模式,也就是說,在 WinHttpOpen 中設定WINHTTP_FLAG_ASYNC時,此函式仍可同步或異步操作。 不論是哪一種情況,如果成功傳送要求,則會呼叫應用程式,並將完成狀態設定為 WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETEWINHTTP_CALLBACK_STATUS_REQUEST_ERROR完成表示作業以異步方式完成,但失敗。 收到 WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE 狀態回呼後,應用程式就可以開始使用 WinHttpReceiveResponse 從伺服器接收回應。 之前,無法呼叫其他異步函式,否則 會傳回ERROR_WINHTTP_INCORRECT_HANDLE_STATE

應用程式不得刪除或改變 lpOptional 指向的緩衝區,直到要求句柄關閉或 WinHttpReceiveResponse 的呼叫完成為止,因為收到回應時可能會遇到需要選擇性數據的驗證挑戰或重新導向。 如果作業必須使用 WinHttpCloseHandle 中止,則應用程式必須讓緩衝區保持有效狀態,直到收到回呼 WINHTTP_CALLBACK_STATUS_REQUEST_ERROR 並出現 ERROR_WINHTTP_OPERATION_CANCELLED 錯誤碼為止。

如果以同步方式使用 WinHTTP,也就是說,在 WinHttpOpen 中未設定WINHTP_FLAG_ASYNC時,即使註冊回呼函式,也不會呼叫具有完成狀態的應用程式。 在此模式中,當 WinHttpSendRequest 傳回時,應用程式可以呼叫 WinHttpReceiveResponse

WinHttpSendRequest 函式會將指定的要求傳送至 HTTP 伺服器,並允許用戶端指定其他標頭以連同要求一起傳送。

此函式也可讓用戶端指定選擇性數據,以緊接在要求標頭之後傳送至 HTTP 伺服器。 這項功能通常用於寫入作業,例如 PUT 和 POST。

應用程式可以在對 WinHttpSendRequest 的多個呼叫中使用相同的 HTTP 要求句柄來重新傳送相同的要求,但應用程式必須讀取先前呼叫傳回的所有數據,才能再次呼叫此函式。

會驗證以這個函式新增的要求標頭名稱和值。 標頭的格式必須正確。 如需有關有效 HTTP 標頭的詳細資訊,請參閱 RFC 2616。 如果使用無效的標頭,此函式會失敗, 而且 GetLastError 會傳回 ERROR_INVALID_PARAMETER。 未新增無效的標頭。

Windows 2000: 從多個線程傳送要求時,網路和CPU效能可能會大幅降低。

Windows XP 和 Windows 2000: 請參閱 運行時間需求

WinHttpSetStatusCallback

如果狀態回呼函式已經與 WinHttpSetStatusCallback 一起安裝,則下列在 WinHttpSetStatusCallback參數中設定的下列通知會指出傳送要求的進度:
  • 未實作WINHTTP_CALLBACK_STATUS_DETECTING_PROXY ()
  • 只在異步模式中WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE ()
  • WINHTTP_CALLBACK_STATUS_REDIRECT
  • WINHTTP_CALLBACK_STATUS_SECURE_FAILURE
  • WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE
注意 在 Windows 7 和 Windows Server 2008 R2 上,下列所有通知都已被取代。
 
  • WINHTTP_CALLBACK_STATUS_RESOLVING_NAME
  • WINHTTP_CALLBACK_STATUS_NAME_RESOLVED
  • WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER
  • WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER
  • WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
  • WINHTTP_CALLBACK_STATUS_REQUEST_SENT
  • WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
  • WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
如果伺服器關閉連線,則也會傳送下列通知,前提是這些通知已在 WinHttpSetStatusCallbackdwNotificationFlags 參數中設定:
  • WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION
  • WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

支援大於 4 GB 上傳

從 Windows Vista 和 Windows Server 2008 開始,WinHttp 支援使用 Content-Length 標頭,將檔案的大小上傳至LARGE_INTEGER (2^64 位元組) 。 呼叫 WinHttpSendRequest 中指定的承載長度限制為 DWORD (2^32 個字節的大小) 。 若要將數據上傳至大於 DWORD 的 URL,應用程式必須在要求的 Content-Length 標頭中提供長度。 在此情況下,WinHttp 用戶端應用程式會呼叫 WinHttpSendRequest ,並將 dwTotalLength 參數設定為 WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH

如果 Content-Length 標頭指定長度小於 2^32,應用程式也必須在 WinHttpSendRequest 呼叫中指定內容長度。 如果 dwTotalLength 參數不符合 Content-Length 標頭中指定的長度,則呼叫會失敗並傳回 ERROR_INVALID_PARAMETER

Content-Length 標頭可以在 WinHttpAddRequestHeaders 的呼叫中新增,也可以在 WinHttpSendRequestlpszHeader 參數中指定,如下列程式代碼範例所示。

BOOL fRet = WinHttpSendRequest(
			hReq,
			L"Content-Length: 68719476735\r\n",
			-1L,
			WINHTTP_NO_REQUEST_DATA,
			0,
			WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH,
			pMyContent);

傳輸編碼標頭

從 Windows Vista 和 Windows Server 2008 開始,WinHttp 可讓應用程式對傳送至伺服器的數據執行區塊傳輸編碼。 當 winHttp 要求上存在 Transfer-Encoding 標頭時,WinHttpSendRequest 呼叫中的 dwTotalLength 參數會設定為 WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH,而應用程式會在一或多個對 WinHttpWriteData 的呼叫中傳送實體主體。 WinHttpSendRequestlpOptional 參數必須是 NULL而 dwOptionLength 參數必須是零,否則會傳回ERROR_WINHTTP_INVALID_PARAMETER錯誤。 若要終止區塊式數據傳輸,應用程式會產生零長度區塊,並在最後一次呼叫 WinHttpWriteData 時傳送它。

範例

下列程式代碼範例示範如何取得 HINTERNET 句柄、開啟 HTTP 工作階段、建立要求標頭,並將該標頭傳送至伺服器。

    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, 
                                       0, 0);

    // Place additional code here.


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

    // Close 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 或更新版本。

另請參閱

關於 Microsoft Windows HTTP Services (WinHTTP)

WINHTTP_STATUS_CALLBACK

WinHTTP 版本

WinHttpCloseHandle

WinHttpConnect

WinHttpOpen

WinHttpOpenRequest

WinHttpReceiveResponse