proxy.register()

Enregistre un fichier PAC (Proxy Auto-Configuration). Le fichier est exécuté immédiatement, et sa fonction FindProxyForURL() sera appelée pour toutes les demandes HTTP, HTTPS ou FTP.

Si les fichiers PAC sont enregistrés par plusieurs extensions, les demandes seront initialement transmises à celle qui a été enregistrée en premier.

  • Si la fonction FindProxyForURL() dans le premier PAC renvoie "DIRECT" pour une demande, alors la demande sera transmise inchangée à la fonction  FindProxyForURL() dans le prochain PAC.
  • Si la fonction FindProxyForURL() dans le premier PAC transfère la requête en renvoyant "PROXY" ou une autre valeur proxy, l'URL du proxy sera transmise à la fonction FindProxyForURL() dans le prochain PAC.

Chaque extension ne peut enregistrer qu'un seul fichier PAC : si vous appelez  register() deux fois, le second fichier PACremplacera le premier.

C'est une fonction asynchrone qui renvoie une Promise.

Communiquez avec les fichiers PAC

Vous pouvez échanger des messages entre le fichier PAC et la page d'arrière-plan de votre extension (ou toute autre page privilégiée, comme les pages contextuelles) en utilisant runtime.sendMessage() et runtime.onMessage.

Pour envoyer un message au fichier PAC, vous devez définir l'option toProxyScript :

// background.js

// Log any messages from the proxy.
browser.runtime.onMessage.addListener((message, sender) => {
  if (sender.url === browser.extension.getURL(proxyScriptURL)) {
    console.log(message);
  }
});

let messageToProxy = {
  enabled: true,
  foo: "A string",
  bar: 1234
};

browser.runtime.sendMessage(messageToProxy, {toProxyScript: true});
// pac.js

browser.runtime.onMessage.addListener((message) => {
  if (message.enabled) {
    browser.runtime.sendMessage("I'm enabled!");
  }
});

Spécification de fichier PAC

La syntaxe de base du fichier PAC est décrite dans la documentation PAC, mais l'implémentation utilisée par l'API proxy diffère de la conception PAC standard de différentes manières, décrites dans cette section.

Valeur retournée FindProxyForURL()

La norme FindProxyForURL() renvoie une chaîne. Dans Firefox 55 et 56, le fichier PAC utilisé avec l'API proxy renvoie également une chaîne. Dans Firefox 55 seulement, vous devez passer un argument à la valeur de retour "DIRECT", même s'il n'a pas besoin d'argument.

À partir de Firefox 57, FindProxyForURL() peut toujours renvoyer une chaîne, mais peut également (et de préférence) renvoyer un tableau d'objets  proxy.ProxyInfo.

Si le tableau contient plus d'un objet, alors tous les objets ProxyInfo après le premier représentent les basculements : si le proxy à la position N dans le tableau n'est pas accessible quand son ProxyInfo.failoverTimeout expire, alors le navigateur essaiera le proxy à la position N + 1.

Par exemple :

const proxySpecification = [
  {
    type: "socks",
    host: "foo.com",
    port: 1080,
    proxyDNS: true,
    failoverTimeout: 5
  },
  {
    type: "socks",
    host: "bar.com",
    port: 1060,
  }
];

Le premier proxy dans le tableau sera essayé en premier. S'il ne répond pas dans failoverTimeout secondes, le prochain sera essayé, jusqu'à ce que la fin du tableau est atteint.

Environnement du fichier PAC

Les fonctions globales d'assistance généralement disponibles pour les fichiers PAC  (isPlainHostName(), dnsDomainIs(), etc) ne sont pas disponibles.

Le code qui s'exécute dans le fichier PAC n'a pas accès à :

//  pac.js

// send the log message to the background script
browser.runtime.sendMessage(`Proxy-blocker: blocked ${url}`);
// background-script.js

function handleMessage(message, sender) {
  // only handle messages from the proxy script
  if (sender.url != browser.extension.getURL(proxyScriptURL)) {
    return;
  }
  console.log(message);
}

browser.runtime.onMessage.addListener(handleMessage);

 

Syntaxe

var registering = browser.proxy.register(
  url   // string
)

Paramètres

url
String. URL pointant vers le fichier PAC à charger. Les fichiers PAC doivent être groupés avec l'extension, et l'url doit être relative au fichier manifest.json de l'extension.

Valeur retournée

Une Promise qui sera remplie sans argument lorsque le fichier PAC a été enregistré ou rejetée en cas d'erreur.

Compatibilité du navigateur

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxOperaFirefox pour Android
Support simpleChrome Aucun support NonEdge Aucun support NonFirefox Support complet 56
Support complet 56
Support complet 55
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : registerProxyScript
Opera Aucun support NonFirefox Android Support complet 56
Support complet 56
Support complet 55
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : registerProxyScript

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Cette fonctionnalité utilise un nom non-standard.
Cette fonctionnalité utilise un nom non-standard.

Exemples

const proxyScriptURL = "proxy/proxy-script.js";

browser.proxy.register(proxyScriptURL);

Example extensions

Remerciements :

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.

Étiquettes et contributeurs liés au document

Contributeurs à cette page : hellosct1
Dernière mise à jour par : hellosct1,