WinHttpGetProxyForUrlEx-Funktion (winhttp.h)

Artikel
03/04/2024

Die WinHttpGetProxyForUrlEx-Funktion ruft die Proxydaten für die angegebene URL ab.

Syntax

WINHTTPAPI DWORD WinHttpGetProxyForUrlEx(
  [in] HINTERNET                 hResolver,
  [in] PCWSTR                    pcwszUrl,
  [in] WINHTTP_AUTOPROXY_OPTIONS *pAutoProxyOptions,
  [in] DWORD_PTR                 pContext
);

Parameter

[in] hResolver

Das WinHTTP-Resolverhandle, das von der WinHttpCreateProxyResolver-Funktion zurückgegeben wird.

[in] pcwszUrl

Ein Zeiger auf eine Unicode-Zeichenfolge mit NULL-Beendigung, die eine URL enthält, für die Proxyinformationen bestimmt werden.

[in] pAutoProxyOptions

Ein Zeiger auf eine WINHTTP_AUTOPROXY_OPTIONS-Struktur , die die zu verwendenden Optionen für den automatischen Proxy angibt.

[in] pContext

Kontextdaten, die an die Rückruffunktion für den Abschluss übergeben werden.

Rückgabewert

Ein status Code, der das Ergebnis des Vorgangs angibt.

Die folgenden Codes können zurückgegeben werden.	BESCHREIBUNG
ERROR_IO_PENDING	Der Vorgang wird asynchron fortgesetzt.
ERROR_WINHTTP_AUTO_PROXY_SERVICE_ERROR	Wird von WinHttpGetProxyForUrlEx zurückgegeben, wenn kein Proxy für die angegebene URL gefunden werden kann.
ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT	Fehler beim Ausführen des Skriptcodes in der PAC-Datei (Proxy Auto-Configuration).
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Der Typ des angegebenen Handles ist für diesen Vorgang falsch.
ERROR_WINHTTP_INVALID_URL	Die URL ist ungültig.
ERROR_WINHTTP_OPERATION_CANCELLED	Der Vorgang wurde abgebrochen, in der Regel, weil das Handle, für das die Anforderung ausgeführt wurde, vor Abschluss des Vorgangs geschlossen wurde.
ERROR_WINHTTP_UNABLE_TO_DOWNLOAD_SCRIPT	Die PAC-Datei konnte nicht heruntergeladen werden. Beispielsweise war der Server, auf den von der PAC-URL verwiesen wird, möglicherweise nicht erreichbar, oder der Server hat die Antwort 404 NOT FOUND zurückgegeben.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Die URL der PAC-Datei gibt ein anderes Schema als "http:" oder "https:" an.
ERROR_NOT_ENOUGH_MEMORY	Es war nicht genügend Arbeitsspeicher verfügbar, um den angeforderten Vorgang abzuschließen. (Windows-Fehlercode)

Hinweise

Diese Funktion implementiert das WPAD-Protokoll (Web Proxy Auto-Discovery) zum automatischen Konfigurieren der Proxyeinstellungen für eine HTTP-Anforderung. Das WPAD-Protokoll lädt eine PAC-Datei (Proxy Auto-Configuration) herunter. Hierbei handelt es sich um ein Skript, das den Proxyserver identifiziert, der für eine bestimmte Ziel-URL verwendet werden soll. PAC-Dateien werden in der Regel von der IT-Abteilung innerhalb einer Unternehmensnetzwerkumgebung bereitgestellt. Die URL der PAC-Datei kann entweder explizit angegeben werden, oder WinHttpGetProxyForUrlEx kann angewiesen werden, den Speicherort der PAC-Datei im lokalen Netzwerk automatisch zu ermitteln.

WinHttpGetProxyForUrlEx unterstützt nur ECMAScript-basierte PAC-Dateien.

WinHttpGetProxyForUrlEx muss pro URL aufgerufen werden, da die PAC-Datei einen anderen Proxyserver für verschiedene URLs zurückgeben kann. Dies ist nützlich, da die PAC-Datei es einer IT-Abteilung ermöglicht, einen Proxyserverlastenausgleich zu implementieren, indem die Ziel-URL (durch den Parameter lpcwszUrl angegeben) einem bestimmten Proxy in einem Proxyserverarray zugeordnet (Hashing) zugeordnet wird.

WinHttpGetProxyForUrlEx speichert die Autoproxy-URL und das Autoproxyskript zwischen, wenn die automatische Ermittlung im dwFlags-Element der pAutoProxyOptions-Struktur angegeben ist. Weitere Informationen finden Sie unter Autoproxy-Cache.

WinHttpGetProxyForUrlEx stellt eine vollständig asynchrone und abbruchfähige API bereit, die WinHttpGetProxyForUrl nicht unterstützt. WinHttpGetProxyForUrlEx stellt der Anwendung auch die vollständige Proxyliste bereit, die vom PAC-Skript zurückgegeben wurde, sodass die Anwendung das Failover auf "DIRECT" besser verarbeiten und BEI Bedarf SOCKS verstehen kann.

WinHttpGetProxyForUrlEx wird immer asynchron ausgeführt und gibt sofort mit ERROR_IO_PENDING bei Erfolg zurück. Der Rückruf wird durch Aufrufen von WinHttpSetStatusCallback auf der von WinHttpOpen bereitgestelltenhSession festgelegt. Rufen Sie alternativ WinHttpSetStatusCallback für den von WinHttpCreateProxyResolver bereitgestellten hResolver auf, um einen bestimmten Rückruf für jeden Aufruf zu erhalten.

Sie müssen WinHttpSetStatusCallback vor WinHttpCreateProxyResolver aufrufen. Verwenden Sie beim Aufrufen von WinHttpSetStatusCallbackWINHTTP_CALLBACK_FLAG_REQUEST_ERROR | WINHTTP_CALLBACK_FLAG_GETPROXYFORURL_COMPLETE. Informationen zur Verwendung des Rückrufs finden Sie unter WINHTTP_STATUS_CALLBACK .

Sobald ein Rückruf von status WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE zurückgegeben wird, kann die Anwendung WinHttpGetProxyResult für das Resolverhandle aufrufen, das zum Ausgeben von WinHttpGetProxyForUrlEx verwendet wird, um die Ergebnisse dieses Aufrufs zu erhalten.

Wenn der Aufruf nach der Rückgabe von ERROR_IO_PENDING fehlschlägt, wird ein Rückruf von WINHTTP_CALLBACK_STATUS_REQUEST_ERROR ausgegeben.

Diese Funktion führt immer out-of-process aus.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winhttp.h
Bibliothek	Winhttp.lib
DLL	Winhttp.dll

Freigeben über