Sessions API - previously Session Restore API. Supports restoring currently open foreign windows an…

chrome/common/extensions/api/sessions.json

Index: chrome/common/extensions/api/sessions.json
diff --git a/chrome/common/extensions/api/session_restore.json b/chrome/common/extensions/api/sessions.json
similarity index 35%
rename from chrome/common/extensions/api/session_restore.json
rename to chrome/common/extensions/api/sessions.json
index e44a59cab9d0527c44cdabd6065c6482cde5cb8f..d3fb752766d8537032c702bbb0753df069e4ff5b 100644
--- a/chrome/common/extensions/api/session_restore.json
+++ b/chrome/common/extensions/api/sessions.json
@@ -4,17 +4,24 @@
 
 [
   {
-    "namespace": "sessionRestore",
-    "description": "Use the <code>chrome.sessionRestore</code> API to query and restore tabs and windows from a browsing session.",
+    "namespace": "sessions",
+    "description": "Use the <code>chrome.sessions</code> API to query and restore tabs and windows from a browsing session.",
     "types": [
       {
-        "id": "ClosedEntry",
+        "id": "Session",
         "type": "object",
         "properties": {
-          "id": {"type": "integer", "minimum": 0, "description": "The ID of the browser session."},
-          "timestamp": {"type": "integer", "description": "The time when the window or tab was closed, represented in milliseconds since the epoch"},
-          "tab": {"$ref": "tabs.Tab", "optional": true, "description": "The closed $ref:tabs.Tab, if this entry describes a tab. Either this or $ref:ClosedEntry.window will be set."},
-          "window": {"$ref": "windows.Window", "optional": true, "description": "The closed $ref:windows.Window, if this entry describes a window. Either this or $ref:ClosedEntry.tab will be set."}
+          "lastModified": {"type": "integer", "description": "The time when the window or tab was closed, represented in milliseconds since the epoch"},
+          "tab": {"$ref": "tabs.Tab", "optional": true, "description": "The closed $ref:tabs.Tab, if this entry describes a tab. Either this or $ref:Session.window will be set."},
+          "window": {"$ref": "windows.Window", "optional": true, "description": "The closed $ref:windows.Window, if this entry describes a window. Either this or $ref:Session.tab will be set."}
+        }
+      },
+      {
+        "id": "Device",
+        "type": "object",

[not at google - send to devlin, 2013/08/06 19:04:09]

description here should include that this represents a foreign device ("device
on another machine" or whatever the term people use is).

[Kristen Dwan, 2013/08/12 15:11:30]

Done.

+        "properties": {
+          "info": {"type": "string", "description": "Represents all information about device."},

[not at google - send to devlin, 2013/08/06 19:04:09]

A string represents all information about the device? that doesn't make sense.

Wasn't this supposed to be an ID into the devices API?

[Kristen Dwan, 2013/08/12 15:11:30]

Yeah (this is just a temp placeholder) - it will be the linked
signedInDevices.DeviceInfo. I put a note up in the description. should have
included it in the pub & mail too. Was waiting on lingesh to get the code
checked in for that. Will mail out the addition of DeviceInfo information after
I finish this up.

+          "sessions": {"type": "array", "items": {"$ref": "Session"}, "description": "Each session represents a window and its currently open tabs on said device. The array will comprise of all window entries currently open on related device."}

[not at google - send to devlin, 2013/08/06 19:04:09]

A list of open window sessions for the [adjective] device, from most recently to
least recently changed. [something about the number of sessions].

[Kristen Dwan, 2013/08/12 15:11:30]

Done.

         }
       }
     ],
@@ -49,7 +56,30 @@
             "name": "callback",
             "parameters": [
               {
-                "name": "entries", "type": "array", "items": { "$ref": "ClosedEntry" }, "description": "The list of closed entries in reverse order that they were closed (the most recently closed tab or window will be at index <code>0</code>). If <code>entryType</code> is specified the entries will be only of that type, otherwise the entries may contain either tabs or windows.List of $ref:ClosedEntry representing the closed tab/window for the session."
+                "name": "sessions", "type": "array", "items": { "$ref": "Session" }, "description": "The list of closed entries in reverse order that they were closed (the most recently closed tab or window will be at index <code>0</code>). If <code>entryType</code> is specified the entries will be only of that type, otherwise the entries may contain either tabs or windows.List of $ref:Session representing the closed tab/window for the session."
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "getDevices",
+        "type": "function",
+        "description": "Retrieves all synced sessions and returns in sorted order from device with most recently modified session to device with least recently modified session, and within each device by most recent to least recently modified session.",
+        "parameters": [
+          {
+            "name": "maxResults",
+            "type": "integer",
+            "optional": true,
+            "minimum": 0,
+            "maximum": 10

[not at google - send to devlin, 2013/08/06 19:04:09]

make this first parameter an object with argument properties:

session.getDevices({
  maxResults: 6
}, function(devices) {
  ...
});

is forwards compatible, whereas

session.getDevices(6, function(devices) {})

isn't. For example, one thing we might want to implement here is paging, which
would be configurable via other properties of the options object.

[Kristen Dwan, 2013/08/12 15:11:30]

Done.

+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "parameters": [
+              {
+                "name": "devices", "type": "array", "items": { "$ref": "Device" }, "description": "The list of $ref:Device objects for each synced session, sorted in order from device with most recently modified session to device with least recently modified session, and within each device by most recent to least recently modified session."

[not at google - send to devlin, 2013/08/06 19:04:09]

"and within each device..." that documentation should be part of the Device type
documentation.

[Kristen Dwan, 2013/08/12 15:11:30]

Done.

               }
             ]
           }
@@ -58,10 +88,26 @@
       {
         "name": "restore",
         "type": "function",
-        "description": "Reopens a $ref:ClosedEntry, with an optional callback to run when the entry has been restored.",
+        "description": "Reopens a $ref:Session, $ref:windows.Window, or $ref:tabs.Tab, with an optional callback to run when the entry has been restored.",
         "parameters": [
-          {"type": "integer", "name": "id", "optional": true, "description": "The id of the $ref:ClosedEntry to restore."},
-          {"type": "function", "name": "callback", "optional": true, "parameters": []}
+          {
+            "type": "string",
+            "name": "sessionId",
+            "optional": true,
+            "description": "The API provided $ref:windows.Window.sessionId, or $ref:tabs.Tab.sessionId to restore."

[not at google - send to devlin, 2013/08/06 19:04:09]

"The API provided" sounds awkward.

[Kristen Dwan, 2013/08/12 15:11:30]

Done.

+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "optional": true,
+            "parameters": [
+              {
+                "choices": [{"$ref": "windows.Window"}, {"$ref": "tabs.Tab"}],
+                "name": "restoredSession",
+                "description": "The restored $ref:windows.Window or $ref:tabs.Tab object."

[not at google - send to devlin, 2013/08/06 19:04:09]

I wonder whether this should actually be an object with a window and a tab,
since if we're dealing in abstract session IDs here (which - we can, clearly)
there isn't a non-hacky way to tell the difference.

In fact, you could just return a Session object.

[Kristen Dwan, 2013/08/12 15:11:30]

Done.

+              }
+            ]
+          }
         ]
       }
     ]