Improve native messaging documentation

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

 <h1>Message Passing</h1>
 
 
 <p>
 Since content scripts run in the context of a web page and not the extension,
 they often need some way of communicating with the rest of the extension. For
 example, an RSS reader extension might use content scripts to detect the
 presence of an RSS feed on a page, then notify the background page in order to
 display a page action icon for that page.
 
@@ skipping 286 matching lines @@
   "name": "com.my_company.my_application",
   "description": "My Application",
   "path": "C:\\Program Files\\My Application\\chrome_native_messaging_host.exe",
   "type": "stdio",
   "allowed_origins": [
     "chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"
   ]
 }
 </pre>
 
-<p>Native messaging host manifest file contains the following fields:
-<table class="simple">
+<p>The native messaging host manifest file must be valid JSON and contains the

[Alexander Kashev, 2014/12/03 09:28:31]

I think the grammar here should be "must be ... and contain"

[robwu, 2014/12/09 15:11:35]

The sentence is correct. Read the sentence as follows:

"The NMH manifest file (must be valid JSON) and (contains the following
fields)."

+following fields:
+<table class="simple" id="native-messaging-host-manifest">
   <tr>
     <th>Name</th>
     <th>Description</th>
   </tr>
   <tr>
     <td><code>name</code></td>
     <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>
     <td>Short application description.</td>
   </tr>
   <tr>
     <td><code>path</code></td>
     <td>Path to the native messaging host binary. On Linux and OSX the path must
     be absolute. On Windows it can be relative to the directory in which the
     manifest file is located.</td>
   </tr>
   <tr>
     <td><code>type</code></td>
     <td>Type of the interface used to communicate with the native messaging
     host. Currently there is only one possible value for this parameter:
     <code>stdio</code>. It indicates that Chrome should use <code>stdin</code>
     and <code>stdout</code> to communicate with the host.</td>
   </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 <em>not</em>
+    allowed.</td>
   </tr>
 </table>
+</p>
 
-<p>Location of the manifest file depends on the platform:
+<h4 id="native-messaging-host-location">Native messaging host location</h4>
+<p>The location of the manifest file depends on the platform.</p>
 
+<p>
+On <b>Windows</b>, 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\<em>com.my_company.my_application</em></code>
+or
+<code>HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\<em>com.my_company.my_application</em></code>,
+and set default value of that key to the full path to the manifest file.<br>

[Alexander Kashev, 2014/12/03 09:28:31]

