HINTERNET-handtag i WinHTTP
Microsoft Windows HTTP Services (WinHTTP) använder referenser för att hålla reda på inställningar och information som krävs när du använder HTTP-protokollet. Varje referens upprätthåller information som är relevant för en HTTP-session, en anslutning till en HTTP-server eller en specifik resurs. Det här avsnittet beskriver de olika typerna av referenser, namngivningskonventionerna för dessa referenser och deras hierarkiska struktur.
Om HINTERNET-referenser
Handtagen som skapas och används av WinHTTP kallas HINTERNET- referenser. WinHTTP-funktionerna returnerar HINTERNET- referenser som inte är utbytbara med andra referenser, så de kan inte användas med funktioner som ReadFile eller CloseHandle. På samma sätt kan andra referenser inte användas med WinHTTP-funktioner. En referens som returneras av CreateFile kan till exempel inte skickas till WinHttpReadData. Dessa HINTERNET- referenser kan inte stängas medan ett API-anrop med handtaget pågår. För att undvika ett konkurrenstillstånd bör program skydda handtaget och förhindra att det stängs så länge API-anropet pågår.
Funktionerna i Microsoft Win32 Internet (WinInet) använder också HINTERNET- referenser. Referenserna som används i WinInet-funktioner kan dock inte bytas ut mot handtagen som används i WinHTTP-funktioner. Mer information om WinInet finns i Om WinINet.
Funktionen WinHttpCloseHandle stänger WinHTTP HINTERNET- referenser.
Namngivningshandtag
I WinHTTP-dokumentationen visar beskrivningar av funktioner i programprogrammeringsgränssnittet (API) och exempelkod skapandet och användningen av olika typer av HINTERNET- referenser. För att hålla reda på de olika typer av referenser som är tillgängliga är namngivningen av dessa referenser konsekvent. I följande tabell visas de identifierare som används av konventionen i dokumentationen.
| Referenstyp | Funktionsskapande handtag | Identifierare |
|---|---|---|
| Allmänt handtag | WinHttpOpen, WinHttpConnecteller WinHttpOpenRequest | hInternet |
| Sessionshandtag | WinHttpOpen | hSession |
| Anslutningshandtag | WinHttpConnect | hConnect |
| Begärandehandtag | WinHttpOpenRequest | hRequest |
| Web Socket-handtag | WinHttpWebSocketCompleteUpgrade | hWebSocket |
Hantera hierarki
Handtagen HINTERNET underhålls i en hierarki. Handtaget som returneras av WinHttpOpen är sessionen HINTERNET- handtag. Att anropa WinHttpOpen initierar WinHTTP-funktionerna och påbörjar en sessionskontext som underhåller användarinformation och inställningar under hela sessionshandtaget. WinHttpConnect- anger en HTTP- eller HTTPS-målserver och skapar en anslutning HINTERNET- handtag. Som standard ärver anslutningshandtaget inställningarna för sessionshandtaget. Varje resurs som anges med ett anrop till WinHttpOpenRequest tilldelas en begäran HINTERNET- handtag.
Följande diagram illustrerar hierarkin för HINTERNET- referenser. Varje ruta i diagrammet representerar en WinHTTP-funktion som returnerar en HINTERNET- handtag.
När du har stängt en referens måste programmet vara redo att ta emot återanropsmeddelanden på handtaget tills det slutliga WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED-värdet returneras för att indikera att handtaget är helt stängt (eller tills programmet gör sin egen motsvarande synkronisering, till exempel spårning och väntan på återanrop från väntande asynkrona åtgärder och se till att inga ytterligare åtgärder görs med hjälp av den handtaget).
En sessionsreferens kallas överordnad för alla anslutningsreferenser som den använde för att skapa. på samma sätt kallas både anslutningshandtaget och dess överordnade sessionshandtag överordnade för alla begärandehandtag som anslutningshandtaget används för att skapa.
När en överordnad referens stängs ogiltigförklaras eventuella underordnade objekt indirekt även om de inte stängs själva, och efterföljande begäranden som använder dem misslyckas med felet ERROR_INVALID_HANDLE. Väntande asynkrona begäranden kan inte användas för att slutföras korrekt.
Följande diagram visar de funktioner som använder HINTERNET--handtag som skapats av WinHttpOpenRequest. De skuggade rutorna representerar WinHTTP-funktioner som skapar referenser, och de oformaterade rutorna visar de funktioner som använder dessa HINTERNET- referenser. Diagrammet är också organiserat för att visa i vilken ordning WinHTTP-funktioner normalt anropas.
Förklaring av referenshierarkin
Först skapas ett sessionshandtag med WinHttpOpen. WinHttpConnect kräver sessionshandtaget som sin första parameter och returnerar ett anslutningshandtag för en angiven server. En begärandereferens skapas av WinHttpOpenRequest, som använder anslutningshandtaget som skapats av WinHttpConnect. Om programmet väljer att lägga till ytterligare huvuden i begäran, eller om det är nödvändigt för att programmet ska kunna ange autentiseringsuppgifter för autentisering, kan WinHttpAddRequestHeaders och WinHttpSetCredentials anropas med hjälp av den här begärandereferensen. Begäran skickas av WinHttpSendRequest, som använder begärandehandtaget. När du har skickat begäran kan ytterligare data skickas till servern med WinHttpWriteData, eller så kan programmet hoppa direkt till WinHttpReceiveResponse för att ange att ingen mer information skickas till servern. Beroende på programmets syfte kan begärandereferensen användas för att anropa WinHttpQueryHeaders, WinHttpQueryAuthSchemeseller hämta en resurs med WinHttpQueryDataAvailable och WinHttpReadData.
Webb socketar i referenshierarkin
Ett web socket-handtag ärver från anslutnings- och sessionshandtagen och upptar en liknande position i referenshierarkin som en begärandehandtag gör. För att kunna skapa ett web socket-handtag måste det finnas ett begärandehandtag. men när web socket-handtaget har skapats kan begäran stängas och web socket-handtaget fortsätter att fungera.