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

chrome/common/extensions/api/sessions.json

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 [
   {
-    "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."}
         }
       }
     ],
     "functions": [
       {
         "name": "getRecentlyClosed",
         "type": "function",
         "description": "Gets the list of recently closed tabs and/or windows.",
         "parameters": [
           {
             "type": "object",
             "name": "options",
             "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)."

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

Nit: "Omit to fetch..." should be "Omit this parameter to fetch...", otherwise
the sentence ambiguous - it could mean "You should not fetch the maximum number
of entries".

I know this came from the sessionRestore API, but this is a good opportunity to
remove the unnecessary ambiguity.

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

Done.

               },
               "entryType": {
                 "type": "string",
                 "enum": ["tab", "window"],
                 "optional": true,
                 "description": "The type of entry to fetch. Omit to fetch all types of entries."

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

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

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

Done.

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