Adding an experimental app notification 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 6154 matching lines @@
         "description": "Fired when browser terminates debugging session for the tab.",
         "parameters": [
           {
             "type": "integer",
             "name": "tabId",
             "description": "The id of the tab that was detached."
           }
         ]
       }
     ]
+  },
+  {
+    "namespace":"experimental.app",
+    "functions": [
+      {
+        "name": "notify",
+        "type": "function",
+        "description": "Creates a notification from this app.",
+        "parameters": [
+          {
+            "type": "object",
+            "name": "details",
+            "properties": {
+              "passive": {
+                "type": "boolean",
+                "optional": "true",
+                "description": "Whether the notification should be passive (true) or active (false). The default value is true."
+              },
+              "title": {
+                "type": "string",
+                "optional": true,
+                "description": "The title of the notification. The first several characters of this will appear underneath the icon on the new tab page."  

[Finnur, 2011/06/20 12:21:46]

nit: Try to phrase it without design details such as where it appears, as it
sounds like people are still not 100% on the final design.

[asargent_no_longer_on_chrome, 2011/06/21 18:10:11]

Done.

+              },
+              "bodyText": {
+                "type": "string",
+                "optional": true,
+                "description": "The text content of the notification."
+              },
+              "linkUrl": {
+                "type": "string",
+                "optional": true,
+                "description": "The URL for an optional link to show at the bottom of the notification. See also linkText."

[Finnur, 2011/06/20 12:21:46]

nit: same here.

[asargent_no_longer_on_chrome, 2011/06/21 18:10:11]

Done.

+              },
+              "linkText": {
+                "type": "string",
+                "optional": true,
+                "description": "If a linkURL is provided, this will be used as the linkified text. It should be very short, and will be displayed truncated if too long (details TBD)."

[Finnur, 2011/06/20 12:21:46]

"details TBD"? What details?

[Finnur, 2011/06/20 12:21:46]

nit: URL is not uppercase above (linkUrl).

[asargent_no_longer_on_chrome, 2011/06/21 18:10:11]

Done.

[asargent_no_longer_on_chrome, 2011/06/21 18:10:11]

I just removed this for now. Eventually when we settle on how this will work we
can include more details either here or in the overview documentation at the top
of the page for the API.

+              },
+              "iconData": {
+                "type": "object",
+                "isInstanceOf": "ImageData",
+                "optional": true,
+                "properties": {},
+                "additionalProperties": { "type": "any" },
+                "description": "Pixel data for an image to use as the icon for this notification. Must be an ImageData object (for example, from a canvas element)."
+              }
+            }
+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "optional": true,
+            "parameters": [],
+            "description": "A callback when the function is complete. Any errors will be reported in <a href='extension.html#property-lastError'>chrome.extension.lastError</a>."
+          }
+        ]
+      },
+      {
+        "name": "clearAllNotifications",

[Finnur, 2011/06/20 12:21:46]

This function got me thinking... We have passive and active notifications. Do we
foresee that we want to clear both types at the same time and always everything?
Will people want to use, for example, passive notifications in such a way that
they maybe expire their last notification or a notification by id (id provided
in a callback). 

For example, if it is a promotion with a price, then you could have the price
change by clearing just the notification that has the old price and setup a new
one with the updated price. That way you don't have to clear out all previous
active and passive notifications just to update the price?

Just thinking out loud... :)

[asargent_no_longer_on_chrome, 2011/06/21 18:10:11]

Interesting. Perhaps we'd want to add a "clearOthers" flag or something to the
create method?

[Finnur, 2011/06/22 10:40:23]

Well, that's kind of the inverse of what I was talking about. Or, at least that
depends on what 'Others' means in this context.

But here's what I'm thinking of... App adds two notifications: 
A: Special prices all summer long. Check the store now!
B: Clearance sale. Winter clothes: 50% off.

If they just want to update B (because the discount is now 75%) they now need to
recreate A after they clearAll to get the effect they are after. Maybe this is
not an issue, certainly not for this changelist, just something to think about
whether we want to support.

On 2011/06/21 18:10:11, Antony Sargent wrote:

[asargent_no_longer_on_chrome, 2011/06/22 17:36:36]

Ok, I'll keep thinking about this but not make any changes to the CL for now. 

+        "type": "function",
+        "description": "Clears all previously sent notifications.",
+        "parameters": [
+          {
+            "type": "function",
+            "name": "callback",
+            "optional": true,
+            "description": "A callback when the function is complete. Any errors will be reported in <a href='extension.html#property-lastError'>chrome.extension.lastError</a>."
+          }
+        ]
+      },
+      {
+        "name": "setLaunchIcon",
+        "type": "function",
+        "parameters": [
+          {
+            "type": "object",
+            "name": "iconData",
+            "isInstanceOf": "ImageData",
+            "optional": true,
+            "properties": {},
+            "additionalProperties": { "type": "any" },
+            "description": "Pixel data for an image to replace the launch icon on the New Tab Page. Must be an ImageData object (for example, from a canvas element). See http://code.google.com/chrome/webstore/docs/images.html for more details."
+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "optional": true,
+            "description": "A callback when the function is complete. Any errors will be reported in <a href='extension.html#property-lastError'>chrome.extension.lastError</a>."
+          }
+        ]
+      },
+      {
+        "name": "resetLaunchIcon",
+        "type": "function",
+        "description": "Resets the app's launch icon to its default value as specified in the manifest.json file.",
+        "parameters": [
+          {
+            "type": "function",
+            "name": "callback",
+            "optional": true,
+            "description": "A callback when the function is complete. Any errors will be reported in <a href='extension.html#property-lastError'>chrome.extension.lastError</a>."
+          }
+        ]
+      }
+    ]
   }
 ]