Improve native messaging documentation

- Specify format of NMH manifest.
- Specify the expected locations of the NMH on all platforms.
- Fully document the communication protocol and constraints.
- Document every error and offer tips for resolving the issues.
- Document other common problems and how-to-solve.

BUG=377582
R=sergeyu@chromium.org,kalman@chromium.org
NOTRY=true

Review URL: https://codereview.chromium.org/768373004

Cr-Commit-Position: refs/heads/master@{#308420}

chrome/common/extensions/docs/examples/api/nativeMessaging/README.txt

@@ -7,13 +7,15 @@ host from the host directory.
 To install the host:
 
 On Windows:
-  Add registry key
-  HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.google.chrome.example.echo
-  or
+  Run install_host.bat script in the host directory.
+  This script installs the native messaging host for the current user, by
+  creating a registry key
   HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.google.chrome.example.echo
-  and set its default value to the full path to
-  host\com.google.chrome.example.echo-win.json . Note that you need to have
-  python installed.
+  and setting its default value to the full path to
+  host\com.google.chrome.example.echo-win.json .
+  If you want to install the native messaging host for all users, change HKCU to
+  HKLM.
+  Note that you need to have python installed.
 
 On Mac and Linux:
   Run install_host.sh script in the host directory:

chrome/common/extensions/docs/examples/api/nativeMessaging/host/install_host.bat

+:: Copyright 2014 The Chromium Authors. All rights reserved.
+:: Use of this source code is governed by a BSD-style license that can be
+:: found in the LICENSE file.
+
+:: Change HKCU to HKLM if you want to install globally.
+:: %~dp0 is the directory containing this bat script and ends with a backslash.
+REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.google.chrome.example.echo" /ve /t REG_SZ /d "%~dp0com.google.chrome.example.echo-win.json" /f

chrome/common/extensions/docs/examples/api/nativeMessaging/host/native-messaging-example-host

@@ -17,6 +17,13 @@ try:
 except ImportError:
   Tkinter = None
 
+# On Windows, the default I/O mode is O_TEXT. Set this to O_BINARY
+# to avoid unwanted modifications of the input/output streams.
+if sys.platform == "win32":
+  import os, msvcrt
+  msvcrt.setmode(sys.stdin.fileno(), os.O_BINARY)
+  msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)
+
 # Helper function that sends a message to the webapp.
 def send_message(message):
    # Write message size.

chrome/common/extensions/docs/examples/api/nativeMessaging/host/uninstall_host.bat

+:: Copyright 2014 The Chromium Authors. All rights reserved.
+:: Use of this source code is governed by a BSD-style license that can be
+:: found in the LICENSE file.
+
+:: Deletes the entry created by install_host.bat
+REG DELETE "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.google.chrome.example.echo" /f
+REG DELETE "HKLM\Software\Google\Chrome\NativeMessagingHosts\com.google.chrome.example.echo" /f

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

@@ -279,142 +279,17 @@ chrome.runtime.onMessageExternal.addListener(
 </pre>
 
 
+<!-- Anchors to make sure that pages that link to a previous version of the
+     documentation do not break. -->
+<a id="native-messaging-host"></a>
+<a id="native-messaging-client"></a>
 <h2 id="native-messaging">Native messaging</h2>
 <p>
-Extensions can exchange messages with native applications. Native
-applications that support this feature must register a <em>native messaging
-host</em> that knows how to communicate with the extension. Chrome starts the
-host in a separate process and communicates with it using standard input and
-standard output streams.
+Extensions and apps <a href="nativeMessaging#native-messaging-client">can
+exchange messages</a> with native applications that are registered as a
+<a href="nativeMessaging#native-messaging-host">native messaging host</a>.
+To learn more about this feature, see <a href="nativeMessaging">Native messaging</a>.
 
-<h3 id="native-messaging-host">Native messaging host</h3>
-<p>
-In order to register a native messaging host the application must install a
-manifest file that defines the native messaging host configuration. Below is an
-example of the manifest file:
-<pre data-filename="manifest.json">
-{
-  "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">
-  <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>
-  </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>
-  </tr>
-</table>
-
-<p>Location of the manifest file depends on the platform:
-
-<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>
-</dl>
-
-<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.
-
-<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.
-
-<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
-messaging host <code>com.my_company.my_application</code>, starts listening for
-messages from that port and sends one outgoing message:
-<pre>
-var port = chrome.runtime.connectNative('com.my_company.my_application');
-port.onMessage.addListener(function(msg) {
-  console.log("Received" + msg);
-});
-port.onDisconnect.addListener(function() {
-  console.log("Disconnected");
-});
-port.postMessage({ text: "Hello, my_application" });
-</pre>
-
-<p>
-$(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>
 
 <h2 id="security-considerations">Security considerations</h2>
 
@@ -459,8 +334,8 @@ 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>
-contains an example application that uses native messaging.
+The <a href="nativeMessaging#examples">native messaging sample</a> demonstrates
+how a Chrome app can communicate with a native app.
 For more examples and for help in viewing the source code, see
 <a href="samples">Samples</a>.
 </p>

chrome/common/extensions/docs/templates/public/apps/nativeMessaging.html

+{{+partials.standard_apps_article article:articles.nativeMessaging/}}

chrome/common/extensions/docs/templates/public/extensions/nativeMessaging.html

+{{+partials.standard_extensions_article article:articles.nativeMessaging/}}