Skip to main content

A package with basic native messaging apis for webextensions

Project description

# nativemessaging
A Python package for interfacing with Native Messaging in WebExtensions

[See Native Messaging on MDN](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging)

Based on [Native Messaging on MDN](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging#App_side) and [native-messaging on mdn/webextension-examples](https://github.com/mdn/webextensions-examples/tree/master/native-messaging) (MPL 2.0 License)

`pip3 install nativemessaging`

## `get_message()`
`nativemessaging.get_message()` will poll for a message from the browser.
If [`runtime.connectNative`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/connectNative) is used, `get_message()` must be called repeatedly in a loop to poll for messages.
If [`runtime.sendNativeMessage`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendNativeMessage) is used, `get_message()` only needs to be called once.

## `encode_message( message_content )`
`nativemessaging.encode_message()` takes one argument, a message to be encoded.
Returns an encoded version of a message to be returned to the browser. Use with `send_message()`.

## `send_message( encoded_message )`
`nativemessaging.send_message()` takes one argument, an encoded message from `encode_message()`. Returns a message to the browser.

## Sample
Browser side:
```javascript
function onReceived(response) {
console.log(response);
}

// runtime.connectNative
var port = browser.runtime.connectNative("application_name");
port.onMessage.addListener(onReceived);
port.postMessage("hello");

// runtime.sendNativeMessage
browser.runtime.sendNativeMessage("application_name", "hello").then(onReceived);
```

App side:
```python
import nativemessaging

while True:
message = nativemessaging.get_message()
if message == "hello":
nativemessaging.send_message(nativemessaging.encode_message("world"))
```

## nativemessaging-install
`nativemessaging-install` is a command line script provided with the package.

### Arguments
`nativemessaging-install browser [--manifest manifest]`
* `browser` - positional argument, 1 or more parameters. Must be `chrome` or `firefox`.
* `--manifest` - a path to a manifest file to use for installing.

### manifest-install.json
A `native-manifest.json` file is expected in the current working directory when running the script, unless `--manifest` is passsed.
The format must be similar to the native manifest format for Chrome or Firefox, with two main differences:
* `path` must be a relative path to the native app in relation to your current working directory.
* Both `allowed_extensions` and `allowed_origins` must be in the manifest to work with both Chrome and Firefox.
```json
{
"name": "application_name",
"description": "description",
"path": "application_name.py",
"type": "stdio",
"allowed_extensions": ["extension@id"],
"allowed_origins": ["chrome-extension://extension-id"]
}
```

### Created files
On Windows, it will create `<application_name>_firefox.json` and `<application_name>_chrome.json` in the same directory as `<path>`.
A batch file will also be created for python apps on Windows.
A registry key is created at `HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\<application_name>` or `HKEY_CURRENT_USER\Software\Mozilla\NativeMessagingHosts\<application_name>`

On linux, it will create `~/.config/google-chrome/NativeMessagingHosts/<application_name>.json` or `~/.mozilla/native-messaging-hosts/<application_name>.json`

On mac, it will create `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/<application_name>.json` or `~/Library/Application Support/Mozilla/NativeMessagingHosts/<application_name>.json`

#### See also:
* [Native Messaging on Chrome Docs](https://developer.chrome.com/extensions/nativeMessaging)


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for nativemessaging, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size nativemessaging-1.0.1-py3-none-any.whl (7.0 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size nativemessaging-1.0.1.tar.gz (4.1 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page