WinINet-toepassingen overzetten naar WinHTTP

Microsoft Windows HTTP Services (WinHTTP) is gericht op middelste en back-endservertoepassingen die toegang nodig hebben tot een HTTP-clientstack. Microsoft Windows Internet (WinINet) biedt een HTTP-clientstack voor clienttoepassingen, evenals toegang tot de protocollen File Transfer Protocol (FTP), SOCKSv4 en Gopher. Dit overzicht kan helpen bepalen of het overzetten van uw WinINet-toepassingen naar WinHTTP nuttig zou zijn. Ook worden specifieke conversievereisten beschreven.

• aandachtspunten voordat u uw WinINet-toepassing overzet
• WinHTTP-equivalenten voor WinINet-functies
• verschillende verwerking van asynchrone aanvragen
• Verschillen in WinHTTP-callbackmeldingen
• authenticatieverschillen
• verschillen in beveiligde HTTP-transacties

Aandachtspunten voordat u uw WinINet-toepassing overzet

Overweeg om uw WinINet-toepassing over te maken naar WinHTTP als uw toepassing zou profiteren van:

• Een serverveilige HTTP-clientstack.
• Geminimaliseerd stackgebruik.
• De schaalbaarheid van een servertoepassing.
• Minder afhankelijkheden van platformgerelateerde API's.
• Ondersteuning voor thread-imitatie.
• Een servicevriendelijke HTTP-stack.
• Toegang tot het scriptbare WinHttpRequest-object.

Overweeg het overzetten van uw WinINet-toepassing niet naar WinHTTP als deze een of meer van de volgende opties moet ondersteunen:

• Het FTP- of Gopher-protocol van de HTTP-stack.
• Ondersteuning voor SOCKSv4-protocol voor communicatie met SOCKS-proxy's.
• Automatische inbeldiensten.

Als u besluit uw toepassing over te leiden naar WinHTTP, begeleiden de volgende secties u bij het conversieproces.

Voor een voorbeeldtoepassing voor zowel WinINet als WinHTTP vergelijkt u het AsyncDemo-voorbeeld voor WinINet met het AsyncDemo-voorbeeld voor WinHTTP.

WinHTTP-equivalenten aan WinINet-functies

De volgende tabel bevat WinINet-functies die zijn gerelateerd aan de HTTP-clientstack, samen met de WinHTTP-equivalenten.

Als voor uw toepassing WinINet-functies zijn vereist die niet worden vermeld, moet u uw toepassing niet overzetten naar WinHTTP.

Verschillende verwerking van asynchrone aanvragen

Houd er rekening mee dat sommige functies in WinINet en WinHTTP asynchrone aanvragen synchroon of asynchroon kunnen voltooien. Uw toepassing moet een van beide situaties afhandelen. Er zijn aanzienlijke verschillen in de manier waarop WinINet en WinHTTP deze mogelijk asynchrone functies verwerken.

WinINet

• Synchrone voltooiing: als een mogelijk asynchrone WinINet-functieaanroep synchroon wordt voltooid, retourneren de OUT-parameters van de functie de resultaten van de bewerking. Wanneer er een fout optreedt, haalt u de foutcode op door GetLastError- aan te roepen na de winINet-functieaanroep.

• Asynchrone voltooiing: als een mogelijk asynchrone functieaanroep asynchroon wordt voltooid, zijn de resultaten van de bewerking en eventuele fouten toegankelijk in de callback-functie. De callback-functie wordt uitgevoerd op een worker thread, niet op de thread die de initiële functieaanroep heeft gedaan.

Met andere woorden, uw toepassing moet logica dupliceren om de resultaten van dergelijke bewerkingen op twee plaatsen te verwerken: zowel direct na de functieaanroep als in de callback-functie.

WinHTTP vereenvoudigt dit model door u in staat te stellen de operationele logica alleen te implementeren in de callback-functie, die een voltooiingsmelding ontvangt, ongeacht of de bewerking synchroon of asynchroon is voltooid. Wanneer asynchrone bewerking is ingeschakeld, retourneren de OUT-parameters van WinHTTP-functies geen zinvolle gegevens en moeten ze worden ingesteld op NULL-.

