Aktivieren der Internetfunktionalität

Vor der Verwendung der WinINet-Funktionen sollte die Anwendung versuchen, mithilfe der InternetAttemptConnect-Funktion eine Verbindung mit dem Internet herzustellen. Diese Funktion ruft das DFÜ-Dialogfeld auf, um eine Verbindung mit dem Internet zu initiieren oder zu überprüfen, ob bereits eine Verbindung besteht. Wenn diese Funktion fehlschlägt, kann die Anwendung in den Offlinemodus wechseln, sodass sie auf Informationen zugreifen kann, die bei vorherigen Verbindungen mit dem Internet zwischengespeichert wurden.

Verwenden Sie die InternetCheckConnection-Funktion , um die Verbindung mit dem Internet zu überprüfen. Es versucht, einen Ping-Ping für den Server auszuführen, der durch die URL festgelegt ist, die an die Funktion übergeben wird. Wenn das FLAG_ICC_FORCE_CONNECTION-Flag festgelegt ist und die URL NULL ist, überprüft die Funktion, ob in der Serverdatenbank ein Eintrag für den nächstgelegenen Server vorhanden ist. Wenn eine vorhanden ist, pingt die Funktion diesen Server.

Verwenden Sie als Nächstes die InternetOpen-Funktion , um die Merkmale der Internetverbindung zu ermitteln, die die Clientanwendung verwendet. InternetOpen erstellt das HINTERNET-Stammhandle, das zum Einrichten von HTTP-FTP-Sitzungen verwendet wird. InternetOpen testet die Verbindung mit dem Internet nicht, um zu überprüfen, ob die an die Funktion übergebenen Merkmale richtig sind.

Verwenden Sie die InternetConnect-Funktion , um eine bestimmte Sitzung zu erstellen. InternetConnect initialisiert eine Sitzung für den angegebenen Standort mithilfe der an sie übergebenen Argumente und erstellt ein HINTERNET-Handle , das ein Branch aus dem Stammhandle ist. InternetConnect versucht nicht, auf den angegebenen Standort zuzugreifen oder eine Verbindung herzustellen, außer im Fall einer FTP-Sitzung. Die Funktionen FtpFindFirstFile, FtpOpenFile und HttpOpenRequest verwenden das von InternetConnect erstellte Handle, um eine Verbindung mit der angegebenen Website herzustellen.

Verwenden von InternetOpen

Um eine Verbindung mit dem Internet zu ermöglichen, muss ein HINTERNET-Stammhandle mithilfe von InternetOpen erstellt werden. Informationen über den Benutzer-Agent (die Anwendung, die die Internetfunktionen aufruft), die Art des Zugriffs auf das Internet, die Proxynamen, die Hosts und Adressen, die den Proxy umgehen, und das Verhalten werden an InternetOpen übergeben.

Festlegen des Benutzer-Agents

Die aufrufende Anwendung sollte dem lpszAgent-Parameter von InternetOpen eine Zeichenfolge mit dem Namen der Anwendung oder Entität geben, die auf das Internet zugreift. Diese Zeichenfolge wird als Benutzer-Agent im HTTP-Protokoll verwendet. Microsoft Internet Explorer verwendet beispielsweise "Microsoft Internet Explorer".

Festlegen von Zugriffstypen

InternetOpen unterstützt drei Zugriffstypen:

• Verwenden Sie INTERNET_OPEN_TYPE_DIRECT, wenn das System, auf dem die Anwendung ausgeführt wird, eine direkte Verbindung mit dem Internet verwendet. Die Parameter lpszProxyName und lpszProxyBypass von InternetOpen werden nicht verwendet und sollten auf NULL festgelegt werden.
• Verwenden Sie INTERNET_OPEN_TYPE_PROXY, wenn das System, auf dem die Anwendung ausgeführt wird, einen oder mehrere Proxyserver für den Zugriff auf das Internet verwendet. InternetOpen verwendet die von lpszProxyName angegebenen Proxyserver und umgeht den Proxy für alle Hostnamen oder IP-Adressen, die von lpszProxyBypass angegeben werden.
• Verwenden Sie INTERNET_OPEN_TYPE_PRECONFIG, um Ihre Anwendung anzuweisen, die Konfiguration aus der Registrierung abzurufen. Dies ist in der Regel die beste Wahl, da die meisten Anwendungen, einschließlich Webbrowsern, diese Option verwenden.

