Various applications of Browser Extensions need a mechanism to communicate with local client native processes outside of the browser environment. This specification proposes such a mechanism.

This specification is not actively maintained. Issues previously filed against it can be read on github. A public archived mailing list was also available, but was reserved for high level discussions, and was not appropriate for specific comments about this document.

Work on this document is governed by the charter of the Browser Extension CG, which includes among other things the Communication, Decision, and Contribution policies of this community group.

Implementation of the technologies discussed and tentatively specified in this Community Group is ongoing and none of the original contributors have expressed opposition to this work. However, due to various circumstances, the level of participation has dropped below the level at which productive discussion is possible, and activity in this group has stopped as a result.

The specifications have therefore not been maintained in a while, and are out of date.

In the meanwhile, a new “WebExtensions Community Group”, with similar objectives but much more active participation, has sprung up. People interested in this topic are encouraged to join that group.

Introduction

The Browser Extensions Community Group's goal is to make browser extension code much more interoperable across browsers by specifying common extension interfaces and well-defined browser behavior.

This specification defines the interfaces and behavior which enables extensions to communicate with local client native processes outside of the browser environment.

It is not a goal of this specification to define:

Core APIs

The goal for these APIs is to provide functionality that extension authors need for message-passing between extensions and local client native process outside of the browser. Methods are provided for both establishing long-lived connection ports and for sending individual "one-shot" messages.

The runtime object

Overview

In addition to the base functionality of the browser.runtime object defined in the [[!browserext]] Browser Extensions specification, these additional APIs provide functionaly for Native Messaging.

Manifest

The "nativeMessaging" permission is required to use these additional APIs. 

{
    "permissions": [                               // Required
        "nativeMessaging"                          // Required
    ]                                              // Required   
}

Context

This API is available only in background pages, a subset of the Window context.

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in the [[!browserext]] Browser Extensions specification. 

dictionary BrowserExtRuntimePort {
    Function disconnect;
    DOMString name;
    object onDisconnect;
    object onMessage;
    Function postMessage;
    MessageSender sender;
};
callback BrowserExtRuntimeSendNativeMessageCallback = void (any response);
[NoInterfaceObject]
partial interface BrowserExtBrowserRuntimeNativeMessaging {
    BrowserExtRuntimePort connectNative(DOMString nativeServiceName);
    void sendNativeMessage(DOMString nativeServiceName, object message, optional RuntimeSendNativeMessageCallback callback);
    attribute BrowserExtRuntimePort Port;
};
[NoInterfaceObject, Exposed=Window,Ck_Any_Prm_nativeMessaging_]
interface BrowserExtRuntimeNativeMessagingAPI {
    readonly attribute BrowserExtRuntimeNativeMessaging runtime; 
};
Browser implements BrowserExtRuntimeNativeMessagingAPI;

Local Client Native Process Registration

The local client native process must register itself in such a way that the browser will be able to:

Each browser implementation may have different mechanisms for registration, message filtering and lifetime management of the local client native process.