Internetfunctionaliteit inschakelen

Voordat u de WinINet-functies gebruikt, moet de toepassing proberen verbinding te maken met internet met behulp van de functie InternetAttemptConnect. Met deze functie wordt het dialoogvenster voor inbelverbinding aangeroepen om een verbinding met internet te starten of te controleren of er al een verbinding bestaat. Als deze functie mislukt, kan de toepassing de offlinemodus openen, zodat deze toegang heeft tot informatie die in de cache is opgeslagen tijdens eerdere verbindingen met internet.

Gebruik de functie InternetCheckConnection om de verbinding met internet te controleren. Er wordt geprobeerd de server te pingen die is aangewezen door de URL die wordt doorgegeven aan de functie. Als de vlag FLAG_ICC_FORCE_CONNECTION is ingesteld en de URL is NULL-, controleert de functie of er een vermelding in de serverdatabase is voor de dichtstbijzijnde server. Als er een bestaat, pingt de functie die server.

Gebruik vervolgens de functie InternetOpen om de kenmerken van de internetverbinding vast te stellen die de clienttoepassing gebruikt. InternetOpen maakt de root-HINTERNET- handle die wordt gebruikt om httpftp-sessies tot stand te brengen. InternetOpen test de verbinding met internet niet om te controleren of de kenmerken die aan de functie zijn doorgegeven, juist zijn.

Gebruik de functie InternetConnect om een specifieke sessie te maken. InternetConnect initialiseert een sessie voor de opgegeven site met behulp van de argumenten die eraan zijn doorgegeven en maakt een HINTERNET handle die een vertakking is van de hoofdgreep. InternetConnect probeert geen toegang te krijgen tot of verbinding te maken met de opgegeven site, behalve in het geval van een FTP-sessie. FtpFindFirstFile, FtpOpenFileen HttpOpenRequest-functies gebruiken de ingang die is gemaakt door InternetConnect om een verbinding met de opgegeven site tot stand te brengen.

InternetOpen gebruiken

Als u een verbinding met internet wilt mogelijk maken, moet een root-HINTERNET--handle worden gecreëerd met behulp van InternetOpen. Informatie over de gebruikersagent (de toepassing die internetfuncties aanroept), het type toegang tot internet, de proxynamen, de hosts en adressen die de proxy omzeilen en het gedrag worden doorgegeven aan InternetOpen.

De gebruikersagent instellen

De aanroepende toepassing moet een tekenreeks geven die de naam van de toepassing of entiteit die toegang heeft tot internet bevat aan de parameter lpszAgent van InternetOpen. Deze tekenreeks wordt gebruikt als de gebruikersagent in het HTTP-protocol. Microsoft Internet Explorer gebruikt bijvoorbeeld "Microsoft Internet Explorer".

Toegangstypen instellen

InternetOpen ondersteunt drie toegangstypen:

• Gebruik INTERNET_OPEN_TYPE_DIRECT als het systeem waarop de toepassing wordt uitgevoerd een directe verbinding met internet gebruikt. De parameters lpszProxyName en lpszProxyBypass parameters van InternetOpen worden niet gebruikt en moeten worden ingesteld op NULL-.
• Gebruik INTERNET_OPEN_TYPE_PROXY als het systeem waarop de toepassing wordt uitgevoerd een of meer proxyservers gebruikt voor toegang tot internet. InternetOpen maakt gebruik van de proxyservers die worden aangegeven door lpszProxyName en omzeilt de proxy voor hostnamen of IP-adressen die zijn opgegeven door lpszProxyBypass.
• Gebruik INTERNET_OPEN_TYPE_PRECONFIG om uw toepassing te instrueren om de configuratie op te halen uit het register. Dit is doorgaans de beste keuze, omdat de meeste toepassingen, waaronder webbrowsers, deze optie gebruiken.

INTERNET_OPEN_TYPE_PRECONFIG kijkt naar de registerwaarden ProxyEnable, ProxyServeren ProxyOverride. Deze waarden bevinden zich onder "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings".

Als ProxyEnable nul is, gebruikt de toepassing INTERNET_OPEN_TYPE_DIRECT. Anders gebruikt de toepassing INTERNET_OPEN_TYPE_PROXY en maakt gebruik van de ProxyServer en de ProxyOverride informatie.

De WinINet-functies bieden alleen ondersteuning voor SOCKS-typeproxy's als Internet Explorer is geïnstalleerd. De installatie van Internet Explorer bevat het Wsock32n.dll-bestand, dat nodig is om SOCKS-proxy's te ondersteunen. Wsock32n.dll is niet herdistribueerbaar.

Proxyservers vermelden