Het enige significante verschil tussen asynchrone en synchrone voltooiing in WinHTTP, vanuit het perspectief van de toepassing, is waar de callback-functie wordt uitgevoerd.

WinHTTP

• Synchrone voltooiing: wanneer een bewerking synchroon wordt voltooid, worden de resultaten geretourneerd in een callback-functie die wordt uitgevoerd in dezelfde thread als de oorspronkelijke functieaanroep.

• Asynchrone voltooiing: wanneer een bewerking asynchroon wordt voltooid, worden de resultaten geretourneerd in een callback-functie die wordt uitgevoerd in een werkdraad.

Hoewel de meeste fouten ook volledig kunnen worden verwerkt in de callback-functie, moeten WinHTTP-toepassingen nog steeds worden voorbereid voor een functie om ONWAAR- te retourneren vanwege een ERROR_INVALID_PARAMETER of een andere vergelijkbare fout die is opgehaald door GetLastError-aan te roepen.

In tegenstelling tot WinINet, dat meerdere asynchrone bewerkingen tegelijk kan uitvoeren, dwingt WinHTTP een beleid af van één asynchrone bewerking per aanvraaghandler. Als een bewerking in behandeling is en een andere WinHTTP-functie wordt aangeroepen, mislukt de tweede functie en GetLastError ERROR_INVALID_OPERATION retourneert.

WinHTTP vereenvoudigt dit model door u in staat te stellen de operationele logica alleen te implementeren in de callback-functie, die een voltooiingsmelding ontvangt, ongeacht of de bewerking synchroon of asynchroon is voltooid. Wanneer asynchrone bewerking is ingeschakeld, retourneren de OUT-parameters van WinHTTP-functies geen zinvolle gegevens en moeten ze worden ingesteld op NULL-.

Verschillen in WinHTTP-callbackmeldingen

De functie status callback ontvangt updates over de status van bewerkingen via meldingenvlagmen. In WinHTTP worden meldingen geselecteerd met behulp van de dwNotificationFlags-parameter van de functie WinHttpSetStatusCallback. Gebruik de vlag WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS om op de hoogte te worden gesteld van alle statusupdates.

Meldingen die aangeven dat een bepaalde bewerking is voltooid, worden voltooiingsmeldingen of alleen voltooiingsmeldingen genoemd. Telkens wanneer de callback-functie in WinINet een voltooiing ontvangt, bevat de parameter lpvStatusInformation een INTERNET_ASYNC_RESULT structuur. In WinHTTP is deze structuur niet beschikbaar voor alle voltooiingen. Het is belangrijk om de referentiepagina voor WINHTTP_STATUS_CALLBACKte bekijken, die informatie bevat over meldingen en welk type gegevens voor elke pagina kan worden verwacht.

In WinHTTP geeft één voltooiing, WINHTTP_CALLBACK_STATUS_REQUEST_ERROR, aan dat een bewerking is mislukt. Alle andere voltooiingen geven een geslaagde bewerking aan.

Zowel WinINet als WinHTTP gebruiken een door de gebruiker gedefinieerde contextwaarde om informatie van de hoofdthread door te geven aan de functie status callback, die kan worden uitgevoerd op een werkrolthread. In WinINet wordt de contextwaarde die wordt gebruikt door de functie status callback ingesteld door een van de verschillende functies aan te roepen. In WinHTTP wordt de contextwaarde alleen ingesteld met WinHttpSendRequest of WinHttpSetOption-. Daarom is het mogelijk in WinHTTP dat een melding plaatsvindt voordat een contextwaarde wordt ingesteld. Als de callback-functie een melding ontvangt voordat de contextwaarde is ingesteld, moet de toepassing worden voorbereid om NULL- te ontvangen in de parameter dwContext parameter van de callback-functie.

Verificatieverschillen

In WinINet worden gebruikersreferenties ingesteld door de functie InternetSetOption- aan te roepen, waarbij code wordt gebruikt die vergelijkbaar is met die in het volgende codevoorbeeld.

// Use the WinINet InternetSetOption function to set the 
// user credentials to the user name contained in strUsername 
// and the password to the contents of strPassword.
       
