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.
| Wert | Bedeutung |
|---|---|
|
Löst alle Hostnamen direkt ohne Proxy auf. |
|
Wichtig Die Verwendung dieser Option ist auf Windows 8.1 und höher veraltet. Verwenden Sie stattdessen WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY.
Die WinHTTP-Proxykonfiguration wird durch einen dieser Mechanismen festgelegt.
|
|
Ü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. |
|
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 |
|---|---|
|
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. |
|
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 |
|---|---|
|
Ein interner Fehler ist aufgetreten. |
|
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.
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. |