chrome.events

Description: The chrome.events namespace contains common types used by APIs dispatching events to notify you when something interesting happens.
Availability: Stable since Chrome 21.

An Event is an object that allows you to be notified when something interesting happens. Here's an example of using the chrome.alarms.onAlarm event to be notified whenever an alarm has elapsed: 

      chrome.alarms.onAlarm.addListener(function(alarm) {
        appendToLog('alarms.onAlarm --'
                    + ' name: '          + alarm.name
                    + ' scheduledTime: ' + alarm.scheduledTime);
      });

As the example shows, you register for notification using addListener(). The argument to addListener() is always a function that you define to handle the event, but the parameters to the function depend on which event you're handling. Checking the documentation for alarms.onAlarm, you can see that the function has a single parameter: an alarms.Alarm object that has details about the elapsed alarm.

Example APIs using Events: alarms, app.runtime, app.window, i18n, identity, runtime. Most chrome APIs do.

Summary

Types
Rule
Event
UrlFilter

Types

Rule

Description of a declarative rule for handling events.
properties
string (optional) id Optional identifier that allows referencing this rule.
array of string (optional) tags Tags can be used to annotate rules and perform operations on sets of rules.
array of any conditions List of conditions that can trigger the actions.
array of any actions List of actions that are triggered if one of the condtions is fulfilled.
integer (optional) priority Optional priority of this rule. Defaults to 100.

Event

An object which allows the addition and removal of listeners for a Chrome event.
methods

addListener

Event.addListener(function callback)

Registers an event listener callback to an event.

Parameters
function callback Called when an event occurs. The parameters of this function depend on the type of event.

The callback parameter should be a function that looks like this:

function() {...};

removeListener

Event.removeListener(function callback)

Deregisters an event listener callback from an event.

Parameters
function callback Listener that shall be unregistered.

The callback parameter should be a function that looks like this:

function() {...};

hasListener

boolean Event.hasListener(function callback)
Parameters
function callback Listener whose registration status shall be tested.

The callback parameter should be a function that looks like this:

function() {...};

hasListeners

boolean Event.hasListeners()

addRules

Event.addRules(array of Rule rules, function callback)

Registers rules to handle events.

Parameters
array of Rule rules Rules to be registered. These do not replace previously registered rules.
function (optional) callback Called with registered rules.

If you specify the callback parameter, it should be a function that looks like this:

function(array of Rule rules) {...};
array of Rule rules Rules that were registered, the optional parameters are filled with values.

getRules

Event.getRules(array of string ruleIdentifiers, function callback)

Returns currently registered rules.

Parameters
array of string (optional) ruleIdentifiers If an array is passed, only rules with identifiers contained in this array are returned.
function callback Called with registered rules.

The callback parameter should be a function that looks like this:

function(array of Rule rules) {...};
array of Rule rules Rules that were registered, the optional parameters are filled with values.

removeRules

Event.removeRules(array of string ruleIdentifiers, function callback)

Unregisters currently registered rules.

Parameters
array of string (optional) ruleIdentifiers If an array is passed, only rules with identifiers contained in this array are unregistered.
function (optional) callback Called when rules were unregistered.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

UrlFilter

Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
properties
string (optional) hostContains Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.
string (optional) hostEquals Matches if the host name of the URL is equal to a specified string.
string (optional) hostPrefix Matches if the host name of the URL starts with a specified string.
string (optional) hostSuffix Matches if the host name of the URL ends with a specified string.
string (optional) pathContains Matches if the path segment of the URL contains a specified string.
string (optional) pathEquals Matches if the path segment of the URL is equal to a specified string.
string (optional) pathPrefix Matches if the path segment of the URL starts with a specified string.
string (optional) pathSuffix Matches if the path segment of the URL ends with a specified string.
string (optional) queryContains Matches if the query segment of the URL contains a specified string.
string (optional) queryEquals Matches if the query segment of the URL is equal to a specified string.
string (optional) queryPrefix Matches if the query segment of the URL starts with a specified string.
string (optional) querySuffix Matches if the query segment of the URL ends with a specified string.
string (optional) urlContains Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.
string (optional) urlEquals Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.
string (optional) urlMatches Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.
string (optional) originAndPathMatches Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.
string (optional) urlPrefix Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.
string (optional) urlSuffix Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.
array of string (optional) schemes Matches if the scheme of the URL is equal to any of the schemes specified in the array.
array of integer or array of integer (optional) ports Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.