Move declarative API into events API

chrome/common/extensions/api/events.json

Index: chrome/common/extensions/api/events.json
diff --git a/chrome/common/extensions/api/declarative.json b/chrome/common/extensions/api/events.json
similarity index 56%
rename from chrome/common/extensions/api/declarative.json
rename to chrome/common/extensions/api/events.json
index bf5ab508e38e462569f305d5e1dfa351662f76c4..9eac5a23077266be19e52c657d7f94ea2a00a03a 100644
--- a/chrome/common/extensions/api/declarative.json
+++ b/chrome/common/extensions/api/events.json
@@ -4,11 +4,117 @@
 
 [
   {
-    "namespace": "declarative",
+    "namespace": "events",

[Aaron Boodman, 2012/05/09 19:29:46]

This was a nice idea, I really like it.

     "internal": true,
-    "documentation_permissions_required": ["declarative"],
+    "unprivileged": true,

[battre, 2012/05/09 16:28:08]

Is this ok? Otherwise my tests fail:

from chrome/test/data/extensions/api_test/webrequest/test_blocking.js

    navigateAndWait(getURLEchoUserAgent(), function() {
      chrome.test.listenOnce(chrome.extension.onRequest, function(request) {
        chrome.test.assertTrue(request.pass, "Request header was not set.");
      });
      chrome.tabs.executeScript(tabId,
        {
          code: "chrome.extension.sendRequest(" +
              "{pass: document.body.innerText.indexOf('FoobarUA') >= 0});"
        });
    });

The code is executed in an unprivileged context. If you look at extension.json,
you see that I have introduced a dependency to events.json. This dependency
cannot be fulfilled, if events.json is not unprivileged.

[Aaron Boodman, 2012/05/09 19:29:46]

Yes, it's OK, so long as methods like addRules are no-ops in all but the places
they're used.

[not at google - send to devlin, 2012/05/10 09:01:25]

We have this problem in a couple of other places where unprivileged APIs require
types defined in privileged APIs.  At least, I think we do.

And I think in all cases it's just the types that we depend on.  Unfortunately
there's no convenient way to do that.

Long story short, this is ok I guess though I think you might be able to put
"unprivileged: false" on all the functions?

Even better though... can we just leave Event on chrome.extension and move it
here when we "fix" features?

[battre, 2012/05/10 16:40:29]

No, I think that does not work because "unprivileged: false" is only supported
one level under the namespace, i.e. for functions and events. These functions
are defined as part of a data type.
No, the entire exercise is to move Event into chrome.events to improve the
documentation.

     "types": [
       {
+        "id": "Event",
+        "type": "object",
+        "description": "An object which allows the addition and removal of listeners for a Chrome event.",
+        "additionalProperties": { "type": "any"},
+        "functions": [
+          // TODO(battre): Add correct signatures.
+          { "name": "addListener", "type": "function", "parameters": [] },
+          { "name": "removeListener", "type": "function", "parameters": [] },
+          { "name": "hasListener", "type": "function", "parameters": [] },
+          { "name": "hasListeners", "type": "function", "parameters": [] },
+          {

[Aaron Boodman, 2012/05/09 19:29:46]

TODO(aa): Limit the rules APIs to privileged context. See crbug.com/120069.

+            "name": "addRules",
+            "type": "function",
+            "description": "Registers rules to handle events. Note that you cannot call this function as <code>chrome.declarative.addRules(...)</code>. Instead a function of this signature is provided for event objects supporting the declarative API such as <code>chrome.declarativeWebRequest.onRequest</code>.",
+            "parameters": [
+              {
+                "nodoc": "true",
+                "name": "eventName",
+                "type": "string",
+                "description": "Name of the event this function affects."
+              },
+              {
+                "name": "rules",
+                "type": "array",
+                "items": {"$ref": "Rule"},
+                "description": "Rules to be registered. These do not replace previously registered rules."
+              },
+              {
+                "name": "callback",
+                "optional": true,
+                "type": "function",
+                "parameters": [
+                  {
+                    "name": "rules",
+                    "type": "array",
+                    "items": {"$ref": "Rule"},
+                    "description": "Rules that were registered, the optional parameters are filled with values."
+                  }
+                ],
+                "description": "Called with registered rules."
+              }
+            ]
+          },
+          {
+            "name": "getRules",
+            "type": "function",
+            "description": "Returns currently registered rules. Note that you cannot call this function as <code>chrome.declarative.getRules(...)</code>. Instead a function of this signature is provided for event objects supporting the declarative API such as <code>chrome.declarativeWebRequest.onRequest</code>.",
+            "parameters": [
+              {
+                "nodoc": "true",
+                "name": "eventName",
+                "type": "string",
+                "description": "Name of the event this function affects."
+              },
+              {
+                "name": "ruleIdentifiers",
+                "optional": "true",
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "If an array is passed, only rules with identifiers contained in this array are returned."
+              },
+              {
+                "name": "callback",
+                "type": "function",
+                "parameters": [
+                  {
+                    "name": "rules",
+                    "type": "array",
+                    "items": {"$ref": "Rule"},
+                    "description": "Rules that were registered, the optional parameters are filled with values."
+                  }
+                ],
+                "description": "Called with registered rules."
+              }
+            ]
+          },
+          {
+            "name": "removeRules",
+            "type": "function",
+            "description": "Unregisters currently registered rules. Note that you cannot call this function as <code>chrome.declarative.removeRules(...)</code>. Instead a function of this signature is provided for event objects supporting the declarative API such as <code>chrome.declarativeWebRequest.onRequest</code>.",
+            "parameters": [
+              {
+                "nodoc": "true",
+                "name": "eventName",
+                "type": "string",
+                "description": "Name of the event this function affects."
+              },
+              {
+                "name": "ruleIdentifiers",
+                "optional": "true",
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "If an array is passed, only rules with identifiers contained in this array are unregistered."
+              },
+              {
+                "name": "callback",
+                "optional": true,
+                "type": "function",
+                "parameters": [],
+                "description": "Called when rules were unregistered."
+              }
+            ]
+          }
+        ]
+      },
+      {
         "id": "Rule",
         "type": "object",
         "description": "Description of a declarative rule for handling events.",
@@ -135,101 +241,6 @@
           }
         }
       }
-    ],
-    "functions": [
-      {
-        "name": "addRules",
-        "type": "function",
-        "description": "Registers rules to handle events. Note that you cannot call this function as <code>chrome.declarative.addRules(...)</code>. Instead a function of this signature is provided for event objects supporting the declarative API such as <code>chrome.declarativeWebRequest.onRequest</code>.",
-        "parameters": [
-          {
-            "nodoc": "true",
-            "name": "eventName",
-            "type": "string",
-            "description": "Name of the event this function affects."
-          },
-          {
-            "name": "rules",
-            "type": "array",
-            "items": {"$ref": "Rule"},
-            "description": "Rules to be registered. These do not replace previously registered rules."
-          },
-          {
-            "name": "callback",
-            "optional": true,
-            "type": "function",
-            "parameters": [
-              {
-                "name": "rules",
-                "type": "array",
-                "items": {"$ref": "Rule"},
-                "description": "Rules that were registered, the optional parameters are filled with values."
-              }
-            ],
-            "description": "Called with registered rules."
-          }
-        ]
-      },
-      {
-        "name": "getRules",
-        "type": "function",
-        "description": "Returns currently registered rules. Note that you cannot call this function as <code>chrome.declarative.getRules(...)</code>. Instead a function of this signature is provided for event objects supporting the declarative API such as <code>chrome.declarativeWebRequest.onRequest</code>.",
-        "parameters": [
-          {
-            "nodoc": "true",
-            "name": "eventName",
-            "type": "string",
-            "description": "Name of the event this function affects."
-          },
-          {
-            "name": "ruleIdentifiers",
-            "optional": "true",
-            "type": "array",
-            "items": {"type": "string"},
-            "description": "If an array is passed, only rules with identifiers contained in this array are returned."
-          },
-          {
-            "name": "callback",
-            "type": "function",
-            "parameters": [
-              {
-                "name": "rules",
-                "type": "array",
-                "items": {"$ref": "Rule"},
-                "description": "Rules that were registered, the optional parameters are filled with values."
-              }
-            ],
-            "description": "Called with registered rules."
-          }
-        ]
-      },
-      {
-        "name": "removeRules",
-        "type": "function",
-        "description": "Unregisters currently registered rules. Note that you cannot call this function as <code>chrome.declarative.removeRules(...)</code>. Instead a function of this signature is provided for event objects supporting the declarative API such as <code>chrome.declarativeWebRequest.onRequest</code>.",
-        "parameters": [
-          {
-            "nodoc": "true",
-            "name": "eventName",
-            "type": "string",
-            "description": "Name of the event this function affects."
-          },
-          {
-            "name": "ruleIdentifiers",
-            "optional": "true",
-            "type": "array",
-            "items": {"type": "string"},
-            "description": "If an array is passed, only rules with identifiers contained in this array are unregistered."
-          },
-          {
-            "name": "callback",
-            "optional": true,
-            "type": "function",
-            "parameters": [],
-            "description": "Called when rules were unregistered."
-          }
-        ]
-      }
     ]
   }
 ]