webext-schema 2.0.1 → 2.0.5

package/schemas/mail/mailext.json

@@ -1772,6 +1772,27 @@
             "description": "The fully-qualified URL to the resource."
           }
         },
+        {
+          "name": "getFrameId",
+          "type": "function",
+          "allowedContexts": [
+            "content",
+            "devtools"
+          ],
+          "description": "Get the frameId of any window global or frame element.",
+          "parameters": [
+            {
+              "type": "any",
+              "name": "target",
+              "description": "A WindowProxy or a Browsing Context container element (IFrame, Frame, Embed, Object) for the target frame."
+            }
+          ],
+          "allowCrossOriginArguments": true,
+          "returns": {
+            "type": "number",
+            "description": "The frameId of the target frame, or -1 if it doesn't exist."
+          }
+        },
         {
           "name": "setUninstallURL",
           "type": "function",
@@ -2696,7 +2717,7 @@
         {
           "name": "getCurrent",
           "type": "function",
-          "async": true,
+          "async": "callback",
           "description": "Returns the current theme for the specified window or the last focused window.",
           "parameters": [
             {
@@ -2704,6 +2725,16 @@
               "name": "windowId",
               "optional": true,
               "description": "The window for which we want the theme."
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "$ref": "ThemeType"
+                }
+              ]
             }
           ]
         },
@@ -3197,7 +3228,7 @@
         {
           "name": "onSearchRequest",
           "type": "function",
-          "description": "Creates a read-only addressbook that fires this event when searching for a contact. Note: This event may change in future releases of Thunderbird.",
+          "description": "Registering this listener will create and list a read-only address book in Thunderbird's address book window, similar to LDAP address books. When selecting this address book, users will first see no contacts, but they can search for them, which will fire this event. Contacts returned by the listener callback will be displayed as contact cards in the address book. Several listeners can be registered, to create multiple address books.\n\nThe event also fires for each registered listener (for each created read-only address book), when users type something into the mail composer's <code>To:</code> field, or into similar fields like the calendar meeting attendees field. Contacts returned by the listener callback will be added to the autocomplete results in the dropdown of that field.\n\nExample: <literalinclude>includes/addressBooks/onSearchRequest.js<lang>JavaScript</lang></literalinclude>",
           "parameters": [
             {
               "name": "node",
@@ -3219,22 +3250,23 @@
           "extraParameters": [
             {
               "name": "parameters",
+              "description": "Descriptions for the address book created by registering this listener.",
               "type": "object",
               "properties": {
                 "addressBookName": {
                   "type": "string",
                   "optional": true,
-                  "description": "The initial name of the address book."
+                  "description": "The name of the created address book."
                 },
                 "isSecure": {
                   "type": "boolean",
                   "optional": true,
-                  "description": "Whether the address book is searched securely."
+                  "description": "Whether the address book search queries are using encrypted protocols like HTTPS."
                 },
                 "id": {
                   "type": "string",
                   "optional": true,
-                  "description": "The id of the address book."
+                  "description": "The unique ID of the created address book. If several listeners have been added, the ``id`` allows to identify which address book initiated the search request. If not provided, a unique ID will be generated for you."
                 }
               }
             }
@@ -3335,11 +3367,24 @@
         {
           "name": "list",
           "type": "function",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "parentId",
               "type": "string"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "ContactNode"
+                  }
+                }
+              ]
             }
           ],
           "description": "Gets all the contacts in the address book with the id <code>parentId</code>."
@@ -3347,7 +3392,7 @@
         {
           "name": "quickSearch",
           "type": "function",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "parentId",
@@ -3397,18 +3442,41 @@
                   }
                 }
               ]
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "ContactNode"
+                  }
+                }
+              ]
             }
           ],
-          "description": "Gets all contacts matching <code>searchString</code> in the address book with the id <code>parentId</code>."
+          "description": "Gets all contacts matching ``queryInfo`` in the address book with the id ``parentId``."
         },
         {
           "name": "get",
           "type": "function",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "id",
               "type": "string"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "$ref": "ContactNode"
+                }
+              ]
             }
           ],
           "description": "Gets a single contact."
