Méthode IBackgroundCopyJob ::SetProxySettings (bits.h)

Article
02/28/2024

Spécifie le proxy à utiliser pour transférer des fichiers.

Syntaxe

HRESULT SetProxySettings(
  [in] BG_JOB_PROXY_USAGE ProxyUsage,
  [in] const WCHAR        *ProxyList,
  [in] const WCHAR        *ProxyBypassList
);

Paramètres

[in] ProxyUsage

Spécifie s’il convient d’utiliser les paramètres de proxy de l’utilisateur, de ne pas utiliser de proxy ou d’utiliser les paramètres de proxy spécifiés par l’application. La valeur par défaut consiste à utiliser les paramètres de proxy de l’utilisateur, BG_JOB_PROXY_USAGE_PRECONFIG. Pour obtenir la liste des options de proxy, consultez l’énumération BG_JOB_PROXY_USAGE .

[in] ProxyList

Chaîne terminée par null qui contient les proxys à utiliser pour transférer des fichiers. La liste est délimitée par des espaces. Pour plus d’informations sur la spécification d’un proxy, consultez Remarques.

Ce paramètre doit avoir la valeur NULL si la valeur de ProxyUsage est BG_JOB_PROXY_USAGE_PRECONFIG, BG_JOB_PROXY_USAGE_NO_PROXY ou BG_JOB_PROXY_USAGE_AUTODETECT.

La longueur de la liste des proxys est limitée à 4 000 caractères, sans compter la terminaison null.

[in] ProxyBypassList

Chaîne terminée par null qui contient une liste facultative de noms d’hôtes, d’adresses IP ou des deux, qui peuvent contourner le proxy. La liste est délimitée par des espaces. Pour plus d’informations sur la spécification d’un proxy de contournement, consultez Remarques.

Ce paramètre doit avoir la valeur NULL si la valeur de ProxyUsage est BG_JOB_PROXY_USAGE_PRECONFIG, BG_JOB_PROXY_USAGE_NO_PROXY ou BG_JOB_PROXY_USAGE_AUTODETECT.

La longueur de la liste de contournement de proxy est limitée à 4 000 caractères, à l’exception de la fin null.

Valeur retournée

Cette méthode retourne les valeurs HRESULT suivantes, ainsi que d’autres.

Code de retour	Description
S_OK	Le proxy a été correctement spécifié.
E_NOTIMPL	La valeur de ProxyUsage n’est pas définie dans l’énumération BG_JOB_PROXY_USAGE .
BG_E_PROXY_LIST_TOO_LARGE	La mémoire tampon pProxyList ne peut pas dépasser 32 Ko.
BG_E_PROXY_BYPASS_LIST_TOO_LARGE	Le pProxyBypassList ne peut pas dépasser 32 Ko.
BG_E_INVALID_STATE	L’état du travail ne peut pas être BG_JOB_STATE_CANCELLED ou BG_JOB_STATE_ACKNOWLEDGED.
E_INVALIDARG	Le paramètre pProxyList ne peut pas être NULL si ProxyUsage est BG_JOB_PROXY_USAGE_OVERRIDE.

Remarques

Les informations de proxy que vous fournissez sont validées au moment de l’exécution. Si les informations du proxy ne sont pas valides, le travail entre dans l’état BG_JOB_STATE_ERROR avec un code d’erreur BG_E_INVALID_PROXY_INFO .

Si votre service s’exécute en tant que LocalSystem, vous devez utiliser la méthode SetProxySettings pour spécifier explicitement une liste de proxy ou de contournement de proxy pour le compte et définir ProxyUsage sur BG_JOB_PROXY_USAGE_OVERRIDE. Pour plus d’informations sur l’utilisation de comptes système avec BITS, consultez Comptes de service et BITS.

BITS ne reconnaît pas les paramètres de proxy définis à l’aide du fichier Proxycfg.exe.

Spécifiez un proxy comme suit :

« [protocol=][protocol » ://"]server[ » :"port] »

Les protocoles valides sont HTTP et HTTPS. La liste des proxys peut contenir le numéro de port utilisé pour accéder au proxy. Par exemple, pour répertorier un proxy HTTP, une chaîne valide est « http=http ://http_proxy_name :80 », où http_proxy_name est le nom du serveur proxy et 80 est le numéro de port que vous devez utiliser pour accéder au proxy. Si le proxy utilise le numéro de port par défaut pour ce protocole, vous pouvez omettre le numéro de port. Si un nom de proxy est répertorié par lui-même, vous pouvez l’utiliser comme proxy par défaut pour tous les protocoles qui n’ont pas de proxy spécifié. Par exemple, « http=http ://http_proxyother_proxy » utilise http_proxy pour toutes les opérations HTTP, tandis que le protocole HTTPS utilise le proxy nommé other_proxy.

Vous pouvez répertorier les noms d’hôtes ou les adresses IP (Internet Protocol) connus localement dans la liste de contournement des proxys. Ce nom peut contenir des caractères génériques, tels que « », qui obligent l’application à contourner le serveur proxy pour les adresses qui correspondent au modèle spécifié, par exemple, « .microsoft.com » ou « .org ». Les caractères génériques doivent être les caractères les plus à gauche du nom. Par exemple, « aaa ». n’est pas pris en charge. Vous pouvez spécifier la <macro locale> pour indiquer que tous les sites intranet locaux sont contournés. Les sites intranet locaux sont considérés comme tous les serveurs qui ne contiennent pas de point dans leur nom.

BITS utilise les paramètres de proxy Internet Explorer de l’utilisateur si une application ne spécifie pas d’utilisation de proxy. Ce comportement par défaut fonctionne généralement si l’application envoie le travail dans le contexte d’un utilisateur interactif, mais peut ne pas fonctionner si un service exécuté en tant que LocalSystem envoie le travail. Vous pouvez spécifier les paramètres de proxy Internet Explorer pour LocalSystem. Toutefois, il est difficile de détecter ces paramètres en cas de problème.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP
Serveur minimal pris en charge	Windows Server 2003
Plateforme cible	Windows
En-tête	bits.h
Bibliothèque	Bits.lib
DLL	QmgrPrxy.dll

Voir aussi

BG_JOB_PROXY_USAGE

IBackgroundCopyJob ::GetProxySettings