app_mode: Add runtime.onRestartRequired event.

chrome/common/extensions/api/runtime.json

 // Copyright (c) 2012 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.
 
 [
   {
     "namespace": "runtime",
     "documentation_permissions_required": ["runtime"],
     "types": [
       {
@@ skipping 334 matching lines @@
                 "type": "string",
                 "description": "The version number of the available update."
               }
             },
             "additionalProperties": { "type": "any" },
             "description": "The manifest details of the available update."
           }
         ]
       },
       {
+        // TODO(xiyuan): onBrowserUpdateAvailable is deprecated in favor of
+        // onRestartRequired. We should remove it when we are sure it is unused.
         "name": "onBrowserUpdateAvailable",
         "type": "function",
         "description": "Fired when a Chrome update is available, but isn't installed immediately because a browser restart is required.",
+        "nodoc": true,
         "parameters": []
       },
       {
         "name": "onConnect",
         "type": "function",
         "nocompile": true,
         "anonymous": true,
         "description": "Fired when a connection is made from either an extension process or a content script.",
         "parameters": [
           {"$ref": "Port", "name": "port"}
@@ skipping 33 matching lines @@
         "parameters": [
           {"name": "message", "type": "any", "description": "The message sent by the calling script."},
           {"name": "sender", "$ref": "MessageSender" },
           {"name": "sendResponse", "type": "function", "description": "Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until <code>sendResponse</code> is called)." }
         ],
         "returns": {
           "type": "boolean",
           "optional": "true",
           "description": "Return true from the event listener if you wish to call <code>sendResponse</code> after the event listener returns."
         }
+      },
+      {
+        "name": "onRestartRequired",
+        "type": "function",
+        "description": "Fired when an app or the device that it runs on needs to be restarted. The app should close all its windows at its earliest convenient time to let the restart to happen. If the app does nothing, a restart will be enforced after a 24-hour grace period has passed. Currently, this event is only fired for Chrome OS kiosk apps.",
+        "parameters": [
+          {
+            "type": "string",
+            "name": "reason",
+            "description": "The reason that the event is being dispatched.",

[Matt Perry, 2013/06/21 22:43:32]

I think it's worth documenting what each enum means - especially "periodic",
which I don't understand.

[xiyuan, 2013/06/21 22:57:17]

Done.

+            "enum": ["app_update", "os_update", "periodic"]
+          }
+        ]
       }
-
-
-
     ]
   }
 ]