@@ -3416,7 +3484,7 @@
         {
           "name": "create",
           "type": "function",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "parentId",
@@ -3431,6 +3499,17 @@
             {
               "name": "properties",
               "$ref": "ContactProperties"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "string",
+                  "description": "The ID of the new contact."
+                }
+              ]
             }
           ],
           "description": "Adds a new contact to the address book with the id <code>parentId</code>."
@@ -3570,11 +3649,24 @@
         {
           "name": "list",
           "type": "function",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "parentId",
               "type": "string"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "MailingListNode"
+                  }
+                }
+              ]
             }
           ],
           "description": "Gets all the mailing lists in the address book with id <code>parentId</code>."
@@ -3582,11 +3674,21 @@
         {
           "name": "get",
           "type": "function",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "id",
               "type": "string"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "$ref": "MailingListNode"
+                }
+              ]
             }
           ],
           "description": "Gets a single mailing list."
@@ -3594,7 +3696,7 @@
         {
           "name": "create",
           "type": "function",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "parentId",
@@ -3616,6 +3718,17 @@
                   "optional": true
                 }
               }
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "string",
+                  "description": "The ID of the new mailing list."
+                }
+              ]
             }
           ],
           "description": "Creates a new mailing list in the address book with id <code>parentId</code>."
@@ -3680,11 +3793,24 @@
         {
           "name": "listMembers",
           "type": "function",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "id",
               "type": "string"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "contacts.ContactNode"
+                  }
+                }
+              ]
             }
           ],
           "description": "Gets all contacts that are members of the mailing list with id <code>id</code>."