WinINet herkent twee soorten proxy's: CERN-typeproxy's (alleen HTTP) en TIS FTP-proxy's (alleen FTP). Als Internet Explorer is geïnstalleerd, biedt WinINet ook ondersteuning voor SOCKS-typeproxy's. InternetConnect standaard ervan uitgaat dat de opgegeven proxy een CERN-proxy is. Als het toegangstype is ingesteld op INTERNET_OPEN_TYPE_DIRECT of INTERNET_OPEN_TYPE_PRECONFIG, moet de parameter lpszProxyName van InternetOpen- worden ingesteld op NULL-. Anders moet de waarde die wordt doorgegeven aan lpszProxyName de proxy's in een door spaties gescheiden tekenreeks bevatten. De proxyvermeldingen kunnen het poortnummer bevatten dat wordt gebruikt voor toegang tot de proxy.

Als u een proxy voor een specifiek protocol wilt weergeven, moet de tekenreeks de notatie ""<protocol><protocol volgen>://<proxy_name>"". De geldige protocollen zijn HTTP, HTTPS en FTP. Als u bijvoorbeeld een FTP-proxy wilt weergeven, is een geldige tekenreeks ""ftp=ftp://ftp_proxy_name:21", waarbij ftp_proxy_name de naam is van de FTP-proxy en 21 het poortnummer is dat moet worden gebruikt voor toegang tot de proxy. Als de proxy het standaardpoortnummer voor dat protocol gebruikt, kan het poortnummer worden weggelaten. Als een proxynaam op zichzelf wordt vermeld, wordt deze gebruikt als de standaardproxy voor protocollen die geen specifieke proxy hebben opgegeven. ''http=https://http_proxy other' zou bijvoorbeeld http_proxy gebruiken voor HTTP-bewerkingen, terwijl alle andere protocollen andere protocollen zouden gebruiken.

Standaard wordt ervan uitgegaan dat de proxy die is opgegeven door lpszProxyName een CERN-proxy is. Een toepassing kan meer dan één proxy opgeven, inclusief verschillende proxy's voor de verschillende protocollen. Als u bijvoorbeeld '"ftp=ftp://ftp-gw HTTP=https://jericho:99 proxy" opgeeft, worden FTP-aanvragen gedaan via de ftp-gw-proxy, die luistert op poort 21 en HTTP-aanvragen worden gedaan via een CERN-proxy met de naam jericho, die luistert op poort 99. Anders worden HTTP-aanvragen gedaan via de CERN-proxy met de naam proxy, die luistert op poort 80. Als de toepassing bijvoorbeeld alleen FTP gebruikt, hoeft deze niet ""ftp=ftp=ftp-gw:21" op te geven. Het kan alleen ''ftp-gw' opgeven. Een toepassing is alleen vereist om de protocolnamen op te geven als deze meer dan één protocol per ingang gebruikt dat wordt geretourneerd door InternetOpen.

De proxy-bypass vermelden

Hostnamen of IP-adressen die niet naar de proxy moeten worden verzonden, kunnen worden vermeld in de lijst met proxy-bypasss. Deze lijst kan jokertekens bevatten, '*', waardoor de toepassing de proxyserver omzeilt voor adressen die voldoen aan het opgegeven patroon. Als u meerdere adressen en hostnamen wilt weergeven, scheidt u deze met puntkomma's in de proxy-bypasstekenreeks. Als de macro '<local>' is opgegeven, zal de functie de proxy omzeilen voor een hostnaam die geen punt bevat.

WinINet slaat standaard de proxy over voor aanvragen die gebruikmaken van de hostnamen 'localhost', 'loopback', '127.0.0.1' of '[::1]'. Dit gedrag bestaat omdat een externe proxyserver deze adressen doorgaans niet correct oplost.

Internet Explorer 9: U kunt de lokale computer verwijderen uit de lijst met proxy-bypasss met behulp van de macro<-loopback>.

In het volgende voorbeeld ziet u voorbeeldaanroepen naar InternetOpen met behulp van verschillende tekenreeksen voor het omzeilen van proxy's. In de opmerkingen boven elke aanroep wordt beschreven welk effect de bypass-tekenreeks heeft op de hostnamen die worden benaderd via de HINTERNET-verwerking die het creëert.

HINTERNET hInternetRoot;

/* bypass the proxy for any host name that does not 
    contain a period */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("<local>"), 0);

/* bypass the proxy for any host name that starts with the 
    letters "ms" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("ms*"), 0);

/* bypass the proxy for any host name that contains "int", 
    such as "internet" and "painter" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("*int*"), 0);

/* bypass the proxy for the host name "example" and any 
    host name that contains "test" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("example *test*"), 0);

/* Disable the loopback proxy bypass for localhost */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("127.0.0.1:8888"),TEXT("<-loopback>"), 0);

InternetConnect gebruiken

Als u een sessie wilt starten, moet de InternetConnect functie een handle van de hoofdhandle maken die wordt geretourneerd door de InternetOpen functie. InternetConnect stelt het serveradres, het poortnummer, de gebruikersnaam, het wachtwoord en het type service in.

InternetConnect maakt gebruik van de root HINTERNET- handle die is gemaakt door InternetOpen om een sessiehandle tot stand te brengen. Als de INTERNET_FLAG_ASYNC vlag is ingesteld in de aanroep naar InternetOpen, moet de aanroep naar InternetConnect- een niet-nulcontextwaarde bevatten.

