WinHTTP 中的 HINTERNET 控制碼

  • 發行項

Microsoft Windows HTTP 服務 (WinHTTP) 會使用控制碼來追蹤使用 HTTP 通訊協定時所需的設定和資訊。 每個控制碼都會維護 HTTP 會話、與 HTTP 伺服器的連線或特定資源的相關資訊。 本主題描述各種類型的控制碼、這些控制碼的命名慣例，以及其階層式結構。

關於 HINTERNET 控制碼

WinHTTP 所建立及使用的控制碼稱為 HINTERNET 控制碼。 WinHTTP 函式會傳回無法與其他控制碼交換的 HINTERNET 控制碼，因此無法與 ReadFile 或 CloseHandle等函式搭配使用。 同樣地，其他控制碼不能與 WinHTTP 函式搭配使用。 例如， CreateFile 傳回的控制碼無法傳遞至 WinHttpReadData。 當使用控制碼的 API 呼叫正在進行時，就無法關閉這些 HINTERNET 控制碼。 為了避免競爭狀況，應用程式應該保護控制碼，並防止它關閉，只要 API 呼叫正在進行中即可。

Microsoft Win32 網際網路 (WinInet) 函式也會使用 HINTERNET 控制碼。 不過，WinInet 函式中使用的控制碼無法與 WinHTTP 函式中使用的控制碼交換。 如需 WinInet 的詳細資訊，請參閱 關於 WinINet。

WinHttpCloseHandle函式會關閉 WinHTTP HINTERNET控制碼。

命名控制碼

在 WinHTTP 檔中，應用程式程式設計介面中函式的描述 (API) 和範例程式碼會顯示建立和使用各種類型的 HINTERNET 控制碼。 若要追蹤可用的不同控制碼類型，這些控制碼的命名是一致的。 下表顯示檔中慣例所使用的識別碼。

控制碼類型 函式建立控制碼 識別碼
泛型控制碼 WinHttpOpen、 WinHttpConnect或 WinHttpOpenRequest hInternet
會話控制碼 WinHttpOpen hSession
連接控制碼 WinHttpConnect hConnect
要求控制碼 WinHttpOpenRequest hRequest
Web 通訊端控制碼 WinHttpWebSocketCompleteUpgrade hWebSocket

處理階層

HINTERNET控制碼會在階層中維護。 WinHttpOpen所傳回的控制碼是會話HINTERNET控制碼。 呼叫 WinHttpOpen 會初始化 WinHTTP 函式，並開始會話內容，在整個會話控制碼的生命週期中維護使用者資訊和設定。 WinHttpConnect 會指定目標 HTTP 或 HTTPS 伺服器，並建立連線 HINTERNET 控制碼。 根據預設，連接控制碼會繼承會話控制碼的設定。 使用 呼叫 WinHttpOpenRequest 所指定的每個資源都會指派要求 HINTERNET 控制碼。

下圖說明 HINTERNET 控制碼的階層。 圖表中的每個方塊都代表會傳回 HINTERNET 控制碼的 WinHTTP 函式。

建立控制碼的函式

關閉控制碼之後，應用程式必須準備好接收控制碼上的回呼通知，直到傳回最後 一個WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED 值，以指出控制碼完全關閉 (或直到應用程式執行自己的對等同步處理，例如追蹤和等候擱置非同步作業的任何回呼，並確保不會使用該控制碼進行進一步的作業) 。

會話控制碼稱為用來建立之任何連線控制碼的父代;同樣地，連接控制碼及其父會話控制碼都是連接控制碼用來建立之任何要求控制碼的父代。

關閉父控制碼時，即使其本身未關閉，其任何子句都間接失效，後續使用的要求也會失敗，併發生錯誤 ERROR_INVALID_HANDLE。 無法依賴擱置的非同步要求來正確完成。

下圖顯示使用WinHttpOpenRequest所建立HINTERNET控制碼的函式。 陰影方塊代表建立控制碼的 WinHTTP 函式，而純方塊會顯示使用這些 HINTERNET 控制碼的函式。 圖表也會組織為顯示一般呼叫 WinHTTP 函式的順序。

建立控制碼的函式

控制碼階層的說明

首先，會使用 WinHttpOpen建立會話控制碼。 WinHttpConnect 需要會話控制碼做為其第一個參數，並傳回指定伺服器的連線控制碼。 要求控制碼是由 WinHttpOpenRequest所建立，它會使用 WinHttpConnect所建立的連接控制碼。 如果應用程式選擇將其他標頭新增至要求，或者如果應用程式需要設定驗證的認證，則可以使用此要求控制碼呼叫 WinHttpAddRequestHeaders 和 WinHttpSetCredentials 。 要求是由 WinHttpSendRequest傳送，其會使用要求控制碼。 傳送要求之後，可以使用 WinHttpWriteData將其他資料傳送至伺服器，或者應用程式可以直接跳至 WinHttpReceiveResponse ，以指定不會傳送其他資訊給伺服器。 此時，視應用程式的目的而定，要求控制碼可用來呼叫 WinHttpQueryHeaders、 WinHttpQueryAuthSchemes，或使用 WinHttpQueryDataAvailable 和 WinHttpReadData擷取資源。

控制碼階層中的 Web 通訊端

Web 通訊端控制碼繼承自連線和會話控制碼，並在控制碼階層中佔用類似位置，如同要求控制碼一樣。 若要建立 Web 通訊端控制碼，要求控制碼必須存在;但是建立 Web 通訊端控制碼之後，要求可能會關閉，而 Web 通訊端控制碼將會繼續運作。