InternetSetOption( hRequest, INTERNET_OPTION_PROXY_USERNAME, 
                   strUsername, strlen(strUsername) + 1 );

InternetSetOption( hRequest, INTERNET_OPTION_PROXY_PASSWORD, 
                   strPassword, strlen(strPassword) + 1 );

Voor compatibiliteit kunnen gebruikersreferenties op dezelfde manier worden ingesteld in WinHTTP met behulp van de functie WinHttpSetOption-, maar dit wordt niet aanbevolen omdat dit een beveiligingsprobleem kan vormen.

Wanneer een toepassing in plaats daarvan een 401-statuscode ontvangt in WinHTTP, is de aanbevolen methode voor het instellen van referenties eerst om een verificatieschema te identificeren met behulp van WinHttpQueryAuthSchemes- en ten tweede de referenties in te stellen met behulp van WinHttpSetCredentials. In het volgende codevoorbeeld ziet u hoe u dit doet.

DWORD dwSupportedSchemes;
DWORD dwPrefered;
DWORD dwTarget;

// Obtain the supported and first schemes.
WinHttpQueryAuthSchemes( hRequest, &dwSupportedSchemes, &dwPrefered, &dwTarget );

// Set the credentials before resending the request.
WinHttpSetCredentials( hRequest, dwTarget, dwPrefered, strUsername, strPassword, NULL );

Omdat er geen equivalent is aan InternetErrorDlg- in WinHTTP, moeten toepassingen die referenties verkrijgen via een gebruikersinterface hun eigen interface bieden.

In tegenstelling tot WinINet slaat WinHTTP geen wachtwoorden in de cache op. Geldige gebruikersreferenties moeten worden opgegeven voor elke aanvraag.

WinHTTP biedt geen ondersteuning voor het DPA-schema (Distributed Password Authentication) dat wordt ondersteund door WinINet. WinHTTP biedt echter wel ondersteuning voor Microsoft Passport 1.4. Zie Passport-verificatie in WinHTTPvoor meer informatie over het gebruik van Passport-verificatie in WinHTTP.

WinHTTP is niet afhankelijk van Internet Explorer-instellingen om het beleid voor automatische aanmelding te bepalen. In plaats daarvan wordt het beleid voor automatisch aanmelden ingesteld met WinHttpSetOption-. Zie Verificatie in WinHTTPvoor meer informatie over verificatie in WinHTTP, waaronder het beleid voor automatisch aanmelden.

Verschillen in beveiligde HTTP-transacties

In WinINet start u een beveiligde sessie met behulp van HttpOpenRequest of InternetConnect, maar in WinHTTP moet u WinHttpOpenRequest aanroepen met behulp van de vlag WINHTTP_FLAG_SECURE.

In een beveiligde HTTP-transactie kunnen servercertificaten worden gebruikt om een server te verifiëren bij de client. Als in WinINet een servercertificaat fouten bevat, mislukt HttpSendRequest en worden details over de certificaatfouten verstrekt.

In WinHttp worden servercertificaatfouten als volgt verwerkt volgens de versie:

• Vanaf WinHttp 5.1, als een servercertificaat mislukt of fouten bevat, rapporteert de aanroep naar WinHttpSendRequest een WINHTTP_CALLBACK_STATUS_SECURE_FAILURE in de callback-functie. Als de fout die is gegenereerd door WinHttpSendRequest- wordt genegeerd, mislukken volgende aanroepen naar WinHttpReceiveResponse- met een ERROR_WINHTTP_OPERATION_CANCELLED-fout.
• In WinHTTP 5.0 veroorzaken fouten in servercertificaten standaard niet dat een aanvraag mislukt. In plaats daarvan worden de fouten gerapporteerd in de callback-functie met de melding WINHTTP_CALLBACK_STATUS_SECURE_FAILURE.

Op sommige eerdere platforms ondersteunde WinINet de protocollen Private Communication Technology (PCT) en/of Fortezza, hoewel niet op Windows XP.

WinHTTP biedt geen ondersteuning voor de PCT- en Fortezza-protocollen op elk platform en is in plaats daarvan afhankelijk van Secure Sockets Layer (SSL) 2.0, SSL 3.0 of Transport Layer Security (TLS) 1.0.