Share via

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