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 23%
rename from chrome/common/extensions/api/session_restore.json
rename to chrome/common/extensions/api/sessions.json
index e44a59cab9d0527c44cdabd6065c6482cde5cb8f..09ea7450ad22042c636dddd4d6cccaf12bc837fc 100644
--- a/chrome/common/extensions/api/session_restore.json
+++ b/chrome/common/extensions/api/sessions.json
@@ -4,17 +4,43 @@
 
 [
   {
-    "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": "Filter",
         "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."}
+          "maxResults": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 25,
+            "optional": true,
+            "description": "The maximum number of entries to be fetched in the requested list. Omit this parameter to fetch the maximum number of entries (25)."
+          },
+          "entryType": {
+            "type": "string",
+            "enum": ["tab", "window"],
+            "optional": true,
+            "description": "The type of entry to fetch. Omit this parameter to fetch all types of entries. Note: All $ref:Device.sessions entries will be windows regardless of this value."

[not at google - send to devlin, 2013/08/19 19:34:40]

It's conceivable to me that one day we'll allow restoring individual tabs. In
that case, this comment would be out of date - but worse, we'll have documented
an incorrectness.

It's worth saying this, but on the getDevices method - for example, "the current
implementation of this method will only return [$ref:Window Windows], so
specifying <code>"tabs"</code> as an [$ref:Filter.entryType entryType] will
return an empty list of sessions". Or similar.

[Kristen Dwan, 2013/08/19 21:35:05]

you already can restore an individual tab from a session. it's just the fact
that we always return the tabs in windows and you can choose any individual tab
from the window to restore it. the reason they're always encapsulated in a
window is because it would just be silly to have to return each individual tab
as a session *and* the same set of tabs encapsulated in their window in case you
wanted to restore the whole window (in the case that no filter was specified).

OR if you think it would be better, we can allow this filter and if tab is
specified just return every tab individually. but if nothing or window is
specified it will default to the usual return in windows.

(RESOLVED: removing filter by entryType. deemed unnecessary for either functions
that utilize filter.)

+          }
+        }
+      },        

[dharcourt, 2013/08/19 17:53:12]

FWIW, there are trailing spaces on this line (28) and this may (should?) cause
trybots to fail.

[Kristen Dwan, 2013/08/19 21:35:05]

Done.

+      {
+        "id": "Session",
+        "type": "object",
+        "properties": {
+          "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."}
         }
       }
     ],
@@ -25,31 +51,38 @@
         "description": "Gets the list of recently closed tabs and/or windows.",
         "parameters": [
           {
-            "type": "object",
+            "$ref": "Filter",
             "name": "options",

[dharcourt, 2013/08/19 17:53:12]

Nit: "options" -> "filter"?

[not at google - send to devlin, 2013/08/19 19:34:40]

I think that would result in slightly nicer generated code, too.

[Kristen Dwan, 2013/08/19 21:35:05]

Done.

-            "optional": true,
-            "properties": {
-              "maxResults": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 25,
-                "optional": true,
-                "description": "The maximum number of entries to be fetched in the requested list. Omit to fetch the maximum number of entries (25)."
-              },
-              "entryType": {
-                "type": "string",
-                "enum": ["tab", "window"],
-                "optional": true,
-                "description": "The type of entry to fetch. Omit to fetch all types of entries."
+            "optional": true
+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "parameters": [
+              {
+                "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."
               }
-            }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "getDevices",
+        "type": "function",
+        "description": "Retrieves all devices with synced sessions.",
+        "parameters": [
+          {
+            "$ref": "Filter",
+            "name": "options",

[dharcourt, 2013/08/19 17:53:12]

Nit: "options" -> "filter"?

[Kristen Dwan, 2013/08/19 21:35:05]

Done.

+            "optional": true,
+            "description": "$ref:Filter.entryType is not taken into consideration. Results will always be returned as $ref:Session.window."
           },
           {
             "type": "function",
             "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": "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. $ref:tabs.Tab objects are sorted by recency in the $ref:windows.Window of the $ref:Session objects."
               }
             ]
           }
@@ -58,10 +91,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."
+              }
+            ]
+          }
         ]
       }
     ]