chromex.app.runtime — binaryage/chromex 0.6.5

clj

Use the chrome.runtime API to retrieve the background page, return details about the manifest, and listen for and respond to events in the app or extension lifecycle. You can also use this API to convert the relative path of URLs to fully-qualified URLs.

• available since Chrome 27
• https://developer.chrome.com/apps/runtime

api-table clj

connect clj/s macro

(connect)

(connect extension-id)

(connect extension-id connect-info)

Attempts to connect to connect listeners within an extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and web messaging. Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via 'tabs.connect'.

|extension-id| - The ID of the extension or app to connect to. If omitted, a connection will be attempted with your own extension. Required if sending messages from a web page for web messaging. |connect-info| - https://developer.chrome.com/apps/runtime#property-connect-connectInfo.

https://developer.chrome.com/apps/runtime#method-connect.

connect* cljs

(connect* config extension-id connect-info)

connect-native clj/s macro

(connect-native application)

Connects to a native application in the host machine. See Native Messaging for more information.

|application| - The name of the registered application to connect to.

https://developer.chrome.com/apps/runtime#method-connectNative.

connect-native* cljs

(connect-native* config application)

gen-call clj

gen-wrap clj/s macro

(gen-wrap kind item-id config & args)

get-background-page clj/s macro

(get-background-page)

Retrieves the JavaScript 'window' object for the background page running inside the current extension/app. If the background page is an event page, the system will ensure it is loaded before calling the callback. If there is no background page, an error is set.

This function returns a core.async channel of type promise-chan which eventually receives a result value. Signature of the result value put on the channel is [background-page] where:

|background-page| - The JavaScript 'window' object for the background page.

In case of an error the channel closes without receiving any value and relevant error object can be obtained via chromex.error/get-last-error.

https://developer.chrome.com/apps/runtime#method-getBackgroundPage.

get-background-page* cljs

(get-background-page* config)

get-id clj/s macro

(get-id)

The ID of the extension/app.

https://developer.chrome.com/apps/runtime#property-id.

get-last-error clj/s macro

(get-last-error)

This will be defined during an API method callback if there was an error

https://developer.chrome.com/apps/runtime#property-lastError.

get-manifest clj/s macro

(get-manifest)

Returns details about the app or extension from the manifest. The object returned is a serialization of the full manifest file.

https://developer.chrome.com/apps/runtime#method-getManifest.

get-manifest* cljs

(get-manifest* config)

get-package-directory-entry clj/s macro

(get-package-directory-entry)

Returns a DirectoryEntry for the package directory.

This function returns a core.async channel of type promise-chan which eventually receives a result value. Signature of the result value put on the channel is [directory-entry] where:

|directory-entry| - https://developer.chrome.com/apps/runtime#property-callback-directoryEntry.

In case of an error the channel closes without receiving any value and relevant error object can be obtained via chromex.error/get-last-error.

https://developer.chrome.com/apps/runtime#method-getPackageDirectoryEntry.

get-package-directory-entry* cljs

(get-package-directory-entry* config)

get-platform-info clj/s macro

(get-platform-info)

Returns information about the current platform.

This function returns a core.async channel of type promise-chan which eventually receives a result value. Signature of the result value put on the channel is [platform-info] where:

|platform-info| - https://developer.chrome.com/apps/runtime#property-callback-platformInfo.

In case of an error the channel closes without receiving any value and relevant error object can be obtained via chromex.error/get-last-error.

https://developer.chrome.com/apps/runtime#method-getPlatformInfo.

get-platform-info* cljs

(get-platform-info* config)

get-url clj/s macro

(get-url path)

Converts a relative path within an app/extension install directory to a fully-qualified URL.

|path| - A path to a resource within an app/extension expressed relative to its install directory.

https://developer.chrome.com/apps/runtime#method-getURL.

get-url* cljs

(get-url* config path)

id* cljs

(id* config)

last-error* cljs

(last-error* config)

on-browser-update-available* cljs

(on-browser-update-available* config channel & args)

on-connect* cljs

(on-connect* config channel & args)

on-connect-external* cljs

(on-connect-external* config channel & args)

on-installed* cljs

(on-installed* config channel & args)

on-message* cljs

(on-message* config channel & args)

on-message-external* cljs

(on-message-external* config channel & args)

on-restart-required* cljs

(on-restart-required* config channel & args)

on-startup* cljs

(on-startup* config channel & args)

on-suspend* cljs

(on-suspend* config channel & args)

on-suspend-canceled* cljs

(on-suspend-canceled* config channel & args)

on-update-available* cljs

(on-update-available* config channel & args)

open-options-page clj/s macro

(open-options-page)

Open your Extension's options page, if possible.The precise behavior may depend on your manifest's options_ui or options_page key, or what Chrome happens to support at the time. For example, the page may be opened in a new tab, within chrome://extensions, within an App, or it may just focus an open options page. It will never cause the caller page to reload.If your Extension does not declare an options page, or Chrome failed to create one for some other reason, the callback will set 'lastError'.