@@ -4557,8 +4683,8 @@
                 "data_format": {
                   "type": "string",
                   "optional": true,
-                  "default": "ArrayBuffer",
-                  "description": "Determines the format of the ``data`` argument in ``onFileUpload``.",
+                  "default": "File",
+                  "description": "Determines the format of the ``data`` argument in ``onFileUpload``. Support for ArrayBuffer will be removed in Thunderbird 102.",
                   "enum": [
                     "ArrayBuffer",
                     "File"
@@ -4605,17 +4731,17 @@
         {
           "name": "onFileUpload",
           "type": "function",
-          "description": "Fired when a file should be uploaded to the cloud file provider",
+          "description": "Fired when a file should be uploaded to the cloud file provider.",
           "parameters": [
             {
               "name": "account",
               "$ref": "CloudFileAccount",
-              "description": "The created account"
+              "description": "The account used for the file upload."
             },
             {
               "name": "fileInfo",
               "$ref": "CloudFile",
-              "description": "The file to upload"
+              "description": "The file to upload."
             },
             {
               "name": "tab",
@@ -4628,12 +4754,17 @@
             "properties": {
               "aborted": {
                 "type": "boolean",
-                "description": "Set this to true if the file upload was aborted",
+                "description": "Set this to true if the file upload was aborted.",
                 "optional": true
               },
               "url": {
                 "type": "string",
-                "description": "The URL where the uploaded file can be accessed",
+                "description": "The URL where the uploaded file can be accessed.",
+                "optional": true
+              },
+              "templateInfo": {
+                "$ref": "CloudFileTemplateInfo",
+                "description": "Information to override the default values used in the cloud file message template.",
                 "optional": true
               }
             }
@@ -4646,13 +4777,13 @@
             {
               "name": "account",
               "$ref": "CloudFileAccount",
-              "description": "The created account"
+              "description": "The account used for the file upload."
             },
             {
               "type": "integer",
               "name": "fileId",
               "minimum": 1,
-              "description": "An identifier for this file"
+              "description": "An identifier for this file."
             },
             {
               "name": "tab",
@@ -4664,18 +4795,18 @@
         {
           "name": "onFileDeleted",
           "type": "function",
-          "description": "Fired when a file previously uploaded should be deleted",
+          "description": "Fired when a file previously uploaded should be deleted.",
           "parameters": [
             {
               "name": "account",
               "$ref": "CloudFileAccount",
-              "description": "The created account"
+              "description": "The account used for the file upload."
             },
             {
               "type": "integer",
               "name": "fileId",
               "minimum": 1,
-              "description": "An identifier for this file"
+              "description": "An identifier for this file."
             },
             {
               "name": "tab",
@@ -4687,24 +4818,24 @@
         {
           "name": "onAccountAdded",
           "type": "function",
-          "description": "Fired when a cloud file account of this add-on was created",
+          "description": "Fired when a cloud file account of this add-on was created.",
           "parameters": [
             {
               "name": "account",
               "$ref": "CloudFileAccount",
-              "description": "The created account"
+              "description": "The created account."
             }
           ]
         },
         {
           "name": "onAccountDeleted",
           "type": "function",
-          "description": "Fired when a cloud file account of this add-on was deleted",
+          "description": "Fired when a cloud file account of this add-on was deleted.",
           "parameters": [
             {
               "name": "accountId",
               "type": "string",
-              "description": "The id of the removed account"
+              "description": "The id of the removed account."
             }
           ]
         }
@@ -4713,11 +4844,11 @@
         {
           "id": "CloudFileAccount",
           "type": "object",
-          "description": "Information about a cloud file account",
+          "description": "Information about a cloud file account.",
           "properties": {
             "id": {
               "type": "string",
-              "description": "Unique identifier of the account"
+              "description": "Unique identifier of the account."
             },
             "configured": {
               "type": "boolean",
@@ -4752,19 +4883,41 @@
             }
           }
         },
+        {
+          "id": "CloudFileTemplateInfo",
+          "type": "object",
+          "description": "Information to be used in the cloud file message template.",
+          "properties": {
+            "service_icon": {
+              "type": "string",
+              "optional": true,
+              "description": "A URL pointing to an icon to represent the used cloud file service. Defaults to the icon of the provider add-on."
+            },
+            "service_name": {
+              "type": "string",
+              "optional": true,
+              "description": "A name to represent the used cloud file service. Defaults to the associated cloud file account name."
+            },
+            "service_url": {
+              "type": "string",
+              "optional": true,
+              "description": "An URL to the web page of the used cloud file service, attached the <code>service_name</code>. Defaults to the <code>service_url</code> manifest entry. Set to an empty string in order to not create a link."
+            }
+          }
+        },
         {
           "id": "CloudFile",
           "type": "object",
-          "description": "Information about a cloud file",
+          "description": "Information about a cloud file.",
           "properties": {
             "id": {
               "type": "integer",
               "minimum": 1,
-              "description": "An identifier for this file"
+              "description": "An identifier for this file."
             },
             "name": {
               "type": "string",
-              "description": "Filename of the file to be transferred"
+              "description": "Filename of the file to be transferred."
             },
             "data": {
               "choices": [
@@ -4772,13 +4925,13 @@
                   "type": "object",
                   "isInstanceOf": "ArrayBuffer",
                   "additionalProperties": true,
-                  "description": "Contents of the file to be transferred"
+                  "description": "Contents of the file to be transferred."
                 },
                 {
                   "type": "object",
                   "isInstanceOf": "File",
                   "additionalProperties": true,
-                  "description": "Contents of the file to be transferred"
+                  "description": "Contents of the file to be transferred."
                 }
               ]
             }
@@ -4789,7 +4942,7 @@
         {
           "name": "getAccount",
           "type": "function",
-          "description": "Retrieve information about a single cloud file account",
+          "description": "Retrieve information about a single cloud file account.",
           "allowedContexts": [
             "content"
           ],
@@ -4798,7 +4951,7 @@
             {
               "name": "accountId",
               "type": "string",
-              "description": "Unique identifier of the account"
+              "description": "Unique identifier of the account."
             },
             {
               "type": "function",
@@ -4815,7 +4968,7 @@
         {
           "name": "getAllAccounts",
           "type": "function",
-          "description": "Retrieve all cloud file accounts for the current add-on",
+          "description": "Retrieve all cloud file accounts for the current add-on.",
           "allowedContexts": [
             "content"
           ],
@@ -4839,7 +4992,7 @@
         {
           "name": "updateAccount",
           "type": "function",
-          "description": "Update a cloud file account",
+          "description": "Update a cloud file account.",
           "allowedContexts": [
             "content"
           ],
@@ -4848,7 +5001,7 @@
             {
               "name": "accountId",
               "type": "string",
-              "description": "Unique identifier of the account"
+              "description": "Unique identifier of the account."
             },
             {
               "name": "updateProperties",
@@ -5381,11 +5534,31 @@
           "permissions": [
             "compose"
           ],
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "tabId",
               "type": "integer"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "choices": [
+                    {
+                      "type": "array",
+                      "items": {
+                        "$ref": "ComposeAttachment"
+                      }
+                    },
+                    {
+                      "type": "any"
+                    }
+                  ]
+                }
+              ]
             }
           ]
         },
@@ -5396,7 +5569,7 @@
           "permissions": [
             "compose"
           ],
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "tabId",
@@ -5417,6 +5590,23 @@
                   "additionalProperties": true
                 }
               }
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "choices": [
+                    {
+                      "$ref": "ComposeAttachment"
+                    },
+                    {
+                      "type": "any"
+                    }
+                  ]
+                }
+              ]
             }
           ]
         },
@@ -5427,7 +5617,7 @@
           "permissions": [
             "compose"
           ],
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "tabId",
@@ -5453,6 +5643,23 @@
                   "optional": true
                 }
               }
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "choices": [
+                    {
+                      "$ref": "ComposeAttachment"
+                    },
+                    {
+                      "type": "any"
+                    }
+                  ]
+                }
+              ]
             }
           ]
         },
