runtime.js 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467
  1. // Copyright 2021 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. // This file was generated by:
  5. // tools/json_schema_compiler/compiler.py.
  6. // NOTE: The format of types has changed. 'FooType' is now
  7. // 'chrome.runtime.FooType'.
  8. // Please run the closure compiler before committing changes.
  9. // See https://chromium.googlesource.com/chromium/src/+/main/docs/closure_compilation.md
  10. // IMPORTANT NOTE: Work-around for crbug.com/543822
  11. // s/chrome.runtime.tabs.Tab/chrome.tabs.Tab/
  12. /** @fileoverview Externs generated from namespace: runtime */
  13. /** @const */
  14. chrome.runtime = {};
  15. /**
  16. * An object which allows two way communication with other pages. See <a href="messaging#connect">Long-lived connections</a> for more information.
  17. * @constructor
  18. * @private
  19. * @see https://developer.chrome.com/extensions/runtime#type-Port
  20. */
  21. chrome.runtime.Port = function() {};
  22. /**
  23. * The name of the port, as specified in the call to $(ref:runtime.connect).
  24. * @type {string}
  25. * @see https://developer.chrome.com/extensions/runtime#type-name
  26. */
  27. chrome.runtime.Port.prototype.name;
  28. /**
  29. * Immediately disconnect the port. Calling <code>disconnect()</code> on an
  30. * already-disconnected port has no effect. When a port is disconnected, no new
  31. * events will be dispatched to this port.
  32. * @see https://developer.chrome.com/extensions/runtime#method-disconnect
  33. */
  34. chrome.runtime.Port.prototype.disconnect = function() {};
  35. /**
  36. * Send a message to the other end of the port. If the port is disconnected, an
  37. * error is thrown.
  38. * @param {*} message The message to send. This object should be JSON-ifiable.
  39. * @see https://developer.chrome.com/extensions/runtime#method-postMessage
  40. */
  41. chrome.runtime.Port.prototype.postMessage = function(message) {};
  42. /**
  43. * This property will <b>only</b> be present on ports passed to $(ref:runtime.onConnect onConnect) / $(ref:runtime.onConnectExternal onConnectExternal) / $(ref:runtime.onConnectExternal onConnectNative) listeners.
  44. * @type {(!chrome.runtime.MessageSender|undefined)}
  45. * @see https://developer.chrome.com/extensions/runtime#type-sender
  46. */
  47. chrome.runtime.Port.prototype.sender;
  48. /**
  49. * An object containing information about the script context that sent a message or request.
  50. * @typedef {{
  51. * tab: (!chrome.tabs.Tab|undefined),
  52. * frameId: (number|undefined),
  53. * guestProcessId: (number|undefined),
  54. * guestRenderFrameRoutingId: (number|undefined),
  55. * id: (string|undefined),
  56. * url: (string|undefined),
  57. * nativeApplication: (string|undefined),
  58. * tlsChannelId: (string|undefined),
  59. * origin: (string|undefined)
  60. * }}
  61. * @see https://developer.chrome.com/extensions/runtime#type-MessageSender
  62. */
  63. chrome.runtime.MessageSender;
  64. /**
  65. * @enum {string}
  66. * @see https://developer.chrome.com/extensions/runtime#type-PlatformOs
  67. */
  68. chrome.runtime.PlatformOs = {
  69. MAC: 'mac',
  70. WIN: 'win',
  71. ANDROID: 'android',
  72. CROS: 'cros',
  73. LINUX: 'linux',
  74. OPENBSD: 'openbsd',
  75. };
  76. /**
  77. * @enum {string}
  78. * @see https://developer.chrome.com/extensions/runtime#type-PlatformArch
  79. */
  80. chrome.runtime.PlatformArch = {
  81. ARM: 'arm',
  82. ARM64: 'arm64',
  83. X86_32: 'x86-32',
  84. X86_64: 'x86-64',
  85. MIPS: 'mips',
  86. MIPS64: 'mips64',
  87. };
  88. /**
  89. * @enum {string}
  90. * @see https://developer.chrome.com/extensions/runtime#type-PlatformNaclArch
  91. */
  92. chrome.runtime.PlatformNaclArch = {
  93. ARM: 'arm',
  94. X86_32: 'x86-32',
  95. X86_64: 'x86-64',
  96. MIPS: 'mips',
  97. MIPS64: 'mips64',
  98. };
  99. /**
  100. * An object containing information about the current platform.
  101. * @typedef {{
  102. * os: !chrome.runtime.PlatformOs,
  103. * arch: !chrome.runtime.PlatformArch,
  104. * nacl_arch: !chrome.runtime.PlatformNaclArch
  105. * }}
  106. * @see https://developer.chrome.com/extensions/runtime#type-PlatformInfo
  107. */
  108. chrome.runtime.PlatformInfo;
  109. /**
  110. * @enum {string}
  111. * @see https://developer.chrome.com/extensions/runtime#type-RequestUpdateCheckStatus
  112. */
  113. chrome.runtime.RequestUpdateCheckStatus = {
  114. THROTTLED: 'throttled',
  115. NO_UPDATE: 'no_update',
  116. UPDATE_AVAILABLE: 'update_available',
  117. };
  118. /**
  119. * @enum {string}
  120. * @see https://developer.chrome.com/extensions/runtime#type-OnInstalledReason
  121. */
  122. chrome.runtime.OnInstalledReason = {
  123. INSTALL: 'install',
  124. UPDATE: 'update',
  125. CHROME_UPDATE: 'chrome_update',
  126. SHARED_MODULE_UPDATE: 'shared_module_update',
  127. };
  128. /**
  129. * @enum {string}
  130. * @see https://developer.chrome.com/extensions/runtime#type-OnRestartRequiredReason
  131. */
  132. chrome.runtime.OnRestartRequiredReason = {
  133. APP_UPDATE: 'app_update',
  134. OS_UPDATE: 'os_update',
  135. PERIODIC: 'periodic',
  136. };
  137. /**
  138. * This will be defined during an API method callback if there was an error
  139. * @typedef {{
  140. * message: (string|undefined)
  141. * }}
  142. * @see https://developer.chrome.com/extensions/runtime#type-lastError
  143. */
  144. chrome.runtime.lastError;
  145. /**
  146. * The ID of the extension/app.
  147. * @type {string}
  148. * @see https://developer.chrome.com/extensions/runtime#type-id
  149. */
  150. chrome.runtime.id;
  151. /**
  152. * Retrieves the JavaScript 'window' object for the background page running
  153. * inside the current extension/app. If the background page is an event page,
  154. * the system will ensure it is loaded before calling the callback. If there is
  155. * no background page, an error is set.
  156. * @param {function((Window|undefined)): void} callback
  157. * @see https://developer.chrome.com/extensions/runtime#method-getBackgroundPage
  158. */
  159. chrome.runtime.getBackgroundPage = function(callback) {};
  160. /**
  161. * <p>Open your Extension's options page, if possible.</p><p>The precise
  162. * behavior may depend on your manifest's <code><a
  163. * href="optionsV2">options_ui</a></code> or <code><a
  164. * href="options">options_page</a></code> key, or what Chrome happens to support
  165. * at the time. For example, the page may be opened in a new tab, within
  166. * chrome://extensions, within an App, or it may just focus an open options
  167. * page. It will never cause the caller page to reload.</p><p>If your Extension
  168. * does not declare an options page, or Chrome failed to create one for some
  169. * other reason, the callback will set $(ref:lastError).</p>
  170. * @param {function(): void=} callback
  171. * @see https://developer.chrome.com/extensions/runtime#method-openOptionsPage
  172. */
  173. chrome.runtime.openOptionsPage = function(callback) {};
  174. /**
  175. * Returns details about the app or extension from the manifest. The object
  176. * returned is a serialization of the full <a href="manifest.html">manifest
  177. * file</a>.
  178. * @return {Object} The manifest details.
  179. * @see https://developer.chrome.com/extensions/runtime#method-getManifest
  180. */
  181. chrome.runtime.getManifest = function() {};
  182. /**
  183. * Converts a relative path within an app/extension install directory to a
  184. * fully-qualified URL.
  185. * @param {string} path A path to a resource within an app/extension expressed
  186. * relative to its install directory.
  187. * @return {string} The fully-qualified URL to the resource.
  188. * @see https://developer.chrome.com/extensions/runtime#method-getURL
  189. */
  190. chrome.runtime.getURL = function(path) {};
  191. /**
  192. * Sets the URL to be visited upon uninstallation. This may be used to clean up
  193. * server-side data, do analytics, and implement surveys. Maximum 255
  194. * characters.
  195. * @param {string} url URL to be opened after the extension is uninstalled. This
  196. * URL must have an http: or https: scheme. Set an empty string to not open
  197. * a new tab upon uninstallation.
  198. * @param {function(): void=} callback Called when the uninstall URL is set. If
  199. * the given URL is invalid, $(ref:runtime.lastError) will be set.
  200. * @see https://developer.chrome.com/extensions/runtime#method-setUninstallURL
  201. */
  202. chrome.runtime.setUninstallURL = function(url, callback) {};
  203. /**
  204. * Reloads the app or extension. This method is not supported in kiosk mode. For
  205. * kiosk mode, use chrome.runtime.restart() method.
  206. * @see https://developer.chrome.com/extensions/runtime#method-reload
  207. */
  208. chrome.runtime.reload = function() {};
  209. /**
  210. * <p>Requests an immediate update check be done for this app/extension.</p>
  211. * <p><b>Important</b>: Most extensions/apps should <b>not</b> use this method,
  212. * since Chrome already does automatic checks every few hours, and you can
  213. * listen for the $(ref:runtime.onUpdateAvailable) event without needing to call
  214. * requestUpdateCheck.</p><p>This method is only appropriate to call in very
  215. * limited circumstances, such as if your extension/app talks to a backend
  216. * service, and the backend service has determined that the client extension/app
  217. * version is very far out of date and you'd like to prompt a user to update.
  218. * Most other uses of requestUpdateCheck, such as calling it unconditionally
  219. * based on a repeating timer, probably only serve to waste client, network, and
  220. * server resources.</p>
  221. * @param {function(!chrome.runtime.RequestUpdateCheckStatus, ({
  222. * version: string
  223. * }|undefined)): void} callback
  224. * @see https://developer.chrome.com/extensions/runtime#method-requestUpdateCheck
  225. */
  226. chrome.runtime.requestUpdateCheck = function(callback) {};
  227. /**
  228. * Restart the ChromeOS device when the app runs in kiosk mode. Otherwise, it's
  229. * no-op.
  230. * @see https://developer.chrome.com/extensions/runtime#method-restart
  231. */
  232. chrome.runtime.restart = function() {};
  233. /**
  234. * Restart the ChromeOS device when the app runs in kiosk mode after the given
  235. * seconds. If called again before the time ends, the reboot will be delayed. If
  236. * called with a value of -1, the reboot will be cancelled. It's a no-op in
  237. * non-kiosk mode. It's only allowed to be called repeatedly by the first
  238. * extension to invoke this API.
  239. * @param {number} seconds Time to wait in seconds before rebooting the device,
  240. * or -1 to cancel a scheduled reboot.
  241. * @param {function(): void=} callback A callback to be invoked when a restart
  242. * request was successfully rescheduled.
  243. * @see https://developer.chrome.com/extensions/runtime#method-restartAfterDelay
  244. */
  245. chrome.runtime.restartAfterDelay = function(seconds, callback) {};
  246. /**
  247. * Attempts to connect to connect listeners within an extension/app (such as the
  248. * background page), or other extensions/apps. This is useful for content
  249. * scripts connecting to their extension processes, inter-app/extension
  250. * communication, and <a href="manifest/externally_connectable.html">web
  251. * messaging</a>. Note that this does not connect to any listeners in a content
  252. * script. Extensions may connect to content scripts embedded in tabs via
  253. * $(ref:tabs.connect).
  254. * @param {string=} extensionId The ID of the extension or app to connect to. If
  255. * omitted, a connection will be attempted with your own extension. Required
  256. * if sending messages from a web page for <a
  257. * href="manifest/externally_connectable.html">web messaging</a>.
  258. * @param {{
  259. * name: (string|undefined),
  260. * includeTlsChannelId: (boolean|undefined)
  261. * }=} connectInfo
  262. * @return {!chrome.runtime.Port} Port through which messages can be sent and
  263. * received. The port's $(ref:Port onDisconnect) event is fired if the
  264. * extension/app does not exist.
  265. * @see https://developer.chrome.com/extensions/runtime#method-connect
  266. */
  267. chrome.runtime.connect = function(extensionId, connectInfo) {};
  268. /**
  269. * Connects to a native application in the host machine. See <a
  270. * href="nativeMessaging">Native Messaging</a> for more information.
  271. * @param {string} application The name of the registered application to connect
  272. * to.
  273. * @return {!chrome.runtime.Port} Port through which messages can be sent and
  274. * received with the application
  275. * @see https://developer.chrome.com/extensions/runtime#method-connectNative
  276. */
  277. chrome.runtime.connectNative = function(application) {};
  278. /**
  279. * Sends a single message to event listeners within your extension/app or a
  280. * different extension/app. Similar to $(ref:runtime.connect) but only sends a
  281. * single message, with an optional response. If sending to your extension, the
  282. * $(ref:runtime.onMessage) event will be fired in every frame of your extension
  283. * (except for the sender's frame), or $(ref:runtime.onMessageExternal), if a
  284. * different extension. Note that extensions cannot send messages to content
  285. * scripts using this method. To send messages to content scripts, use
  286. * $(ref:tabs.sendMessage).
  287. * @param {?string|undefined} extensionId The ID of the extension/app to send
  288. * the message to. If omitted, the message will be sent to your own
  289. * extension/app. Required if sending messages from a web page for <a
  290. * href="manifest/externally_connectable.html">web messaging</a>.
  291. * @param {*} message The message to send. This message should be a JSON-ifiable
  292. * object.
  293. * @param {{
  294. * includeTlsChannelId: (boolean|undefined)
  295. * }=} options
  296. * @param {function(*): void=} responseCallback
  297. * @see https://developer.chrome.com/extensions/runtime#method-sendMessage
  298. */
  299. chrome.runtime.sendMessage = function(extensionId, message, options, responseCallback) {};
  300. /**
  301. * Send a single message to a native application.
  302. * @param {string} application The name of the native messaging host.
  303. * @param {Object} message The message that will be passed to the native
  304. * messaging host.
  305. * @param {function(*): void=} responseCallback
  306. * @see https://developer.chrome.com/extensions/runtime#method-sendNativeMessage
  307. */
  308. chrome.runtime.sendNativeMessage = function(application, message, responseCallback) {};
  309. /**
  310. * Returns information about the current platform.
  311. * @param {function(!chrome.runtime.PlatformInfo): void} callback Called with
  312. * results
  313. * @see https://developer.chrome.com/extensions/runtime#method-getPlatformInfo
  314. */
  315. chrome.runtime.getPlatformInfo = function(callback) {};
  316. /**
  317. * Returns a DirectoryEntry for the package directory.
  318. * @param {function(DirectoryEntry): void} callback
  319. * @see https://developer.chrome.com/extensions/runtime#method-getPackageDirectoryEntry
  320. */
  321. chrome.runtime.getPackageDirectoryEntry = function(callback) {};
  322. /**
  323. * Fired when a profile that has this extension installed first starts up. This
  324. * event is not fired when an incognito profile is started, even if this
  325. * extension is operating in 'split' incognito mode.
  326. * @type {!ChromeEvent}
  327. * @see https://developer.chrome.com/extensions/runtime#event-onStartup
  328. */
  329. chrome.runtime.onStartup;
  330. /**
  331. * Fired when the extension is first installed, when the extension is updated to
  332. * a new version, and when Chrome is updated to a new version.
  333. * @type {!ChromeEvent}
  334. * @see https://developer.chrome.com/extensions/runtime#event-onInstalled
  335. */
  336. chrome.runtime.onInstalled;
  337. /**
  338. * Sent to the event page just before it is unloaded. This gives the extension
  339. * opportunity to do some clean up. Note that since the page is unloading, any
  340. * asynchronous operations started while handling this event are not guaranteed
  341. * to complete. If more activity for the event page occurs before it gets
  342. * unloaded the onSuspendCanceled event will be sent and the page won't be
  343. * unloaded.
  344. * @type {!ChromeEvent}
  345. * @see https://developer.chrome.com/extensions/runtime#event-onSuspend
  346. */
  347. chrome.runtime.onSuspend;
  348. /**
  349. * Sent after onSuspend to indicate that the app won't be unloaded after all.
  350. * @type {!ChromeEvent}
  351. * @see https://developer.chrome.com/extensions/runtime#event-onSuspendCanceled
  352. */
  353. chrome.runtime.onSuspendCanceled;
  354. /**
  355. * Fired when an update is available, but isn't installed immediately because
  356. * the app is currently running. If you do nothing, the update will be installed
  357. * the next time the background page gets unloaded, if you want it to be
  358. * installed sooner you can explicitly call chrome.runtime.reload(). If your
  359. * extension is using a persistent background page, the background page of
  360. * course never gets unloaded, so unless you call chrome.runtime.reload()
  361. * manually in response to this event the update will not get installed until
  362. * the next time Chrome itself restarts. If no handlers are listening for this
  363. * event, and your extension has a persistent background page, it behaves as if
  364. * chrome.runtime.reload() is called in response to this event.
  365. * @type {!ChromeEvent}
  366. * @see https://developer.chrome.com/extensions/runtime#event-onUpdateAvailable
  367. */
  368. chrome.runtime.onUpdateAvailable;
  369. /**
  370. * Fired when a Chrome update is available, but isn't installed immediately
  371. * because a browser restart is required.
  372. * @type {!ChromeEvent}
  373. * @see https://developer.chrome.com/extensions/runtime#event-onBrowserUpdateAvailable
  374. */
  375. chrome.runtime.onBrowserUpdateAvailable;
  376. /**
  377. * Fired when a connection is made from either an extension process or a content
  378. * script (by $(ref:runtime.connect)).
  379. * @type {!ChromeEvent}
  380. * @see https://developer.chrome.com/extensions/runtime#event-onConnect
  381. */
  382. chrome.runtime.onConnect;
  383. /**
  384. * Fired when a connection is made from another extension (by
  385. * $(ref:runtime.connect)).
  386. * @type {!ChromeEvent}
  387. * @see https://developer.chrome.com/extensions/runtime#event-onConnectExternal
  388. */
  389. chrome.runtime.onConnectExternal;
  390. /**
  391. * Fired when a connection is made from a native application. Currently only
  392. * supported on Chrome OS.
  393. * @type {!ChromeEvent}
  394. * @see https://developer.chrome.com/extensions/runtime#event-onConnectNative
  395. */
  396. chrome.runtime.onConnectNative;
  397. /**
  398. * Fired when a message is sent from either an extension process (by
  399. * $(ref:runtime.sendMessage)) or a content script (by $(ref:tabs.sendMessage)).
  400. * @type {!ChromeEvent}
  401. * @see https://developer.chrome.com/extensions/runtime#event-onMessage
  402. */
  403. chrome.runtime.onMessage;
  404. /**
  405. * Fired when a message is sent from another extension/app (by
  406. * $(ref:runtime.sendMessage)). Cannot be used in a content script.
  407. * @type {!ChromeEvent}
  408. * @see https://developer.chrome.com/extensions/runtime#event-onMessageExternal
  409. */
  410. chrome.runtime.onMessageExternal;
  411. /**
  412. * Fired when an app or the device that it runs on needs to be restarted. The
  413. * app should close all its windows at its earliest convenient time to let the
  414. * restart to happen. If the app does nothing, a restart will be enforced after
  415. * a 24-hour grace period has passed. Currently, this event is only fired for
  416. * Chrome OS kiosk apps.
  417. * @type {!ChromeEvent}
  418. * @see https://developer.chrome.com/extensions/runtime#event-onRestartRequired
  419. */
  420. chrome.runtime.onRestartRequired;