INTERNET_OPEN_TYPE_PRECONFIG die Registrierungswerte ProxyEnable, ProxyServer und ProxyOverride. Diese Werte befinden sich unter "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings".

Wenn ProxyEnable null ist, verwendet die Anwendung INTERNET_OPEN_TYPE_DIRECT. Andernfalls verwendet die Anwendung INTERNET_OPEN_TYPE_PROXY und verwendet die ProxyServer- und ProxyOverride-Informationen.

Die WinINet-Funktionen bieten nur Unterstützung für Proxys vom Typ SOCKS, wenn internet Explorer installiert ist. Die Installation von Internet Explorer umfasst die Wsock32n.dll-Datei, die zur Unterstützung von SOCKS-Proxys erforderlich ist. Wsock32n.dll ist nicht verteilbar.

Auflisten von Proxyservern

WinINet erkennt zwei Arten von Proxys: Proxys vom TYP CERN (nur HTTP) und TIS FTP-Proxys (nur FTP). Wenn Internet Explorer installiert ist, unterstützt WinINet auch Proxys vom Typ SOCKS. InternetConnect geht standardmäßig davon aus, dass es sich bei dem angegebenen Proxy um einen CERN-Proxy handelt. Wenn der Zugriffstyp auf INTERNET_OPEN_TYPE_DIRECT oder INTERNET_OPEN_TYPE_PRECONFIG festgelegt ist, sollte der lpszProxyName-Parameter von InternetOpen auf NULL festgelegt werden. Andernfalls muss der an lpszProxyName übergebene Wert die Proxys in einer leerzeichentrennten Zeichenfolge enthalten. Die Proxyauflistungen können die Portnummer enthalten, die für den Zugriff auf den Proxy verwendet wird.

Um einen Proxy für ein bestimmtes Protokoll aufzulisten, muss die Zeichenfolge das Format "protokollprotokoll><><://<proxy_name>" aufweisen. Die gültigen Protokolle sind HTTP, HTTPS und FTP. Um beispielsweise einen FTP-Proxy aufzulisten, würde eine gültige Zeichenfolge ""ftp=ftp://ftp_proxy_name:21"" lauten, wobei ftp_proxy_name der Name des FTP-Proxys und 21 die Portnummer ist, die für den Zugriff auf den Proxy verwendet werden muss. Wenn der Proxy die Standardportnummer für dieses Protokoll verwendet, kann die Portnummer weggelassen werden. Wenn ein Proxyname allein aufgeführt wird, wird er als Standardproxy für alle Protokolle verwendet, für die kein bestimmter Proxy angegeben ist. Beispielsweise würde "http=https://http_proxy other"" http_proxy für alle HTTP-Vorgänge verwenden, während alle anderen Protokolle andere verwenden würden.

Standardmäßig geht die Funktion davon aus, dass der von lpszProxyName angegebene Proxy ein CERN-Proxy ist. Eine Anwendung kann mehrere Proxys angeben, einschließlich verschiedener Proxys für die verschiedenen Protokolle. Wenn Sie beispielsweise ""ftp=ftp://ftp-gw HTTP=https://jericho:99 proxy"" angeben, werden FTP-Anforderungen über den ftp-gw-Proxy gesendet, der an Port 21 lauscht, und HTTP-Anforderungen werden über einen CERN-Proxy mit dem Namen jericho gesendet, der an Port 99 lauscht. Andernfalls würden HTTP-Anforderungen über den CERN-Proxy namens Proxy erfolgen, der an Port 80 lauscht. Wenn die Anwendung beispielsweise nur FTP verwendet, muss sie ""ftp=ftp://ftp-gw:21" nicht angeben. Es könnte nur ""ftp-gw" angeben. Eine Anwendung muss die Protokollnamen nur angeben, wenn sie mehr als ein Protokoll pro von InternetOpen zurückgegebenen Handle verwendet.

