chrome/common/extensions/docs/templates/articles/messaging.html - Issue 768373004: Improve native messaging documentation

Unified Diff: chrome/common/extensions/docs/templates/articles/messaging.html

Issue 768373004: Improve native messaging documentation (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master

Patch Set: Add extra installation instructions for Windows Created 6 years ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Download patch

Index: chrome/common/extensions/docs/templates/articles/messaging.html

diff --git a/chrome/common/extensions/docs/templates/articles/messaging.html b/chrome/common/extensions/docs/templates/articles/messaging.html

index a6066e80e9542f44b05b0263083f989e83e775c5..c4f79fc9f34500f3cc69413c5762dee01eac9400 100644

--- a/chrome/common/extensions/docs/templates/articles/messaging.html

+++ b/chrome/common/extensions/docs/templates/articles/messaging.html

@@ -304,8 +304,9 @@ example of the manifest file:

}

</pre>

-Native messaging host manifest file contains the following fields:

-<table class="simple">

+The native messaging host manifest file must be valid JSON and contains the

+following fields:

+<table class="simple" id="native-messaging-host-manifest">

<tr>

<th>Description</th>

@@ -313,7 +314,11 @@ example of the manifest file:

<tr>

<td>Name of the native messaging host. Clients pass this string to

- $(ref:runtime.connectNative) or $(ref:runtime.sendNativeMessage).</td>

+ $(ref:runtime.connectNative) or $(ref:runtime.sendNativeMessage).

+ This name can only contain lowercase alphanumeric characters, underscores

+ and dots. The name cannot start or end with a dot, and a dot cannot be

+ followed by another dot.

+ </td>

</tr>

<tr>

<td><code>description</code></td>

@@ -334,43 +339,79 @@ example of the manifest file:

</tr>

<tr>

<td><code>allowed_origins</code></td>

- <td>List of extensions that should have access to the native messaging host.</td>

+ <td>List of extensions that should have access to the native messaging host.

+ Wildcards such as <code>chrome-extension://*/*</code> are not

+ allowed.</td>

</tr>

</table>

+

+<h4 id="native-messaging-host-location">Native messaging host location</h4>

+The location of the manifest file depends on the platform.

+

+On Windows, the manifest file can be located anywhere in the file system.

+The application installer must create registry key

+<code>HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application</code>

+or

+<code>HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application</code>,

+and set default value of that key to the full path to the manifest file.

+For example, using the following command:

+<pre>

+REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f

+</pre>

+or using the following <code>.reg</code> file:

+<pre>

+Windows Registry Editor Version 5.00

+[HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application]

+@="C:\\path\\to\\nmh-manifest.json"

+</pre>

+When Chrome looks for native messaging hosts, first the 32-bit registry is

+queried, then the 64-bit registry.

+

-Location of the manifest file depends on the platform:

+

+On OS X and Linux, the location of the native messaging host's

+manifest file varies by the browser (Google Chrome or Chromium).

+The system-wide native messaging hosts are looked up at a fixed location,

+while the user-level native messaging hosts are looked up in a subdirectory within the

+<a href="https://www.chromium.org/user-experience/user-data-directory">user profile directory</a>

+called <code>NativeMessagingHosts</code>.

+

Sergey Ulanov 2014/12/10 18:42:47 nit: don't need here and below. http://stacko

robwu 2014/12/10 23:09:41 Done.

+

+<dl>

+<dt>OS X (system-wide)</dt>

+<dd>Google Chrome: <code>/Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json</code></dd>

+<dd>Chromium: <code>/Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json</code></dd>

+<dt>OS X (user-specific, default path)</dt>

+<dd>Google Chrome: <code>~/Library/Application Support/Google/Chrome/Default/NativeMessagingHosts/com.my_company.my_application.json</code></dd>

+<dd>Chromium: <code>~/Library/Application Support/Chromium/Default/NativeMessagingHosts/com.my_company.my_application.json</code></dd>

+</dl>

+

+

<dl>

- <dt>Windows:</dt>

- <dd>The manifest file can be located anywhere in the file system.

- The application installer must create registry key

- <code>HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application</code>

- or

- <code>HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application</code>,

- and set default value of that key to the full path to the manifest file.

- </dd>

- <dt>OSX:</dt>

- <dd>The manifest file must be placed at

- <code>/Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json</code>,

- or, for applications installed on user level,

- <code>~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json</code>.

- </dd>

- <dt>Linux:</dt>

- <dd>The manifest file must be placed at

- <code>/etc/opt/chrome/native-messaging-hosts/com.my_company.my_application.json</code>,

- or, for applications installed on user level,

- <code>~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json</code>.

- </dd>

+<dt>Linux (system-wide)</dt>

+<dd>Google Chrome: <code>/etc/opt/chrome/native-messaging-hosts/com.my_company.my_application.json</code></dd>

+<dd>Chromium: <code>/etc/chromium/native-messaging-hosts/com.my_company.my_application.json</code></dd>

+<dt>Linux (user-specific, default path)</dt>

+<dd>Google Chrome: <code>~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json</code></dd>

+<dd>Chromium: <code>~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json</code></dd>

</dl>

+

+<h4 id="native-messaging-host-protocol">Native messaging protocol</h4>

Chrome starts each native messaging host in a separate process and communicates

with it using standard input (<code>stdin</code>) and standard output

(<code>stdout</code>). The same format is used to send messages in both

directions: each message is serialized using JSON, UTF-8 encoded

and is preceded with 32-bit message length in native byte order.

+The maximum size of a single message from the native messaging host is 1 MB,

+mainly to protect Chrome from misbehaving native applications. The maximum

+size of the message sent to the native messaging host is 4 GB.