This function returns a core.async channel of type promise-chan which eventually receives a result value. Signature of the result value put on the channel is [].

In case of an error the channel closes without receiving any value and relevant error object can be obtained via chromex.error/get-last-error.

https://developer.chrome.com/apps/runtime#method-openOptionsPage.

open-options-page* cljs

(open-options-page* config)

reload clj/s macro

(reload)

Reloads the app or extension. This method is not supported in kiosk mode. For kiosk mode, use chrome.runtime.restart() method.

https://developer.chrome.com/apps/runtime#method-reload.

reload* cljs

(reload* config)

request-update-check clj/s macro

(request-update-check)

Requests an immediate update check be done for this app/extension. Important: Most extensions/apps should not use this method, since chrome already does automatic checks every few hours, and you can listen for the 'runtime.onUpdateAvailable' event without needing to call requestUpdateCheck.This method is only appropriate to call in very limited circumstances, such as if your extension/app talks to a backend service, and the backend service has determined that the client extension/app version is very far out of date and you'd like to prompt a user to update. Most other uses of requestUpdateCheck, such as calling it unconditionally based on a repeating timer, probably only serve to waste client, network, and server resources.

This function returns a core.async channel of type promise-chan which eventually receives a result value. Signature of the result value put on the channel is [status details] where:

|status| - Result of the update check. |details| - If an update is available, this contains more information about the available update.

In case of an error the channel closes without receiving any value and relevant error object can be obtained via chromex.error/get-last-error.

https://developer.chrome.com/apps/runtime#method-requestUpdateCheck.

request-update-check* cljs

(request-update-check* config)

restart clj/s macro

(restart)

Restart the ChromeOS device when the app runs in kiosk mode. Otherwise, it's no-op.

https://developer.chrome.com/apps/runtime#method-restart.

restart* cljs

(restart* config)

restart-after-delay clj/s macro

(restart-after-delay seconds)

Restart the ChromeOS device when the app runs in kiosk mode after the given seconds. If called again before the time ends, the reboot will be delayed. If called with a value of -1, the reboot will be cancelled. It's a no-op in non-kiosk mode. It's only allowed to be called repeatedly by the first extension to invoke this API.

|seconds| - Time to wait in seconds before rebooting the device, or -1 to cancel a scheduled reboot.

This function returns a core.async channel of type promise-chan which eventually receives a result value. Signature of the result value put on the channel is [].

In case of an error the channel closes without receiving any value and relevant error object can be obtained via chromex.error/get-last-error.

https://developer.chrome.com/apps/runtime#method-restartAfterDelay.

restart-after-delay* cljs

(restart-after-delay* config seconds)

send-message clj/s macro

(send-message extension-id message)

(send-message extension-id message options)

