1 files changed, 248 insertions, 0 deletions
diff --git a/files/fr/mozilla/add-ons/webextensions/api/runtime/port/index.html b/files/fr/mozilla/add-ons/webextensions/api/runtime/port/index.html
new file mode 100644
index 0000000000..eb8e904ad7
--- /dev/null
+++ b/files/fr/mozilla/add-ons/webextensions/api/runtime/port/index.html
@@ -0,0 +1,248 @@
+---
+title: runtime.Port
+slug: Mozilla/Add-ons/WebExtensions/API/runtime/Port
+tags:
+  - API
+  - Add-ons
+  - Extensionns
+  - Non-standard
+  - Reference
+  - Type
+  - WebExtensions
+  - port
+  - runtime
+translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/Port
+---
+<div>{{AddonSidebar()}}</div>
+
+<p>Un objet <code>Port</code> represente une extrémité d'une connexion entre deux contextes spécifiques, qui peut-être utilisée pour échanger des messages.</p>
+
+<p>Un côté initie la connexion à l'aide d'une API <code>connect()</code>. Cela retourne un objet <code>Port</code>. L'autre camp écoute les tentatives de connexion à l'aide d'un écouteur <code>onConnect</code>. Ceci est passé un objet <code>Port</code> correspondant.</p>
+
+<p>Une fois que les deux côtés ont des objets <code>Port,</code> ils peuvent échanger des messages JSON en utilisant <code>Port.postMessage()</code> et <code>Port.onMessage</code>. Quand ils sont terminés, chaque extrémité peut se déconnecter en utilisant <code>Port.disconnect()</code>, ce qui générera un événement <code>Port.onDisconnect</code> à l'autre extrémité, permettant à l'autre extrémité de faire le nettoyage requis.</p>
+
+<p>Vous pouvez utiliser ce modèle pour communiquer entre:</p>
+
+<ul>
+ <li>différentes parties de votre extension (par exemple, entre les <a href="/fr/Add-ons/WebExtensions/Content_scripts">scripts de contenus</a> et les <a href="/fr/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">scripts d'arrière-plan</a>)</li>
+ <li>entre votre extension et une <a href="/fr/Add-ons/WebExtensions/Native_messaging">application native s'exéutant sur l'ordinateur de l'utilisateur</a>.</li>
+ <li>entre votre extension et une extension différente</li>
+</ul>
+
+<p>Vous devez utiliser différentes API de connexion pour différents types de connexions, comme indiqué dans le tableau ci-dessous.</p>
+
+<table class="fullwidth-table standard-table">
+ <thead>
+  <tr>
+   <th scope="col">type de connection</th>
+   <th scope="col">Lancer une tentative de connexion</th>
+   <th scope="col">Gérer la tentative de connexion</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr>
+   <td>Script d'arrière-plan au script de contenu</td>
+   <td>{{WebExtAPIRef("tabs.connect()")}}</td>
+   <td>{{WebExtAPIRef("runtime.onConnect")}}</td>
+  </tr>
+  <tr>
+   <td>Script de contenu au script d'arrière-plan</td>
+   <td>{{WebExtAPIRef("runtime.connect()")}}</td>
+   <td>{{WebExtAPIRef("runtime.onConnect")}}</td>
+  </tr>
+  <tr>
+   <td>Extension à l'application native</td>
+   <td>{{WebExtAPIRef("runtime.connectNative()")}}</td>
+   <td>N'est pas applicable (voir <a href="/fr/Add-ons/WebExtensions/Native_messaging">Native messaging</a>).</td>
+  </tr>
+  <tr>
+   <td>Extension à l'extension</td>
+   <td>{{WebExtAPIRef("runtime.connect()")}}</td>
+   <td>{{WebExtAPIRef("runtime.onConnectExternal")}}</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Type">Type</h2>
+
+<p>Les valeurs de ce type sont des objets. Ils contiennent les propriétés suivantes :</p>
+
+<dl class="reference-values">
+ <dt><code>name</code></dt>
+ <dd><code>string</code>. Le nom du port, défini dans {{WebExtAPIRef("runtime.connect()")}} ou {{WebExtAPIRef("tabs.connect()")}} appel qui l'a créé. Si ce port est connecté à une application native, son nom est le nom de l'application native.</dd>
+ <dt><code>disconnect</code></dt>
+ <dd><code>function</code>. Déconnecte un port. Chaque extrémité peut appeler cela quand ils ont fini avec le port. Cela provoquera le déclenchement de <code>onDisconnect</code> à l'autre extrémité. Ceci est utile si l'autre extrémité maintient un état relatif à ce port, qui peut être nettoyé lors de la déconnexion. Si ce port est connecté à une application native, cette fonction ferme l'application native.</dd>
+ <dt><code>error</code></dt>
+ <dd><code>object</code>. Si le port a été déconnecté en raison d'une erreur, il sera défini sur un objet avec un <code>message</code>, de propriété de chaîne, vous donnant plus d'informations sur l'erreur. Voir <code>onDisconnect</code>.</dd>
+ <dt><code>onDisconnect</code></dt>
+ <dd>
+ <p><code>object</code>. Cela contient les fonctions <code>addListener()</code> et <code>removeListener()</code> communes à tous les événements pour les extensions créées à l'aide des API. WebExtension. Les fonctions de l'écouteur seront appelées lorsque l'autre extrémité aura appelé <code>Port.disconnect()</code>. Cet événement ne sera déclenché qu'une fois pour chaque port. La fonction d'écouteur recevra l'objet <code>Port</code>. Si le port a été déconnecté en raison d'une erreur, l'argument <code>Port</code> contiendra une propriété  <code>error</code> donnant plus d'informations sur l'erreur :</p>
+
+ <pre class="brush: js">port.onDisconnect.addListener((p) =&gt; {
+  if (p.error) {
+    console.log(`Disconnected due to an error: ${p.error.message}`);
+  }
+});</pre>
+
+ <p>Notez que dans Google Chrome <code>port.error</code> n'est pas supporté: utilisez plutôt  {{WebExtAPIRef("runtime.lastError")}} pour obtenir le message d'erreur.</p>
+ </dd>
+ <dt><code>onMessage</code></dt>
+ <dd><code>object</code>. Cela contient les fonctions <code>addListener()</code> et <code>removeListener()</code> communes à tous les événements pour les extensions créées à l'aide des API WebExtension. Les fonctions de l'écouteur seront appelées lorsque l'autre extrémité aura envoyé un message à ce port. L'écouteur recevra l'objet JSON envoyé par l'autre extrémité.</dd>
+ <dt><code>postMessage</code></dt>
+ <dd><code>function</code>. Envoyer un message à l'autre extrémité. Cela prend un argument, qui est un objet JSON représentant le message à envoyer. Il sera fourni à tout script écoutant l'événement <code>onMessage</code> du port, ou à l'application native si ce port est connecté à une application native.</dd>
+ <dt><code>sender</code>{{optional_inline}}</dt>
+ <dd>{{WebExtAPIRef('runtime.MessageSender')}}. Contient des informations sur l'expéditeur du message. ette propriété ne sera présente que sur les ports transmis aux écouteurs <code>onConnect</code>/<code>onConnectExternal</code>.</dd>
+</dl>
+
+<h2 id="Compatibilité_du_navigateur">Compatibilité du navigateur</h2>
+
+<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p>
+
+<p>{{Compat("webextensions.api.runtime.Port")}}</p>
+
+<h2 id="Exemples">Exemples</h2>
+
+<h3 id="Connecting_from_content_scripts">Connecting from content scripts</h3>
+
+<p>This content script:</p>
+
+<ul>
+ <li>connects to the background script and stores the <code>Port</code> in a variable called <code>myPort</code>.</li>
+ <li>listens for messages on <code>myPort</code> and logs them.</li>
+ <li>sends messages to the background script, using <code>myPort</code>, when the user clicks the document.</li>
+</ul>
+
+<pre class="brush: js line-numbers  language-js"><code class="language-js"><span class="comment token">// content-script.js</span>
+
+<span class="keyword token">var</span> myPort <span class="operator token">=</span> browser<span class="punctuation token">.</span>runtime<span class="punctuation token">.</span><span class="function token">connect</span><span class="punctuation token">(</span><span class="punctuation token">{</span>name<span class="punctuation token">:</span><span class="string token">"port-from-cs"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+myPort<span class="punctuation token">.</span><span class="function token">postMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span>greeting<span class="punctuation token">:</span> <span class="string token">"hello from content script"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+
+myPort<span class="punctuation token">.</span>onMessage<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span><span class="keyword token">function</span><span class="punctuation token">(</span>m<span class="punctuation token">)</span> <span class="punctuation token">{</span>
+  console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span><span class="string token">"In content script, received message from background script: "</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+  console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>m<span class="punctuation token">.</span>greeting<span class="punctuation token">)</span><span class="punctuation token">;</span>
+<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+
+document<span class="punctuation token">.</span>body<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">"click"</span><span class="punctuation token">,</span> <span class="keyword token">function</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span>
+  myPort<span class="punctuation token">.</span><span class="function token">postMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span>greeting<span class="punctuation token">:</span> <span class="string token">"they clicked the page!"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre>
+
+<p>The corresponding background script:</p>
+
+<ul>
+ <li>listens for connection attempts from the content script.</li>
+ <li>when it receives a connection attempt:
+  <ul>
+   <li>stores the port in a variable named <code>portFromCS</code>.</li>
+   <li>sends the content script a message using the port.</li>
+   <li>starts listening to messages received on the port, and logs them.</li>
+  </ul>
+ </li>
+ <li>sends messages to the content script, using <code>portFromCS</code>, when the user clicks the extension's browser action.</li>
+</ul>
+
+<pre class="brush: js line-numbers  language-js"><code class="language-js"><span class="comment token">// background-script.js</span>
+
+<span class="keyword token">var</span> portFromCS<span class="punctuation token">;</span>
+
+<span class="keyword token">function</span> <span class="function token">connected</span><span class="punctuation token">(</span>p<span class="punctuation token">)</span> <span class="punctuation token">{</span>
+  portFromCS <span class="operator token">=</span> p<span class="punctuation token">;</span>
+  portFromCS<span class="punctuation token">.</span><span class="function token">postMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span>greeting<span class="punctuation token">:</span> <span class="string token">"hi there content script!"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+  portFromCS<span class="punctuation token">.</span>onMessage<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span><span class="keyword token">function</span><span class="punctuation token">(</span>m<span class="punctuation token">)</span> <span class="punctuation token">{</span>
+    console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span><span class="string token">"In background script, received message from content script"</span><span class="punctuation token">)</span>
+    console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>m<span class="punctuation token">.</span>greeting<span class="punctuation token">)</span><span class="punctuation token">;</span>
+  <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+<span class="punctuation token">}</span>
+
+browser<span class="punctuation token">.</span>runtime<span class="punctuation token">.</span>onConnect<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>connected<span class="punctuation token">)</span><span class="punctuation token">;</span>
+
+browser<span class="punctuation token">.</span>browserAction<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span><span class="keyword token">function</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span>
+  portFromCS<span class="punctuation token">.</span><span class="function token">postMessage</span><span class="punctuation token">(</span><span class="punctuation token">{</span>greeting<span class="punctuation token">:</span> <span class="string token">"they clicked the button!"</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre>
+
+<h4 id="Script_à_contenu_multiple">Script à contenu multiple</h4>
+
+<p>Si plusieurs scripts de contenu communiquent en même temps, vous voudrez peut-être stocker chaque connexion dans un tableau.</p>
+
+<ul>
+</ul>
+
+<pre class="brush: js">// background-script.js
+
+var ports = []
+
+function connected(p) {
+  ports[p.sender.tab.id]    = p
+  //...
+}
+
+browser.runtime.onConnect.addListener(connected)
+
+browser.browserAction.onClicked.addListener(function() {
+  ports.forEach(p =&gt; {
+        p.postMessage({greeting: "they clicked the button!"})
+    })
+});</pre>
+
+<h3 id="Connecting_to_native_applications">Connecting to native applications</h3>
+
+<p>This example connects to the native application "ping_pong" and starts listening for messages from it. It also sends the native application a message when the user clicks a browser action icon:</p>
+
+<pre class="brush: js">/*
+On startup, connect to the "ping_pong" app.
+*/
+var port = browser.runtime.connectNative("ping_pong");
+
+/*
+Listen for messages from the app.
+*/
+port.onMessage.addListener((response) =&gt; {
+  console.log("Received: " + response);
+});
+
+/*
+On a click on the browser action, send the app a message.
+*/
+browser.browserAction.onClicked.addListener(() =&gt; {
+  console.log("Sending:  ping");
+  port.postMessage("ping");
+});</pre>
+
+<p>{{WebExtExamples}}</p>
+
+<div class="note"><strong>Remerciements :</strong>
+
+<p>Cette API est basée sur l'API Chromium <a href="https://developer.chrome.com/extensions/runtime#event-onConnect"><code>chrome.runtime</code></a>. Cette documentation est dérivée de <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/runtime.json"><code>runtime.json</code></a> dans le code de Chromium code.</p>
+
+<p>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.</p>
+</div>
+
+<div class="hidden">
+<pre>// Copyright 2015 The Chromium Authors. All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//    * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//    * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//    * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+</pre>
+</div>