Since you're updating the documentation: it would be great to specify how
backslashes in the path in the registry should be formatted. This has been a
source of confusion before (e.g.
http://stackoverflow.com/questions/21961775/chrome-native-messaging-on-windows);
it would be nice if there was a sample in the REG-file format.

[robwu, 2014/12/09 15:11:35]

The usual Windows path syntax applies. Paths are separated by a backslash, but
in contexts where a backslash is an escape character, two backslashes have to be
used. I have added three examples (2 inline in the documentation, one in a
separate file).

+When Chrome looks for native messaging hosts, first the 32-bit registry is
+queried, then the 64-bit registry.
+</p>
+
+<p>On <b>OS X</b> and <b>Linux</b>, 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>.
+</p>
+
+<p>
 <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\<em>com.my_company.my_application</em></code>
-     or
-     <code>HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\<em>com.my_company.my_application</em></code>,
-     and set default value of that key to the full path to the manifest file.
-    </dd>
+<dt>OS X (system-wide)</dt>
+<dd>Google Chrome: <code>/Library/Google/Chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code></dd>
+<dd>Chromium: <code>/Library/Application Support/Chromium/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code></dd>
+<dt>OS X (user-specific, <em>default</em> path)</dt>
+<dd>Google Chrome: <code>~/Library/Application Support/Google/Chrome/Default/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code></dd>
+<dd>Chromium: <code>~/Library/Application Support/Chromium/Default/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code></dd>
+</dl>
+</p>
 
-  <dt>OSX:</dt>
-    <dd>The manifest file must be placed at
-    <code>/Library/Google/Chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>,
-    or, for applications installed on user level,
-    <code>~/Library/Application Support/Google/Chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>.
-    </dd>
+<p>
+<dl>
+<dt>Linux (system-wide)</dt>
+<dd>Google Chrome: <code>/etc/opt/chrome/native-messaging-hosts/<em>com.my_company.my_application</em>.json</code></dd>
+<dd>Chromium: <code>/etc/chromium/native-messaging-hosts/<em>com.my_company.my_application</em>.json</code></dd>
+<dt>Linux (user-specific, <em>default</em> path)</dt>
+<dd>Google Chrome: <code>~/.config/google-chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code></dd>
+<dd>Chromium: <code>~/.config/chromium/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code></dd>
+</dl>
+</p>
 
-  <dt>Linux:</dt>
-    <dd>The manifest file must be placed at
-    <code>/etc/opt/chrome/native-messaging-hosts/<em>com.my_company.my_application</em>.json</code>,
-    or, for applications installed on user level,
-    <code>~/.config/google-chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>.
-    </dd>
-</dl>
-
+<h4 id="native-messaging-host-protocol">Native messaging protocol</h4>
 <p>
 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. There is no
+hard limit on the size of the message sent to the native messaging host.

[Alexander Kashev, 2014/12/03 09:28:32]

Technically, not true: message sent to the host is limited by the 32-bit length
field.

[robwu, 2014/12/09 15:11:34]

Done.

+</p>
 
 <p>
 When a messaging port is created using $(ref:runtime.connectNative) Chrome
 starts native messaging host process and keeps it running until the port is
 destroyed. On the other hand, when a message is sent using
 $(ref:runtime.sendNativeMessage), without creating a messaging port, Chrome starts
 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.</p>
 
 <h3 id="native-messaging-client">Connecting to a native application</h3>
 <p>
 Sending and receiving messages to and from a native application is very similar
 to cross-extension messaging. The main difference is that
 $(ref:runtime.connectNative) is used instead of $(ref:runtime.connect),
 and $(ref:runtime.sendNativeMessage) is used instead of $(ref:runtime.sendMessage).
 
 <p>
 The Following example creates a $(ref:runtime.Port) object that's connected to native
@@ skipping 14 matching lines @@
 $(ref:runtime.sendNativeMessage) can be used to send a message to native
 application without creating a port, e.g.:
 <pre>
 chrome.runtime.sendNativeMessage('com.my_company.my_application',
   { text: "Hello" },
   function(response) {
     console.log("Received " + response);
   });
 </pre>
 
+<h3 id="native-messaging-debugging">Debugging native messaging</h3>
+<p>
+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>.
+</p>
+
+Here are some errors and tips for solving the issues:
+<dl>
+  <dt>Failed to start native messaging host.</dt>
+  <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>
+    <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 <em>host name</em> is not registered. (Windows-only)</dt>
+  <dd>The native messaging host was not found in the Windows registry. Look at
+  <a href="#native-messaging-host-location">native messaging host location</a>
+  for more information on the required format of the registry key.
+  </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>
+      <b>Windows-only: Make sure that the program's I/O mode is set to
+      <code>O_BINARY</code></b>. By default, the I/O mode is <code>O_TEXT</code>,
+      which replaces line breaks (<code>\n</code> = <code>0A</code>) with
+      Windows-style line endings (<code>\r\n</code> = <code>0D 0A</code>).<br>
+      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>
 
 <p>
 When receiving a message from a content script or another extension, your
 background page should be careful not to fall victim to <a
 href="http://en.wikipedia.org/wiki/Cross-site_scripting">cross-site
 scripting</a>.  Specifically, avoid using dangerous APIs such as the
 below:
 </p>
 <pre data-filename="background.js">
@@ skipping 33 matching lines @@
 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/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,
 in which a content script and its parent extension exchange messages,
 so that the parent extension can perform
 cross-site requests on behalf of the content script.
 For more examples and for help in viewing the source code, see
 <a href="samples">Samples</a>.
 </p>