WinHttpOpen-Funktion (winhttp.h)

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.

[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.

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.

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.

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

Weitere Informationen

Informationen zu Microsoft Windows HTTP-Diensten (WinHTTP)

WinHTTP-Versionen

WinHttpCloseHandle