Implement an initial extension settings API.

chrome/common/extensions/api/extension_api.json

 [
   {
     "namespace": "extension",
     "unprivileged": true,
     "types": [
       {
         "id": "MessageSender",
         "type": "object",
         "description": "An object containing information about the script context that sent a message or request.",
         "properties": {
@@ skipping 681 matching lines @@
         ]
       },
       {
         "name": "onStop",
         "type": "function",
         "description": "Fired when a call is made to tts.stop and this extension may be in the middle of speaking. If an extension receives a call to onStop and speech is already stopped, it should do nothing (not raise an error)."
       }
     ]
   },
   {
+    "namespace": "experimental.settings",
+    "types": [],
+    "functions": [
+      {
+        "name": "get",
+        "type": "function",
+        "description": "Gets one or more values from settings.",
+        "parameters": [
+          {
+            "name": "keys",
+            "choices": [
+              {"type": "string"},
+              {"type": "array", "items": {"type": "string"}, "minItems": 1}
+            ],
+            "description": "A single key or a list of keys to get from settings. Leave empty to get the entire contents of settings; this should only be used for debugging.",
+            "optional": true
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Callback with settings values, or on failure (in which case lastError will be set).",
+            "parameters": [
+              {
+                "name": "settings",
+                "type": "object",
+                "properties": {},
+                "additionalProperties": { "type": "any" },
+                "description": "Object with given keys set to settings values."
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "set",
+        "type": "function",
+        "description": "Sets multiple settings values.",
+        "parameters": [
+          {
+            "name": "settings",
+            "type": "object",
+            "properties": {},
+            "additionalProperties": { "type": "any" },
+            "description": "Object to augment settings with. Values that cannot be serialized (functions, etc) will be ignored."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Callback with settings values, or on failure (in which case lastError will be set).",
+            "parameters": [
+              {
+                "name": "settings",
+                "type": "object",
+                "properties": {},
+                "additionalProperties": { "type": "any" },
+                "description": "Object with given keys set to settings values."
+              }
+            ],
+            "optional": true
+          }
+        ]
+      },
+      {
+        "name": "remove",
+        "type": "function",
+        "description": "Removes one or more values from settings.",
+        "parameters": [
+          {
+            "name": "keys",
+            "choices": [
+              {"type": "string"},
+              {"type": "array", "items": {"type": "string"}, "minItems": 1}
+            ],
+            "description": "A single key or a list of keys to remove from settings."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Callback with an empty settings object, or on failure (in which case lastError will be set).",

[Matt Perry, 2011/06/29 18:08:11]

I didn't notice this before, but why are we passing an empty object? We can pass
no arguments, and just have lastError set on an error.

[not at google - send to devlin, 2011/08/03 06:36:51]

Initially so that, C++ implementation wise, all methods can use the same
callback types; just a DictionaryValue.

From an API standpoint this arguably doesn't make much sense, but I can see it
being useful even for a developer to have all these functions have the same
type, if function pointers are passed around... or something.

[Matt Perry, 2011/08/03 22:57:47]

If you pass NULL to that callback (which then sets the
ExtensionFunction::result_ to NULL), it will pass no arguments to the callback.

[not at google - send to devlin, 2011/08/04 00:59:06]

Done.

+            "parameters": [
+              {
+                "name": "settings",
+                "type": "object",
+                "properties": {},
+                "additionalProperties": { "type": "any" },
+                "description": "An empty object."
+              }
+            ],
+            "optional": true
+          }
+        ]
+      },
+      {
+        "name": "clear",
+        "type": "function",
+        "description": "Removes all values from settings.",
+        "parameters": [
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Callback with an empty settings object, or on failure (in which case lastError will be set).",

[Matt Perry, 2011/06/29 18:08:11]

ditto

[not at google - send to devlin, 2011/08/04 00:59:06]

Done.

+            "parameters": [
+              {
+                "name": "settings",
+                "type": "object",
+                "properties": {},
+                "additionalProperties": { "type": "any" },
+                "description": "An empty object."
+              }
+            ],
+            "optional": true
+          }
+        ]
+      }
+    ],
+    "events": []
+  },
+  {
     "namespace": "windows",
     "types": [
       {
         "id": "Window",
         "type": "object",
         "properties": {
           "id": {"type": "integer", "minimum": 0, "description": "The ID of the window. Window IDs are unique within a browser session."},
           "focused": {"type": "boolean", "description": "Whether the window is currently the focused window."},
           "top": {"type": "integer", "description": "The offset of the window from the top edge of the screen in pixels."},
           "left": {"type": "integer", "description": "The offset of the window from the left edge of the screen in pixels."},
@@ skipping 5455 matching lines @@
           {
             "type": "integer",
             "name": "tabId",
             "description": "The id of the tab that was detached."
           }
         ]
       }
     ]
   }
 ]