WinHttpOpen-Funktion (winhttp.h)

  • Artikel

Die WinHttpOpen-Funktion initialisiert für eine Anwendung die Verwendung von WinHTTP-Funktionen und gibt ein WinHTTP-Sitzungshandle zurück.

Syntax

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

Parameter

[in, optional] pszAgentW

Ein Zeiger auf eine Zeichenfolgenvariable, die den Namen der Anwendung oder Entität enthält, die die WinHTTP-Funktionen aufruft. Dieser Name wird als Benutzer-Agent im HTTP-Protokoll verwendet.

[in] dwAccessType

Erforderliche Zugriffsart. Dies kann einer der folgenden Werte sein.

Wert Bedeutung
WINHTTP_ACCESS_TYPE_NO_PROXY
 Löst alle Hostnamen direkt ohne Proxy auf.
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
Wichtig Die Verwendung dieser Option ist auf Windows 8.1 und höher veraltet. Verwenden Sie stattdessen WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY.
 
Ruft den statischen Proxy oder die direkte Konfiguration aus der Registrierung ab. WINHTTP_ACCESS_TYPE_DEFAULT_PROXY erbt keine Browserproxyeinstellungen.

Die WinHTTP-Proxykonfiguration wird durch einen dieser Mechanismen festgelegt.
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 Übergibt Anforderungen an den Proxy, es sei denn, es wird eine Proxyumgehungsliste angegeben und der zu auflösende Name umgeht den Proxy. In diesem Fall verwendet diese Funktion die Werte, die für pwszProxyName und pwszProxyBypass übergeben werden.
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 Verwendet System- und Benutzerproxyeinstellungen (einschließlich der Internet-Explorer Proxykonfiguration), um zu bestimmen, welche Proxys/Proxys verwendet werden sollen. Versucht automatisch, ein Failover zwischen mehreren Proxys, verschiedenen Proxykonfigurationen pro Schnittstelle und Authentifizierung zu verarbeiten. Wird in Windows 8.1 und höher unterstützt.

[in] pszProxyW

Ein Zeiger auf eine Zeichenfolgenvariable, die den Namen des Proxyservers enthält, der verwendet werden soll, wenn der Proxyzugriff angegeben wird, indem dwAccessType auf WINHTTP_ACCESS_TYPE_NAMED_PROXY festgelegt wird. Die WinHTTP-Funktionen erkennen nur CERN-Typproxys für HTTP. Wenn dwAccessType nicht auf WINHTTP_ACCESS_TYPE_NAMED_PROXY festgelegt ist, muss dieser Parameter auf WINHTTP_NO_PROXY_NAME festgelegt werden.

[in] pszProxyBypassW

Ein Zeiger auf eine Zeichenfolgenvariable, die eine optionale durch Semikolon getrennte Liste von Hostnamen oder IP-Adressen oder beides enthält, die nicht über den Proxy weitergeleitet werden sollte, wenn dwAccessType auf WINHTTP_ACCESS_TYPE_NAMED_PROXY festgelegt ist. Die Liste kann Einen Feldhalter enthalten. Verwenden Sie keine leere Zeichenfolge, da die WinHttpOpen-Funktion sie als Proxyumgehungsliste verwendet. Wenn dieser Parameter das "<lokale>" Makro in der Liste als einzigen Eintrag angibt, umgeht diese Funktion jeden Hostnamen, der keinen Punkt enthält. Wenn dwAccessType nicht auf WINHTTP_ACCESS_TYPE_NAMED_PROXY festgelegt ist, muss dieser Parameter auf WINHTTP_NO_PROXY_BYPASS festgelegt werden.

[in] dwFlags

Lange ganzzahliger Wert ohne Vorzeichen, der die Flags enthält, die verschiedene Optionen angeben, die sich auf das Verhalten dieser Funktion auswirken. Dieser Parameter kann den folgenden Wert aufweisen.