Auflisten der Proxyumgehung

Hostnamen oder IP-Adressen, die nicht an den Proxy gesendet werden sollen, können in der Proxyumgehungsliste aufgeführt werden. Diese Liste kann Platzhalter "*" enthalten, die dazu führen, dass die Anwendung den Proxyserver für Adressen umgeht, die dem angegebenen Muster entsprechen. Um mehrere Adressen und Hostnamen aufzulisten, trennen Sie diese durch Semikolons in der Proxyumgehungszeichenfolge. Wenn das "<lokale>" Makro angegeben wird, umgeht die Funktion den Proxy für jeden Hostnamen, der keinen Punkt enthält.

Standardmäßig umgeht WinINet den Proxy für Anforderungen, die die Hostnamen "localhost", "loopback", "127.0.0.1" oder "[::1]" verwenden. Dieses Verhalten ist vorhanden, da ein Remoteproxyserver diese Adressen in der Regel nicht ordnungsgemäß auflöst.

Internet Explorer 9: Sie können den lokalen Computer mithilfe des Makros "<-loopback>" aus der Proxyumgehungsliste entfernen.

Das folgende Beispiel zeigt Beispielaufrufe von InternetOpen unter Verwendung unterschiedlicher Proxyumgehungszeichenfolgen. In den Kommentaren über jedem Aufruf wird beschrieben, welche Auswirkungen die Umgehungszeichenfolge auf die Hostnamen hat, auf die über das von ihr erzeugte HINTERNET-Handle zugegriffen wird.

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);

Verwenden von InternetConnect

Zum Starten einer Sitzung muss die InternetConnect-Funktion ein Handle aus dem Stammhandle erstellen, das von der InternetOpen-Funktion zurückgegeben wird. InternetConnect legt die Serveradresse, die Portnummer, den Benutzernamen, das Kennwort und den Typ des Diensts fest.

InternetConnect verwendet das von InternetOpen erstellte HINTERNET-Stammhandle, um ein Sitzungshandle einzurichten. Wenn das INTERNET_FLAG_ASYNC-Flag im Aufruf von InternetOpen festgelegt wurde, sollte der Aufruf von InternetConnect einen nichtzero-Kontextwert enthalten.

Der Servername kann entweder den Hostnamen (z. B. "www.servername.com") oder die IP-Nummer der Website im ASCII-Dezimalformat enthalten (z. B. "10.0.1.45").

Der Serverport ist die TCP/IP-Portnummer (Transmission Control Protocol/Internet Protocol), mit der eine Verbindung auf dem Server hergestellt werden soll. InternetConnect verwendet den Standardport für den ausgewählten Diensttyp, wenn der INTERNET_INVALID_PORT_NUMBER Wert verwendet wird. Die folgenden Tabellen enthalten die Serverportstandardeinstellungen für WinINet.

Wert	Bedeutung
INTERNET_DEFAULT_FTP_PORT	Verwenden Sie den Standardport für FTP-Server (Port 21).
INTERNET_DEFAULT_GOPHER_PORT	Verwenden Sie den Standardport für Gopherserver (Port 70). Hinweis: Nur Windows XP und Windows Server 2003 R2 und früher.
INTERNET_DEFAULT_HTTP_PORT	Verwenden Sie den Standardport für HTTP-Server (Port 80).
INTERNET_DEFAULT_HTTPS_PORT	Verwenden Sie den Standardport für HTTPS-Server (Port 443).
INTERNET_DEFAULT_SOCKS_PORT	Verwenden Sie den Standardport für SOCKS-Firewallserver (Port 1080).

