Improve native messaging documentation

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

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..bf30e0e0006f314a6023456658751bde769945bc 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>
 
-<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
+following fields:
+<table class="simple" id="native-messaging-host-manifest">
   <tr>
     <th>Name</th>
     <th>Description</th>
@@ -313,7 +314,11 @@ example of the manifest file:
   <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>
@@ -334,43 +339,71 @@ 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 <em>not</em>
+    allowed.</td>
   </tr>
 </table>
 
-<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 id="native-messaging-host-location-windows">
+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.
+For example, using the following command:<br>
+<pre>
+REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\<em>com.my_company.my_application</em>" /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\<em>com.my_company.my_application</em>]
+@="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.
+
+<p id="native-messaging-host-location-nix">
+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>.
+
+<dl>
+<dt>OS X (system-wide)
+<dd>Google Chrome: <code>/Library/Google/Chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>
+<dd>Chromium: <code>/Library/Application Support/Chromium/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>
+<dt>OS X (user-specific, <em>default</em> path)
+<dd>Google Chrome: <code>~/Library/Application Support/Google/Chrome/Default/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>
+<dd>Chromium: <code>~/Library/Application Support/Chromium/Default/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>
+</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\<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>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>
-
-  <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>
+<dt>Linux (system-wide)
+<dd>Google Chrome: <code>/etc/opt/chrome/native-messaging-hosts/<em>com.my_company.my_application</em>.json</code>
+<dd>Chromium: <code>/etc/chromium/native-messaging-hosts/<em>com.my_company.my_application</em>.json</code>
+<dt>Linux (user-specific, <em>default</em> path)
+<dd>Google Chrome: <code>~/.config/google-chrome/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>
+<dd>Chromium: <code>~/.config/chromium/NativeMessagingHosts/<em>com.my_company.my_application</em>.json</code>
 </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. The maximum
+size of the message sent to the native messaging host is 4 GB.
 
 <p>
 When a messaging port is created using $(ref:runtime.connectNative) Chrome
@@ -416,6 +449,86 @@ chrome.runtime.sendNativeMessage('com.my_company.my_application',
   });
 </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.
+  <dd>Check whether you have sufficient permissions to execute the file.
+
+  <dt>Invalid native messaging host name specified.
+  <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.
+
+  <dt>Native host has exited.
+  <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.
+
+  <dt>Specified native messaging host not found.
+  <dd>
+  <ul>
+    <li>
+      Is the name spelled correctly in the extension and in the manifest file?
+    <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>
+      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>
+      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.
+  </ul>
+
+  <dt>Native messaging host <em>host name</em> is not registered. (Windows-only)
+  <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>.
+
+  <dt>Access to the specified native messaging host is forbidden.
+  <dd>Is the extension's origin listed in <code>allowed_origins</code>?
+
+  <dt>Error when communicating with the native messaging host.
+  <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>
+      Make sure that the 32-bit message length is in the platform's native
+      integer format (little-endian / big-endian).
+    <li>
+      The message length must not exceed 1024*1024.
+    <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>
+      <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 corrupts the message format as line breaks (<code>\n</code> =
+      <code>0A</code>) are replaced with Windows-style line endings
+      (<code>\r\n</code> = <code>0D 0A</code>). The I/O mode can be set using
+      <a href="http://msdn.microsoft.com/en-us/library/tw4k6df8.aspx"><code>__setmode</code></a>.
+  </ul>
+</dl>
+
 <h2 id="security-considerations">Security considerations</h2>
 
 <p>
@@ -459,7 +572,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,