Sends a single message to event listeners within your extension/app or a different extension/app. Similar to 'runtime.connect' but only sends a single message, with an optional response. If sending to your extension, the 'runtime.onMessage' event will be fired in every frame of your extension (except for the sender's frame), or 'runtime.onMessageExternal', if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use 'tabs.sendMessage'.

|extension-id| - The ID of the extension/app to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for web messaging. |message| - The message to send. This message should be a JSON-ifiable object. |options| - https://developer.chrome.com/apps/runtime#property-sendMessage-options.

This function returns a core.async channel of type promise-chan which eventually receives a result value. Signature of the result value put on the channel is [response] where:

|response| - The JSON response object sent by the handler of the message. If an error occurs while connecting to the extension, the callback will be called with no arguments and 'runtime.lastError' will be set to the error message.

In case of an error the channel closes without receiving any value and relevant error object can be obtained via chromex.error/get-last-error.

https://developer.chrome.com/apps/runtime#method-sendMessage.

send-message* cljs

(send-message* config extension-id message options)

send-native-message clj/s macro

(send-native-message application message)

Send a single message to a native application.

|application| - The name of the native messaging host. |message| - The message that will be passed to the native messaging host.

This function returns a core.async channel of type promise-chan which eventually receives a result value. Signature of the result value put on the channel is [response] where:

|response| - The response message sent by the native messaging host. If an error occurs while connecting to the native messaging host, the callback will be called with no arguments and 'runtime.lastError' will be set to the error message.

In case of an error the channel closes without receiving any value and relevant error object can be obtained via chromex.error/get-last-error.

https://developer.chrome.com/apps/runtime#method-sendNativeMessage.

send-native-message* cljs

(send-native-message* config application message)

set-uninstall-url clj/s macro

(set-uninstall-url url)

Sets the URL to be visited upon uninstallation. This may be used to clean up server-side data, do analytics, and implement surveys. Maximum 255 characters.

|url| - URL to be opened after the extension is uninstalled. This URL must have an http: or https: scheme. Set an empty string to not open a new tab upon uninstallation.

This function returns a core.async channel of type promise-chan which eventually receives a result value. Signature of the result value put on the channel is [].

In case of an error the channel closes without receiving any value and relevant error object can be obtained via chromex.error/get-last-error.

https://developer.chrome.com/apps/runtime#method-setUninstallURL.

set-uninstall-url* cljs

(set-uninstall-url* config url)

tap-all-events clj/s macro

(tap-all-events chan)

Taps all valid non-deprecated events in chromex.app.runtime namespace.

tap-on-browser-update-available-events clj/s macro

(tap-on-browser-update-available-events channel & args)

Fired when a Chrome update is available, but isn't installed immediately because a browser restart is required.

Events will be put on the |channel| with signature [::on-browser-update-available []].

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onBrowserUpdateAvailable.

tap-on-connect-events clj/s macro

(tap-on-connect-events channel & args)

Fired when a connection is made from either an extension process or a content script (by 'runtime.connect').

Events will be put on the |channel| with signature [::on-connect [port]] where:

|port| - https://developer.chrome.com/apps/runtime#property-onConnect-port.

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onConnect.

tap-on-connect-external-events clj/s macro

(tap-on-connect-external-events channel & args)

Fired when a connection is made from another extension (by 'runtime.connect').

Events will be put on the |channel| with signature [::on-connect-external [port]] where:

|port| - https://developer.chrome.com/apps/runtime#property-onConnectExternal-port.

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onConnectExternal.

tap-on-installed-events clj/s macro

(tap-on-installed-events channel & args)

Fired when the extension is first installed, when the extension is updated to a new version, and when Chrome is updated to a new version.

Events will be put on the |channel| with signature [::on-installed [details]] where:

|details| - https://developer.chrome.com/apps/runtime#property-onInstalled-details.

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onInstalled.

tap-on-message-events clj/s macro

(tap-on-message-events channel & args)

Fired when a message is sent from either an extension process (by 'runtime.sendMessage') or a content script (by 'tabs.sendMessage').

Events will be put on the |channel| with signature [::on-message [message sender send-response]] where:

|message| - The message sent by the calling script. |sender| - https://developer.chrome.com/apps/runtime#property-onMessage-sender.

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onMessage.

tap-on-message-external-events clj/s macro

(tap-on-message-external-events channel & args)

Fired when a message is sent from another extension/app (by 'runtime.sendMessage'). Cannot be used in a content script.

Events will be put on the |channel| with signature [::on-message-external [message sender send-response]] where:

|message| - The message sent by the calling script. |sender| - https://developer.chrome.com/apps/runtime#property-onMessageExternal-sender.

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onMessageExternal.

tap-on-restart-required-events clj/s macro

(tap-on-restart-required-events channel & args)

Fired when an app or the device that it runs on needs to be restarted. The app should close all its windows at its earliest convenient time to let the restart to happen. If the app does nothing, a restart will be enforced after a 24-hour grace period has passed. Currently, this event is only fired for Chrome OS kiosk apps.

Events will be put on the |channel| with signature [::on-restart-required [reason]] where:

|reason| - The reason that the event is being dispatched.

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onRestartRequired.

tap-on-startup-events clj/s macro

(tap-on-startup-events channel & args)

Fired when a profile that has this extension installed first starts up. This event is not fired when an incognito profile is started, even if this extension is operating in 'split' incognito mode.

Events will be put on the |channel| with signature [::on-startup []].

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onStartup.

tap-on-suspend-canceled-events clj/s macro

(tap-on-suspend-canceled-events channel & args)

Sent after onSuspend to indicate that the app won't be unloaded after all.

Events will be put on the |channel| with signature [::on-suspend-canceled []].

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onSuspendCanceled.

tap-on-suspend-events clj/s macro

(tap-on-suspend-events channel & args)

Sent to the event page just before it is unloaded. This gives the extension opportunity to do some clean up. Note that since the page is unloading, any asynchronous operations started while handling this event are not guaranteed to complete. If more activity for the event page occurs before it gets unloaded the onSuspendCanceled event will be sent and the page won't be unloaded.

Events will be put on the |channel| with signature [::on-suspend []].

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onSuspend.

tap-on-update-available-events clj/s macro

(tap-on-update-available-events channel & args)

Fired when an update is available, but isn't installed immediately because the app is currently running. If you do nothing, the update will be installed the next time the background page gets unloaded, if you want it to be installed sooner you can explicitly call chrome.runtime.reload(). If your extension is using a persistent background page, the background page of course never gets unloaded, so unless you call chrome.runtime.reload() manually in response to this event the update will not get installed until the next time chrome itself restarts. If no handlers are listening for this event, and your extension has a persistent background page, it behaves as if chrome.runtime.reload() is called in response to this event.

Events will be put on the |channel| with signature [::on-update-available [details]] where:

|details| - The manifest details of the available update.

Note: |args| will be passed as additional parameters into Chrome event's .addListener call.

https://developer.chrome.com/apps/runtime#event-onUpdateAvailable.