Definieren des Benutzernamens und des Kennworts

Der Wert von lpszUsername ist die Adresse einer null-beendeten Zeichenfolge, die den Namen des Benutzers enthält, der sich anmeldet. Wenn dieser Parameter NULL ist, verwendet die Funktion mit Ausnahme von HTTP einen entsprechenden Standardwert. Ein NULL-Parameter in HTTP bewirkt, dass der Server einen Fehler zurückgibt. Für das FTP-Protokoll ist der Standardwert anonym.

Der Wert von lpszPassword ist die Adresse einer NULL-Zeichenfolge, die das Anmeldekennwort enthält. Wenn sowohl lpszUsername als auch lpszPasswordNULL sind, verwendet die Funktion das anonyme Standardkennwort. Im Falle von FTP ist das anonyme Standardkennwort der E-Mail-Name des Benutzers. Wenn lpszUsername nicht NULL und lpszPasswordNULL ist, verwendet die Funktion ein leeres Kennwort. Es gibt vier mögliche Einstellungen von lpszUsername und lpszPassword, die das in der folgenden Tabelle gezeigte Verhalten erzeugen.

lpszUsername	lpszPassword	An FTP-Server gesendeter Benutzername	An FTP-Server gesendetes Kennwort
NULL	NULL	"anonym"	E-Mail-Name des Benutzers
Nicht-NULL-Zeichenfolge	NULL	lpszUsername	""
NULL	Nicht-NULL-Zeichenfolge	ERROR	ERROR
Nicht-NULL-Zeichenfolge	Nicht-NULL-Zeichenfolge	lpszUsername	lpszPassword

Diese Informationen können mithilfe der Funktionen InternetSetOption und InternetErrorDlg geändert werden. InternetSetOption ändert die Werte für Benutzername und Kennwort, während InternetErrorDlg ein Dialogfeld anzeigt, in dem der richtige Benutzername und das richtige Kennwort angefordert werden.

Definieren der Sitzung

Um die sitzung zu definieren, die eingerichtet wird, legen Sie den Diensttyp, die Flags und den Kontextwert für InternetConnect fest.

Für InternetConnect stehen zwei Diensttypen zur Verfügung: INTERNET_SERVICE_FTP und INTERNET_SERVICE_HTTP. INTERNET_SERVICE_HTTP wird sowohl für HTTP- als auch für HTTPS-Sitzungen verwendet.

INTERNET_FLAG_PASSIVE ist das einzige dienstspezifische Flag, das von den WinINet-Funktionen verwendet wird. Dieses Flag kann festgelegt werden, wenn der Diensttyp INTERNET_SERVICE_FTP ist, um passive FTP-Semantik zu verwenden.

Für alle synchronen Vorgänge sollte der Wert von dwContext auf 0 (null) festgelegt werden. Wenn asynchrone Vorgänge durch Festlegen des INTERNET_FLAG_ASYNC-Flags im Aufruf von InternetOpen eingerichtet wurden, sollte für dwContext ein Wert ungleich null angegeben werden. Weitere Informationen zu asynchronen Vorgängen finden Sie unter Einrichten von asynchronen Vorgängen.

Bei FTP-Sitzungen versucht InternetConnect , eine Verbindung mit dem Server im Internet herzustellen. Bei HTTP-Sitzungen stellt InternetConnect erst dann eine Verbindung her, wenn eine andere Funktion versucht, Informationen vom Server abzurufen.

Hinweis

WinINet unterstützt keine Serverimplementierungen. Darüber hinaus sollte es nicht von einem Dienst verwendet werden. Verwenden Sie für Serverimplementierungen oder Dienste Microsoft Windows HTTP Services (WinHTTP).