Wert Bedeutung
WINHTTP_FLAG_ASYNC
 Verwenden Sie die WinHTTP-Funktionen asynchron. Standardmäßig werden alle WinHTTP-Funktionen, die das zurückgegebene HINTERNET-Handle verwenden, synchron ausgeführt. Wenn dieses Flag festgelegt ist, muss der Aufrufer eine Rückruffunktion über WinHttpSetStatusCallback angeben.
WINHTTP_FLAG_SECURE_DEFAULTS
 Wenn dieses Flag festgelegt ist, erfordert WinHttp die Verwendung von TLS 1.2 oder höher. Wenn der Aufrufer versucht, ältere TLS-Versionen durch Festlegen von WINHTTP_OPTION_SECURE_PROTOCOLS zu aktivieren, schlägt dies mit ERROR_ACCESS_DENIED fehl. Darüber hinaus wird das TLS-Fallback deaktiviert. Beachten Sie, dass durch Festlegen dieses Flags auch flag WINHTTP_FLAG_ASYNC festgelegt wird.

Rückgabewert

Gibt bei erfolgreicher Ausführung ein gültiges Sitzungshandle zurück, andernfalls NULL . Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen abzurufen. Zu den zurückgegebenen Fehlercodes gehören die folgenden.

Fehlercode BESCHREIBUNG
ERROR_WINHTTP_INTERNAL_ERROR
 Ein interner Fehler ist aufgetreten.
ERROR_NOT_ENOUGH_MEMORY
 Für den angeforderten Vorgang war nicht genügend Arbeitsspeicher verfügbar. (Windows-Fehlercode)

Hinweise

Es wird dringend empfohlen, WinHTTP im asynchronen Modus zu verwenden (das heißt, wenn WINHTTP_FLAG_ASYNC in WinHttpOpen festgelegt wurde, damit die Verwendung des zurückgegebenen HINTERNET asynchron wird). Der Rückgabewert weist auf Erfolg oder Fehler hin. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen abzurufen.

Die WinHttpOpen-Funktion ist die erste der WinHTTP-Funktionen, die von einer Anwendung aufgerufen werden. Sie initialisiert interne WinHTTP-Datenstrukturen und bereitet zukünftige Aufrufe der Anwendung vor. Wenn die Anwendung die Verwendung der WinHTTP-Funktionen abgeschlossen hat, muss winHttpCloseHandle aufgerufen werden, um das Sitzungshandle und alle zugehörigen Ressourcen freizugeben.

Die Anwendung kann eine beliebige Anzahl von Aufrufen an WinHttpOpen tätigen, obwohl ein einzelner Aufruf normalerweise ausreichend ist. Jeder Aufruf von WinHttpOpen öffnet einen neuen Sitzungskontext. Da Benutzerdaten nicht für mehrere Sitzungskontexte freigegeben werden, sollte eine Anwendung, die Anforderungen im Namen mehrerer Benutzer sendet, eine separate Sitzung für jeden Benutzer erstellen, um keine benutzerspezifischen Cookies und den Authentifizierungsstatus freizugeben. Die Anwendung sollte separate Verhaltensweisen für jede WinHttpOpen-instance definieren, z. B. für unterschiedliche Proxyserver, die für jeden konfiguriert sind.

Nachdem die aufrufende Anwendung das von WinHttpOpen zurückgegebene HINTERNET-Handle verwendet hat, muss es mit der WinHttpCloseHandle-Funktion geschlossen werden.

Hinweis Informationen zu Windows XP und Windows 2000 finden Sie unter Laufzeitanforderungen.
 

Beispiele

Der folgende Beispielcode zeigt, wie Sie den Standardwert für das Verbindungstimeout abrufen.


    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {


        // Use WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", 
                    GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winhttp.h
Bibliothek Winhttp.lib
DLL Winhttp.dll
Verteilbare Komponente WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000.

Weitere Informationen

Informationen zu Microsoft Windows HTTP-Diensten (WinHTTP)

WinHTTP-Versionen

WinHttpCloseHandle