@@ -6061,11 +6268,21 @@
           "name": "isEnabled",
           "type": "function",
           "description": "Checks whether the composeAction is enabled.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "details",
               "$ref": "Details"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "boolean"
+                }
+              ]
             }
           ]
         },
@@ -8185,12 +8402,29 @@
           "name": "getDisplayedMessage",
           "type": "function",
           "description": "Gets the currently displayed message in the specified tab. It returns null if no messages are displayed, or if multiple messages are displayed.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "tabId",
               "type": "integer",
               "minimum": 1
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "choices": [
+                    {
+                      "$ref": "messages.MessageHeader"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                }
+              ]
             }
           ]
         },
@@ -8198,12 +8432,25 @@
           "name": "getDisplayedMessages",
           "type": "function",
           "description": "Gets an array of the currently displayed messages in the specified tab. The array is empty if no messages are displayed.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "tabId",
               "type": "integer",
               "minimum": 1
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "messages.MessageHeader"
+                  }
+                }
+              ]
             }
           ]
         }
@@ -8724,11 +8971,21 @@
           "name": "isEnabled",
           "type": "function",
           "description": "Checks whether the messageDisplayAction is enabled.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "details",
               "$ref": "Details"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "boolean"
+                }
+              ]
             }
           ]
         },
@@ -8894,7 +9151,13 @@
             "headers": {
               "type": "object",
               "description": "An object of part headers, with the header name as key, and an array of header values as value",
-              "optional": true
+              "optional": true,
+              "additionalProperties": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
             },
             "name": {
               "type": "string",
@@ -9109,7 +9372,7 @@
           "name": "list",
           "type": "function",
           "description": "Gets all messages in a folder.",
-          "async": true,
+          "async": "callback",
           "permissions": [
             "accountsRead"
           ],
@@ -9117,6 +9380,16 @@
             {
               "name": "folder",
               "$ref": "folders.MailFolder"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "$ref": "MessageList"
+                }
+              ]
             }
           ]
         },