+

When a messaging port is created using $(ref:runtime.connectNative) Chrome

@@ -381,7 +422,7 @@ a new native messaging host process for each message. In that case the first

message generated by the host process is handled as a response to the original

request, i.e. Chrome will pass it to the response callback specified when

$(ref:runtime.sendNativeMessage) is called. All other messages generated by the

-native messaging host in that case are ignored.

+native messaging host in that case are ignored.

<h3 id="native-messaging-client">Connecting to a native application</h3>

@@ -416,6 +457,99 @@ chrome.runtime.sendNativeMessage('com.my_company.my_application',

});

</pre>

+<h3 id="native-messaging-debugging">Debugging native messaging</h3>

+

+When the native messaging host fails to start, writes to <code>stderr</code> or

+when it violates the communication protocol, output is written to the error log

+of Chrome.

+On Linux and OS X, this log can easily be accessed by starting Chrome from the

+command line and watching its output in the terminal.

+On Windows, use <code>--enable-logging</code> as explained at

+<a href="https://www.chromium.org/for-testers/enable-logging">How to enable logging</a>.

+

+Here are some errors and tips for solving the issues:

+<dl>

+ <dt>Failed to start native messaging host.</dt>

Sergey Ulanov 2014/12/10 18:42:47 nit: don't need to close <dt>, same for <dd>

robwu 2014/12/10 23:09:41 Done.

+ <dd>Check whether you have sufficient permissions to execute the file.</dd>

+ <dt>Invalid native messaging host name specified.</dt>

+ <dd>Check whether the name contains any invalid characters.

+ Only lowercase alphanumeric characters, underscores and dots are allowed.

+ A name cannot start or end with a dot, and a dot cannot be followed by

+ another dot.</dd>

+ <dt>Native host has exited.</dt>

+ <dd>The pipe to the native messaging host was broken before the message was

+ read by Chrome. This is most likely initiated from your native messaging host.

+ </dd>

+ <dt>Specified native messaging host not found.</dt>

+ <dd>

+ <ul>

+ <li>Is the name spelled correctly in the extension and in the manifest file?</li>

Sergey Ulanov 2014/12/10 18:42:47 nit: don't need to close <li> in html

robwu 2014/12/10 23:09:41 Done.

+ <li>

+ Is the manifest put in the right directory and with the correct name? See

+ <a href="#native-messaging-host-location">native messaging host location</a>

+ for the expected formats.

+ </li>

+ <li>

+ Is the manifest file in the correct format? In particular, is the JSON

+ syntax correct and do the values match the definition of a

+ <a href="native-messaging-host-manifest">native messaging host manifest</a>?

+ </li>

+ <li>Does the file specified in <code>path</code> exist? On Windows, paths

+ may be relative, but on OS X and Linux, the paths must be absolute.</li>

+ </ul>

+ </dd>

+ <dt>Native messaging host host name is not registered. (Windows-only)</dt>

+ <dd>The native messaging host was not found in the Windows registry. Double-check

+ using <code>regedit</code> whether the key was really created and matches the

+ required format as documented at

+ <a href="#native-messaging-host-location">native messaging host location</a>.

+ </dd>

+ <dt>Access to the specified native messaging host is forbidden.</dt>

+ <dd>Is the extension's origin listed in <code>allowed_origins</code>?</dd>

+ <dt>Error when communicating with the native messaging host.</dt>

+ <dd>This is a very common error and indicates an incorrect implementation of

+ the communication protocol in the native messaging host.

+ <ul>

+ <li>

+ Make sure that all output in <code>stdout</code> adheres to the native

+ messaging protocol. If you want to print some data for debugging purposes,

+ write to <code>stderr</code>.

+ </li>

+ <li>

+ Make sure that the 32-bit message length is in the platform's native

+ integer format (little-endian / big-endian).

+ </li>

+ <li>

+ The message length must not exceed 1024*1024.

+ </li>

+ <li>

+ The message size must be equal to the number of bytes in the message.

+ This may differ from the "length" of a string, because characters may be

+ represented by multiple bytes.

+ </li>

+ <li>

+ Windows-only: Make sure that the program's I/O mode is set to

+ <code>O_BINARY</code>. By default, the I/O mode is <code>O_TEXT</code>,

Sergey Ulanov 2014/12/10 18:42:47 Please add link to MSDN for how the mode can be ch

robwu 2014/12/10 23:09:41 Done.

+ which replaces line breaks (<code>\n</code> = <code>0A</code>) with

+ Windows-style line endings (<code>\r\n</code> = <code>0D 0A</code>).

+ This modification is problematic. For example, if your message length is

+ 10, then the 32-bit integer is <code>00 00 00 0A</code>.

+ When <code>0D</code> is inserted before <code>0A</code>, the message

+ header becomes <code>00 00 00 0D 0A</code>. Only the first four bytes

+ represent a 32-bit integer, so the length is <code>0D</code> = 13.

+ This length is different from the original message length and incorrect!

+ </li>

+ </ul>

+ </dd>

+</dl>

<h2 id="security-considerations">Security considerations</h2>

@@ -459,7 +593,7 @@ chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {

You can find simple examples of communication via messages in the

<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/messaging/">examples/api/messaging</a>

directory.

-<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/nativeMessaging/">examples/api/nativeMessaging</a>

+<a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/docs/examples/api/nativeMessaging">examples/api/nativeMessaging</a>

contains an example application that uses native messaging.

Also see the

<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/howto/contentscript_xhr">contentscript_xhr</a> example,

« no previous file with comments | « chrome/common/extensions/docs/examples/api/nativeMessaging/host/uninstall_host.bat ('k') | no next file » | no next file with comments »