共用方式為


WinHttpOpenRequest 函式 (winhttp.h)

WinHttpOpenRequest 函式會建立 HTTP 要求句柄。

語法

WINHTTPAPI HINTERNET WinHttpOpenRequest(
  [in] HINTERNET hConnect,
  [in] LPCWSTR   pwszVerb,
  [in] LPCWSTR   pwszObjectName,
  [in] LPCWSTR   pwszVersion,
  [in] LPCWSTR   pwszReferrer,
  [in] LPCWSTR   *ppwszAcceptTypes,
  [in] DWORD     dwFlags
);

參數

[in] hConnect

WINHttpConnect 所傳回之 HTTP 工作階段的 HINTERNET 連線句柄。

[in] pwszVerb

字串的指標,其中包含要求中使用的 HTTP 動詞 命令。 如果此參數為 NULL,則函式會使用 GET 作為 HTTP 動詞命令注意 此字串應該是全部大寫。 許多伺服器會將 HTTP 動詞視為區分大小寫,而因特網工程工作組 (IETF) 批註要求 (RFC) 使用大寫字元來拼字這些動詞。

[in] pwszObjectName

字串的指標,其中包含指定之 HTTP 動詞命令的目標資源名稱。 這通常是檔名、可執行模組或搜尋規範。

[in] pwszVersion

包含 HTTP 版本的字串指標。 如果此參數為 NULL,則函式會使用 HTTP/1.1。

[in] pwszReferrer

字串的指標,指定從中取得 要求 pwszObjectName 中 URL 的檔 URL。 如果此參數設定為 WINHTTP_NO_REFERER,則不會指定參照檔。

[in] ppwszAcceptTypes

字串指標的 Null 終止陣列指標,指定用戶端接受的媒體類型。 如果此參數設定為 WINHTTP_DEFAULT_ACCEPT_TYPES,則用戶端不會接受任何類型。 通常,伺服器會處理缺少接受的類型,表示用戶端只接受 「text/*」 類型的檔;也就是說,只有文本文件,沒有圖片或其他二進位檔。 如需有效的媒體類型清單,請參閱IANA http://www.iana.org/assignments/media-types/在定義的媒體類型。

[in] dwFlags

包含因特網旗標值的不帶正負號長整數值。 可為下列一或多個值:

意義
WINHTTP_FLAG_BYPASS_PROXY_CACHE
此旗標提供與 WINHTTP_FLAG_REFRESH相同的行為。
WINHTTP_FLAG_ESCAPE_DISABLE
針對 pwszObjectName 傳入之 URL 中的不安全字元不會轉換成逸出序列。
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY
針對 pwszObjectName 傳入之 URL 查詢元件中的不安全字元不會轉換成逸出序列。
WINHTTP_FLAG_ESCAPE_PERCENT
針對 pwszObjectName 傳入的字串會從 LPCWSTR 轉換為 LPSTR。 所有不安全字元都會轉換成逸出序列,包括百分比符號。 根據預設,除了百分比符號以外的所有不安全字元都會轉換成逸出序列。
WINHTTP_FLAG_NULL_CODEPAGE
針對 pwszObjectName 傳入的字串假設是由 WCHAR 所代表的有效 ANSI 字元所組成。 不安全字元不會進行檢查。

Windows 7: 此選項已過時。

WINHTTP_FLAG_REFRESH
表示要求應該轉送至原始伺服器,而不是從 Proxy 伺服器傳送快取的資源版本。 使用此旗標時,會將 「Pragma: no-cache」 標頭新增至要求句柄。 建立 HTTP/1.1 要求標頭時,也會新增 “Cache-Control: no-cache”。
WINHTTP_FLAG_SECURE
使用安全交易語意。 這轉譯成使用安全套接字層 (SSL) /傳輸層安全性 (TLS) 。

傳回值

如果成功,則傳回有效的 HTTP 要求句柄,否則傳回 NULL 。 如需擴充的錯誤資訊,請呼叫 GetLastError。 傳回的錯誤碼如下。

錯誤碼 描述
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
此作業所提供的句柄類型不正確。
ERROR_WINHTTP_INTERNAL_ERROR
發生內部錯誤。
ERROR_WINHTTP_INVALID_URL
URL 無效。
ERROR_WINHTTP_OPERATION_CANCELLED
作業已取消,通常是因為作業完成之前,要求已關閉的句柄。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
URL 指定了 “HTTP:” 或 “https:” 以外的配置。
ERROR_NOT_ENOUGH_MEMORY
記憶體不足,無法完成要求的作業。 (Windows 錯誤碼)

備註

傳回值表示成功或失敗。 若要取得擴充的錯誤資訊,請呼叫 GetLastError

WinHttpOpenRequest 函式會建立新的 HTTP 要求句柄,並將指定的參數儲存在該句柄中。 HTTP 要求句柄會保留傳送至 HTTP 伺服器的要求,並包含所有要作為要求一部分傳送的 RFC822/MIME/HTTP 標頭。

如果 pwszVerb 設定為 “HEAD”,則會忽略 Content-Length 標頭。

如果已使用 WinHttpSetStatusCallback 安裝狀態回呼函式,則 WINHTTP_CALLBACK_STATUS_HANDLE_CREATED 通知表示 WinHttpOpenRequest 已建立要求句柄。

呼叫應用程式使用 WinHttpOpenRequest 傳回的 HINTERNET 句柄完成之後,必須使用 WinHttpCloseHandle 函式來關閉它。

注意 針對 Windows XP 和 Windows 2000,請參閱 WinHttp 起始頁的 運行時間需求 一節。
 

範例

此範例示範如何取得 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 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、具有 SP3 的 Windows 2000 Server [僅限傳統型應用程式]
目標平台 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 版本

WinHttpConnect

WinHttpOpen