De servernaam kan de hostnaam (bijvoorbeeld "www.servername.com") of het IP-nummer van de site bevatten in asCII-decimale notatie (bijvoorbeeld '10.0.1.45').

De serverpoort is het TCP/IP-poortnummer (Transmission Control Protocol/Internet Protocol) waarmee verbinding moet worden gemaakt op de server. InternetConnect gebruikt de standaardpoort voor het geselecteerde servicetype als de INTERNET_INVALID_PORT_NUMBER waarde wordt gebruikt. De volgende tabellen bevatten de standaardinstellingen voor de serverpoort voor WinINet.

Waarde	Betekenis
INTERNET_DEFAULT_FTP_PORT	Gebruik de standaardpoort voor FTP-servers (poort 21).
INTERNET_DEFAULT_GOPHER_PORT	Gebruik de standaardpoort voor gopher-servers (poort 70). Opmerking: Windows XP en Windows Server 2003 R2 en eerder, alleen.
INTERNET_DEFAULT_HTTP_PORT	Gebruik de standaardpoort voor HTTP-servers (poort 80).
INTERNET_DEFAULT_HTTPS_PORT	Gebruik de standaardpoort voor https-servers (poort 443).
INTERNET_DEFAULT_SOCKS_PORT	Gebruik de standaardpoort voor SOCKS-firewallservers (poort 1080).

De gebruikersnaam en het wachtwoord definiëren

De waarde van lpszUsername is het adres van een null-tekenreeks-terminated die de naam bevat van de gebruiker die zich aanmeldt. Als deze parameter is NULL-, gebruikt de functie een geschikte standaardwaarde, met uitzondering van HTTP. Een PARAMETER NULL in HTTP zorgt ervoor dat de server een fout retourneert. Voor het FTP-protocol is de standaardwaarde anoniem.

De waarde van lpszPassword is het adres van een tekenreeks die door een null-tekenwordt beëindigd en het aanmeldingswachtwoord bevat. Als zowel lpszUsername als lpszPassword-NULL-zijn, gebruikt de functie het standaard anonieme standaardwachtwoord. In het geval van FTP is het standaard anonieme wachtwoord de e-mailnaam van de gebruiker. Als lpszUsername niet NULL- is en lpszPasswordNULL-is, gebruikt de functie een leeg wachtwoord. Er zijn vier mogelijke instellingen van lpszUsername en lpszPassword, die het gedrag produceren dat wordt weergegeven in de volgende tabel.

lpszUsername	lpszPassword	Gebruikersnaam verzonden naar FTP-server	Wachtwoord verzonden naar FTP-server
NULL-	NULL	"anoniem"	E-mailnaam van gebruiker
Niet-NULL- tekenreeks	NULL-	lpszUsername	""
NULL	Niet-NULL- tekenreeks	FOUT	FOUT
Niet-NULL- tekenreeks	Niet-NULL- tekenreeks	lpszUsername	lpszPassword

Deze informatie kan worden gewijzigd met behulp van de functies InternetSetOption en InternetErrorDlg. InternetSetOption- de gebruikersnaam en wachtwoordwaarden wijzigt, terwijl InternetErrorDlg- een dialoogvenster weergeeft waarin de juiste gebruikersnaam en het juiste wachtwoord worden aangevraagd.

De sessie definiëren

Als u de sessie wilt definiëren die tot stand wordt gebracht, stelt u het servicetype, de vlaggen en de contextwaarde in voor InternetConnect.

Er zijn twee servicetypen beschikbaar voor InternetConnect: INTERNET_SERVICE_FTP en INTERNET_SERVICE_HTTP. INTERNET_SERVICE_HTTP wordt gebruikt voor zowel HTTP- als HTTPS-sessies.

INTERNET_FLAG_PASSIVE is de enige servicespecifieke vlag die wordt gebruikt door de WinINet-functies. Deze vlag kan worden ingesteld wanneer het servicetype INTERNET_SERVICE_FTP is, zodat passieve FTP-semantieken worden gebruikt.

Voor alle synchrone bewerkingen moet de waarde van dwContext- worden ingesteld op nul. Als asynchrone bewerkingen zijn ingesteld door de vlag INTERNET_FLAG_ASYNC in te stellen in de aanroep van InternetOpen, moet een niet-nulwaarde worden opgegeven voor dwContext-. Zie Asynchrone bewerkingen instellenvoor meer informatie over asynchrone bewerkingen.

Voor FTP-sessies probeert InternetConnect een verbinding tot stand te brengen met de server op internet. Voor HTTP-sessies wordt er met InternetConnect pas een verbinding tot stand gebracht wanneer een andere functie informatie van de server probeert op te halen.

Notitie

WinINet biedt geen ondersteuning voor serverimplementaties. Daarnaast mag deze niet worden gebruikt vanuit een service. Voor server-implementaties of -services wordt Microsoft Windows HTTP Services (WinHTTP)gebruikt.