WinHttpGetProxyForUrlEx, fonction (winhttp.h)

Article
08/27/2023

La fonction WinHttpGetProxyForUrlEx récupère les données de proxy pour l’URL spécifiée.

Syntaxe

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

Paramètres

[in] hResolver

Handle du programme de résolution WinHTTP retourné par la fonction WinHttpCreateProxyResolver .

[in] pcwszUrl

Pointeur vers une chaîne Unicode terminée par un caractère Null qui contient une URL pour laquelle les informations de proxy seront déterminées.

[in] pAutoProxyOptions

Pointeur vers une structure de WINHTTP_AUTOPROXY_OPTIONS qui spécifie les options de proxy automatique à utiliser.

[in] pContext

Données de contexte qui seront passées à la fonction de rappel d’achèvement.

Valeur retournée

Code status indiquant le résultat de l’opération.

Les codes suivants peuvent être retournés.	Description
ERROR_IO_PENDING	L’opération se poursuit de manière asynchrone.
ERROR_WINHTTP_AUTO_PROXY_SERVICE_ERROR	Retourné par WinHttpGetProxyForUrlEx lorsqu’un proxy pour l’URL spécifiée est introuvable.
ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT	Une erreur s’est produite lors de l’exécution du code de script dans le fichier PAC (Proxy Auto-Configuration).
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Le type de handle fourni est incorrect pour cette opération.
ERROR_WINHTTP_INVALID_URL	L’URL n’est pas valide.
ERROR_WINHTTP_OPERATION_CANCELLED	L’opération a été annulée, généralement parce que le handle sur lequel la requête fonctionnait a été fermé avant la fin de l’opération.
ERROR_WINHTTP_UNABLE_TO_DOWNLOAD_SCRIPT	Impossible de télécharger le fichier PAC. Par exemple, le serveur référencé par l’URL PAC n’a peut-être pas été accessible, ou le serveur a retourné une réponse 404 NOT FOUND.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	L’URL du fichier PAC a spécifié un schéma autre que « http : » ou « https : ».
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible était insuffisante pour terminer l’opération demandée. (Code d’erreur Windows)

Remarques

Cette fonction implémente le protocole WPAD (Web Proxy Auto-Discovery) pour configurer automatiquement les paramètres de proxy pour une requête HTTP. Le protocole WPAD télécharge un fichier PAC (Proxy Auto-Configuration), qui est un script qui identifie le serveur proxy à utiliser pour une URL cible donnée. Les fichiers PAC sont généralement déployés par le service informatique au sein d’un environnement réseau d’entreprise. L’URL du fichier PAC peut être spécifiée explicitement ou WinHttpGetProxyForUrlEx peut être invité à découvrir automatiquement l’emplacement du fichier PAC sur le réseau local.

WinHttpGetProxyForUrlEx prend uniquement en charge les fichiers PAC basés sur ECMAScript.

WinHttpGetProxyForUrlEx doit être appelé par URL, car le fichier PAC peut retourner un serveur proxy différent pour différentes URL. Cela est utile, car le fichier PAC permet à un service informatique d’implémenter l’équilibrage de charge du serveur proxy en mappant (hachage) l’URL cible (spécifiée par le paramètre lpcwszUrl ) à un certain proxy dans un tableau de serveurs proxy.

WinHttpGetProxyForUrlEx met en cache l’URL autoproxy et le script autoproxy lorsque la découverte automatique est spécifiée dans le membre dwFlags de la structure pAutoProxyOptions . Pour plus d’informations, consultez Cache autoproxy.

WinHttpGetProxyForUrlEx fournit une API entièrement asynchrone et annulable que WinHttpGetProxyForUrl ne fait pas. WinHttpGetProxyForUrlEx fournit également à l’application la liste complète des proxys retournée par le script PAC, ce qui permet à l’application de mieux gérer le basculement vers « DIRECT » et de comprendre SOCKS si vous le souhaitez.

WinHttpGetProxyForUrlEx s’exécute toujours de manière asynchrone et retourne immédiatement avec ERROR_IO_PENDING en cas de réussite. Le rappel est défini en appelant WinHttpSetStatusCallback sur la session hSession fournie par WinHttpOpen. Vous pouvez également appeler WinHttpSetStatusCallback sur le hResolver fourni par WinHttpCreateProxyResolver pour avoir un rappel spécifique pour chaque appel.

Vous devez appeler WinHttpSetStatusCallback avant WinHttpCreateProxyResolver. Lors de l’appel de WinHttpSetStatusCallback, utilisez WINHTTP_CALLBACK_FLAG_REQUEST_ERROR | WINHTTP_CALLBACK_FLAG_GETPROXYFORURL_COMPLETE. Pour plus d’informations sur l’utilisation du rappel, consultez WINHTTP_STATUS_CALLBACK.

Une fois qu’un rappel de status WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE est retourné, l’application peut appeler WinHttpGetProxyResult sur le handle du programme de résolution utilisé pour émettre WinHttpGetProxyForUrlEx pour recevoir les résultats de cet appel.

Si l’appel échoue après avoir retourné ERROR_IO_PENDING un rappel de WINHTTP_CALLBACK_STATUS_REQUEST_ERROR est émis.

Cette fonction s’exécute toujours hors processus.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winhttp.h
Bibliothèque	Winhttp.lib
DLL	Winhttp.dll

Partager via