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 34%
rename from chrome/common/extensions/api/session_restore.json
rename to chrome/common/extensions/api/sessions.json
index e44a59cab9d0527c44cdabd6065c6482cde5cb8f..e514dae89522510a734ac026bc6151beaff7fd22 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",
+        "properties": {
+          "info": {"type": "string", "description": "Represents all information about a foreign device."},
+          "sessions": {"type": "array", "items": {"$ref": "Session"}, "description": "A list of open window sessions for the foreign device, sorted from most recently to least recently modified session."}
         }
       }
     ],
@@ -49,7 +56,37 @@
             "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."

[dharcourt, 2013/08/16 02:27:34]

Nit: The last sentence (after "either tabs or windows.") is redundant. Also,
there's a space missing after the preceding sentence. Removing the last sentence
will fix both of these issues.

[Kristen Dwan, 2013/08/16 22:03:06]

Done.

+              }
+            ]
+          }
+        ]
+      },
+      {
+        "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.",

[dharcourt, 2013/08/16 02:27:34]

Nit: This was confusing to me. I think the following is more exact and would be
clearer: "Retrieves all devices with synced sessions in sorted order from the
device with most recently modified sessions to the one with least recently
modified sessions. Within each device sessions are sorted from most recently to
least recently modified."

The sort order is actually explained in the description of the callback
parameter and Device type, so this could actually be simplified to the even
clearer: "Retrieves all devices with synced sessions."

[Kristen Dwan, 2013/08/16 22:03:06]

Done.

+        "parameters": [
+          {
+            "type": "object",
+            "name": "options",
+            "optional": true,
+            "properties": {
+              "maxResults": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 10,
+                "optional": true,
+                "description": "The maximum number of devices to be returned in the requested $ref:Device list. Omit to fetch the maximum number of devices (10)."

[dharcourt, 2013/08/16 02:27:34]

Nit: As above, "Omit to fetch" -> "Omit this parameter to fetch".

[Kristen Dwan, 2013/08/16 22:03:06]

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."
               }
             ]
           }
@@ -58,10 +95,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 $ref:windows.Window.sessionId, or $ref:tabs.Tab.sessionId to restore."
+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "optional": true,
+            "parameters": [
+              {
+                "$ref": "Session",
+                "name": "restoredSession",
+                "description": "A $ref:Session containing the restored $ref:windows.Window or $ref:tabs.Tab object."
+              }
+            ]
+          }
         ]
       }
     ]