@@ -9124,11 +9397,21 @@
           "name": "continueList",
           "type": "function",
           "description": "Returns the next chunk of messages in a list. See :doc:`how-to/messageLists` for more information.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "messageListId",
               "type": "string"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "$ref": "MessageList"
+                }
+              ]
             }
           ]
         },
@@ -9136,11 +9419,21 @@
           "name": "get",
           "type": "function",
           "description": "Returns a specified message.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "messageId",
               "type": "integer"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "$ref": "MessageHeader"
+                }
+              ]
             }
           ]
         },
@@ -9148,23 +9441,43 @@
           "name": "getFull",
           "type": "function",
           "description": "Returns a specified message, including all headers and MIME parts.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "messageId",
               "type": "integer"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "$ref": "MessagePart"
+                }
+              ]
             }
           ]
         },
         {
           "name": "getRaw",
           "type": "function",
-          "description": "Returns the unmodified source of a message as a `binary string <https://developer.mozilla.org/en-US/docs/Web/API/DOMString/Binary>`__.",
-          "async": true,
+          "description": "Returns the unmodified source of a message as a `binary string <https://developer.mozilla.org/en-US/docs/Web/API/DOMString/Binary>`__, which is a simple series of 8-bit values. If the message contains non-ASCII characters, the body parts in the binary string cannot be read directly and must be decoded according to their character sets. Use :ref:`messages.getFull` to get the correctly decoded parts. Manually decoding the raw message is probably too error-prone, especially if the message contains MIME parts with different character set encodings or attachments.\n\nTo get a readable version of the raw message as it appears in Thunderbird's message source view, it may be sufficient to decode the message according to the character set specified in its main ``content-type`` header (example: `text/html; charset=UTF-8`) using the following function (see MDN for `supported input encodings <https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings>`__): <literalinclude>includes/messages/decodeBinaryString.js<lang>JavaScript</lang></literalinclude>",
+          "async": "callback",
           "parameters": [
             {
               "name": "messageId",
               "type": "integer"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "string"
+                }
+              ]
             }
           ]
         },
@@ -9172,11 +9485,24 @@
           "name": "listAttachments",
           "type": "function",
           "description": "Lists all of the attachments of a message.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "messageId",
               "type": "integer"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "Attachment"
+                  }
+                }
+              ]
             }
           ]
         },
@@ -9184,7 +9510,7 @@
           "name": "getAttachmentFile",
           "type": "function",
           "description": "Gets the content of an attachment as a DOM <code>File</code> object.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "name": "messageId",
@@ -9194,6 +9520,18 @@
               "name": "partName",
               "type": "string",
               "pattern": "^\\d+(\\.\\d+)*$"
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "object",
+                  "isInstanceOf": "File",
+                  "additionalProperties": true
+                }
+              ]
             }
           ]
         },
@@ -9201,12 +9539,17 @@
           "name": "query",
           "type": "function",
           "description": "Gets all messages that have the specified properties, or all messages if no properties are specified.",
-          "async": true,
+          "async": "callback",
           "parameters": [
             {
               "type": "object",
               "name": "queryInfo",
               "properties": {
+                "attachment": {
+                  "type": "boolean",
+                  "optional": true,
+                  "description": "If specified, returns only messages with or without attachments."
+                },
                 "author": {
                   "type": "string",
                   "optional": true,
@@ -9283,6 +9626,16 @@
                   "description": "Returns only unread (or read if false) messages."
                 }
               }
+            },
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "$ref": "MessageList"
+                }
+              ]
             }
           ]
         },
@@ -9405,8 +9758,22 @@
           "name": "listTags",
           "type": "function",
           "description": "Returns a list of tags that can be set on messages, and their human-friendly name, colour, and sort order.",
-          "async": true,
-          "parameters": []
+          "async": "callback",
+          "parameters": [
+            {
+              "type": "function",
+              "name": "callback",
+              "optional": true,
+              "parameters": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "MessageTag"
+                  }
+                }
+              ]
+            }
+          ]
         }
       ]
     }