runtime.Port

A Port object provides a dedicated messaging channel between two specific endpoints.

You can use a Port to communicate:

• within your extension (for example, between content scripts running in a particular tab and your extension's background scripts)
• with other extensions
• with web pages.

You create a Port object by calling runtime.connect() or, if you are connecting to content scripts running in a tab, by calling tabs.connect().

The other end can listen for the new port using runtime.onConnect for intra-extension ports, or runtime.onConnectExternal for extension-to-extension or page-to-extension ports.

Each end can then send messages using Port.postMessage() and receive messages using Port.onMessage.

Each end can disconnect using Port.disconnect(), which will generate a Port.onDisconnect event at the other end, enabling the other end to do any cleanup.

Type

Values of this type are objects. They contain the following properties:

name

string. The port's name, defined in the runtime.connect() or tabs.connect() call that created it.

disconnect

function. Disconnects a port. One end can call this when they have finished with the port. It will cause onDisconnect to be fired at the other end. This is useful if the other end is maintaining some state relating to this port, which can be cleaned up on disconnect.

onDisconnect

events.Event. This has the addListener() and removeListener() functions common to all events in WebExtensions. Listener functions will be called when the other end has called Port.disconnect(). This event will only be fired once for each port.

onMessage

events.Event. This has the addListener() and removeListener() functions common to all events in WebExtensions. Listener functions will be called when the other end has called Port.postMessage(). The listener will be passed the JSON object that the other end passed to Port.postMessage().

postMessage

function. Send a message to the other end. This takes one argument, which is a JSON object representing the message to send. It will be delivered to anyone listening to the port's onMessage event.

senderOptional

runtime.MessageSender. Contains information about the sender of the message. This property will only be present on ports passed to onConnect/onConnectExternal listeners.

Browser compatibility

// 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.