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.

If you wish to make comments regarding this document, please file issues on github. A public mailing list (subscribe, archives) is also available, but is reserved for high level discussions, and is 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.

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.