Add experimental.alarms API to allow lazy background pages to

chrome/common/extensions/api/experimental.alarms.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": "experimental.alarms",
+    "types": [
+      {
+        "id": "Alarm",
+        "type": "object",
+        "properties": {
+          "name": {"type": "string",
+            "description": "Name of this alarm."},
+          "delayInSeconds": {"type": "integer", "minimum": "0",
+            "description": "Original length of time in seconds after which the onAlarm event should fire."},
+          "repeating": {"type": "boolean",
+            "description": "True if the alarm repeatedly fires at regular intervals, false if it only fires once."}
+        }
+      }
+    ],
+    "functions": [
+      {
+        "name": "create",
+        "type": "function",
+        "description": "Sets an alarm. After the delay is expired, the onAlarm event is fired. If there is another alarm with the same name (or no name if none is specified), it will be overridden by this alarm.",

[Aaron Boodman, 2012/03/28 03:36:18]

Creates an alarm. Will the old alarm be canceled in the case of overwrite? Or
will it still fire?

[Matt Perry, 2012/03/28 20:21:36]

Done (it will be cancelled).

+        "parameters": [
+          {
+            "type": "string",
+            "name": "name",
+            "optional": true,
+            "description": "Optional name to identify this alarm. Defaults to \"default\"."

[Aaron Boodman, 2012/03/28 03:36:18]

How about just defaulting to empty string?

[Matt Perry, 2012/03/28 20:21:36]

Done.

+          },
+          {
+            "type": "object",
+            "name": "alarmInfo",
+            "properties": {
+              "delayInSeconds": {"type": "integer", "minimum": "0",
+                "description": "Length of time in seconds after which the onAlarm event should fire. Note that granularity is not guaranteed: up to a minute may pass before the alarm is finally triggered."},

[Aaron Boodman, 2012/03/28 03:36:18]

You could say: Accuracy is only guaranteed to within one minute (but then why
not just have units be minutes? -- your previous explanation didn't totally make
sense to me).

[Matt Perry, 2012/03/28 20:21:36]

I'm trying to give us some leeway as to how accurate alarms are, and not tie it
directly to the units. If we want to allow alarms every 30 seconds, for example,
we need to use seconds as the units. And if we want to reduce granularity to
every 5 minutes, using minutes as units doesn't convey that either. I'll update
the description and try to convey this better.

+              "repeating": {"type": "boolean", "optional": true,
+                "description": "True if the alarm should repeatedly fire at regular intervals. Defaults to false."}
+            }
+          }
+        ]
+      },
+      {
+        "name": "get",
+        "type": "function",
+        "description": "Retrieves details about the specified alarm.",
+        "parameters": [
+          {
+            "type": "string",
+            "name": "name",
+            "optional": true,
+            "description": "The name of the alarm to get. Defaults to \"default\"."
+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "parameters": [
+              { "name": "alarm", "$ref": "Alarm" }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "getAll",
+        "type": "function",
+        "description": "Gets an array of all the alarms.",
+        "parameters": [
+          {
+            "type": "function",
+            "name": "callback",
+            "parameters": [
+              { "name": "alarms", "type": "array", "items": { "$ref": "Alarm" } }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "clear",
+        "type": "function",
+        "description": "Clears the alarm with the given name.",
+        "parameters": [
+          {
+            "type": "string",
+            "name": "name",
+            "optional": true,
+            "description": "The name of the alarm to clear. Defaults to \"default\"."
+          }
+        ]
+      },
+      {
+        "name": "clearAll",
+        "type": "function",
+        "description": "Clears all alarms.",
+        "parameters": []
+      }
+    ],
+    "events": [
+      {
+        "name": "onAlarm",
+        "type": "function",
+        "description": "Fired when an alarm has expired. Useful for transient background pages.",
+        "parameters": [
+          {
+            "type": "string",
+            "name": "name",
+            "optional": true,
+            "description": "The name of the alarm that has expired."
+          }
+        ]
+      }
+    ]
+  }
+]