diff options
Diffstat (limited to 'chrome/common/extensions/docs')
41 files changed, 1916 insertions, 27 deletions
diff --git a/chrome/common/extensions/docs/api_index.html b/chrome/common/extensions/docs/api_index.html index 7fe848c..098b48d 100644 --- a/chrome/common/extensions/docs/api_index.html +++ b/chrome/common/extensions/docs/api_index.html @@ -221,7 +221,7 @@ so that extensions can interact with the browser. Here are the supported chrome.* APIs: </p> <ul> - <li><a href="alarms.html" js="">alarms</a></li><li><a href="bookmarks.html" js="">bookmarks</a></li><li><a href="browserAction.html" js="">browserAction</a></li><li><a href="browsingData.html" js="">browsingData</a></li><li><a href="contentSettings.html" js="">contentSettings</a></li><li><a href="contextMenus.html" js="">contextMenus</a></li><li><a href="cookies.html" js="">cookies</a></li><li><a href="debugger.html" js="">debugger</a></li><li><a href="declarativeWebRequest.html" js="">declarativeWebRequest</a></li><li><a href="extension.html" js="">extension</a></li><li><a href="fileBrowserHandler.html" js="">fileBrowserHandler</a></li><li><a href="history.html" js="">history</a></li><li><a href="i18n.html" js="">i18n</a></li><li><a href="idle.html" js="">idle</a></li><li><a href="management.html" js="">management</a></li><li><a href="omnibox.html" js="">omnibox</a></li><li><a href="pageAction.html" js="">pageAction</a></li><li><a href="pageCapture.html" js="">pageCapture</a></li><li><a href="permissions.html" js="">permissions</a></li><li><a href="privacy.html" js="">privacy</a></li><li><a href="proxy.html" js="">proxy</a></li><li><a href="storage.html" js="">storage</a></li><li><a href="tabs.html" js="">tabs</a></li><li><a href="topSites.html" js="">topSites</a></li><li><a href="tts.html" js="">tts</a></li><li><a href="ttsEngine.html" js="">ttsEngine</a></li><li><a href="types.html" js="">types</a></li><li><a href="webNavigation.html" js="">webNavigation</a></li><li><a href="webRequest.html" js="">webRequest</a></li><li><a href="webstore.html" js="">webstore</a></li><li><a href="windows.html" js="">windows</a></li> + <li><a href="alarms.html" js="">alarms</a></li><li><a href="bookmarks.html" js="">bookmarks</a></li><li><a href="browserAction.html" js="">browserAction</a></li><li><a href="browsingData.html" js="">browsingData</a></li><li><a href="contentSettings.html" js="">contentSettings</a></li><li><a href="contextMenus.html" js="">contextMenus</a></li><li><a href="cookies.html" js="">cookies</a></li><li><a href="debugger.html" js="">debugger</a></li><li><a href="declarative.html" js="">declarative</a></li><li><a href="declarativeWebRequest.html" js="">declarativeWebRequest</a></li><li><a href="extension.html" js="">extension</a></li><li><a href="fileBrowserHandler.html" js="">fileBrowserHandler</a></li><li><a href="history.html" js="">history</a></li><li><a href="i18n.html" js="">i18n</a></li><li><a href="idle.html" js="">idle</a></li><li><a href="management.html" js="">management</a></li><li><a href="omnibox.html" js="">omnibox</a></li><li><a href="pageAction.html" js="">pageAction</a></li><li><a href="pageCapture.html" js="">pageCapture</a></li><li><a href="permissions.html" js="">permissions</a></li><li><a href="privacy.html" js="">privacy</a></li><li><a href="proxy.html" js="">proxy</a></li><li><a href="storage.html" js="">storage</a></li><li><a href="tabs.html" js="">tabs</a></li><li><a href="topSites.html" js="">topSites</a></li><li><a href="tts.html" js="">tts</a></li><li><a href="ttsEngine.html" js="">ttsEngine</a></li><li><a href="types.html" js="">types</a></li><li><a href="webNavigation.html" js="">webNavigation</a></li><li><a href="webRequest.html" js="">webRequest</a></li><li><a href="webstore.html" js="">webstore</a></li><li><a href="windows.html" js="">windows</a></li> </ul> <h2 id="experimental">Experimental APIs</h2> <p> diff --git a/chrome/common/extensions/docs/bookmarks.html b/chrome/common/extensions/docs/bookmarks.html index 3838a2c..488da43 100644 --- a/chrome/common/extensions/docs/bookmarks.html +++ b/chrome/common/extensions/docs/bookmarks.html @@ -1934,6 +1934,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onChildrenReordered"></a> <h4>onChildrenReordered</h4> @@ -2041,6 +2042,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onCreated"></a> <h4>onCreated</h4> @@ -2112,6 +2114,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onImportBegan"></a> <h4>onImportBegan</h4> @@ -2127,6 +2130,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onImportEnded"></a> <h4>onImportEnded</h4> @@ -2142,6 +2146,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onMoved"></a> <h4>onMoved</h4> @@ -2318,6 +2323,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onRemoved"></a> <h4>onRemoved</h4> @@ -2444,6 +2450,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/browserAction.html b/chrome/common/extensions/docs/browserAction.html index 2147329..7a2c5b1 100644 --- a/chrome/common/extensions/docs/browserAction.html +++ b/chrome/common/extensions/docs/browserAction.html @@ -1543,6 +1543,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/build/directory.py b/chrome/common/extensions/docs/build/directory.py index ad23c4c..6f9097a 100644 --- a/chrome/common/extensions/docs/build/directory.py +++ b/chrome/common/extensions/docs/build/directory.py @@ -142,8 +142,7 @@ class ApiManifest(object): "chrome.types.get": "types.html#method-ChromeSetting-get" } - If the API namespace is defined "nodoc" or "internal" then an empty dict - is returned. + If the API namespace is defined "nodoc" then an empty dict is returned. """ api_dict = {} namespace = module['namespace'] @@ -185,8 +184,7 @@ class ApiManifest(object): "chrome.tabs.onDetached" : "tabs.html#event-onDetatched" } - If the API namespace is defined "nodoc" or "internal" then an empty dict - is returned. + If the API namespace is defined "nodoc" then an empty dict is returned. Raises: Exception: If the key supplied is not a member of _MODULE_DOC_KEYS. @@ -219,10 +217,7 @@ class ApiManifest(object): if not self._disableDocs(module)) def _disableDocs(self, obj): - for key in ['nodoc', 'internal']: - if key in obj and obj[key]: - return True - return False + return 'nodoc' in obj and obj['nodoc'] def getDocumentationLinks(self): """ Parses the extension API JSON manifest and returns a dict of all diff --git a/chrome/common/extensions/docs/cookies.html b/chrome/common/extensions/docs/cookies.html index 9f8c5be..3b1e0b9 100644 --- a/chrome/common/extensions/docs/cookies.html +++ b/chrome/common/extensions/docs/cookies.html @@ -1585,6 +1585,7 @@ see <a href="samples.html">Samples</a>. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/debugger.html b/chrome/common/extensions/docs/debugger.html index 225cdae..fe1c53a 100644 --- a/chrome/common/extensions/docs/debugger.html +++ b/chrome/common/extensions/docs/debugger.html @@ -685,6 +685,7 @@ You can find samples of this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onEvent"></a> <h4>onEvent</h4> @@ -776,6 +777,7 @@ You can find samples of this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/declarative.html b/chrome/common/extensions/docs/declarative.html new file mode 100644 index 0000000..c21a118 --- /dev/null +++ b/chrome/common/extensions/docs/declarative.html @@ -0,0 +1,1314 @@ +<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: + 1) The <head> information in this page is significant, should be uniform + across api docs and should be edited only with knowledge of the + templating mechanism. + 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a + browser, it will be re-generated from the template, json schema and + authored overview content. + 4) The <body>.innerHTML is also generated by an offline step so that this + page may easily be indexed by search engines. +--><html xmlns="http://www.w3.org/1999/xhtml"><head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> + <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> + <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js"> + </script> + <script type="text/javascript" src="../../../../third_party/json_minify/minify-sans-regexp.js"> + </script> + <script type="text/javascript" src="js/api_page_generator.js"></script> + <script type="text/javascript" src="js/bootstrap.js"></script> + <script type="text/javascript" src="js/sidebar.js"></script> + <meta name="description" content="Documentation for the chrome.declarative module, which is part of the Google Chrome extension APIs."><title>chrome.declarative - Google Chrome Extensions - Google Code</title></head> + <body> <div id="devModeWarning" class="displayModeWarning"> + You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files. + </div> + <div id="branchWarning" class="displayModeWarning"> + <span>WARNING: This is the <span id="branchName">BETA</span> documentation. + It may not work with the stable release of Chrome.</span> + <select id="branchChooser"> + <option>Choose a different version... + </option><option value="">Stable + </option><option value="beta">Beta + </option><option value="dev">Dev + </option><option value="trunk">Trunk + </option></select> + </div> + <div id="unofficialWarning" class="displayModeWarning"> + <span>WARNING: This is unofficial documentation. It may not work with the + current release of Chrome.</span> + <button id="goToOfficialDocs">Go to the official docs</button> + </div> + <div id="gc-container" class="labs"> + <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> + <!-- In particular, sub-templates that recurse, must be used by allowing + jstemplate to make a copy of the template in this section which + are not operated on by way of the jsskip="true" --> + <!-- /SUBTEMPLATES --> + <a id="top"></a> + <div id="skipto"> + <a href="#gc-pagecontent">Skip to page content</a> + <a href="#gc-toc">Skip to main navigation</a> + </div> + <!-- API HEADER --> + <table id="header" width="100%" cellspacing="0" border="0"> + <tbody><tr> + <td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td> + <td valign="middle" width="100%" style="padding-left:0.6em;"> + <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> + <div id="gsc-search-box"> + <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> + <input type="hidden" name="ie" value="UTF-8"> + <input type="text" name="q" value="" size="55"> + <input class="gsc-search-button" type="submit" name="sa" value="Search"> + <br> + <span class="greytext">e.g. "page action" or "tabs"</span> + </div> + </form> + <script type="text/javascript" src="https://www.google.com/jsapi"></script> + <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> + <script type="text/javascript" src="https://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> + <script type="text/javascript" src="https://www.google.com/coop/cse/brand?form=cse&lang=en"></script> + </td> + </tr> + </tbody></table> + <div id="codesiteContent" class=""> + <a id="gc-topnav-anchor"></a> + <div id="gc-topnav"> + <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> + <ul id="home" class="gc-topnav-tabs"> + <li id="home_link"> + <a href="index.html" title="Google Chrome Extensions home page">Home</a> + </li> + <li id="docs_link"> + <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> + </li> + <li id="faq_link"> + <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> + </li> + <li id="samples_link"> + <a href="samples.html" title="Sample extensions (with source code)">Samples</a> + </li> + <li id="group_link"> + <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> + </li> + <li id="so_link"> + <a href="http://stackoverflow.com/questions/tagged/google-chrome-extension" title="[google-chrome-extension] tag on Stack Overflow">Questions?</a> + </li> + </ul> + </div> <!-- end gc-topnav --> + <div class="g-section g-tpl-170"> + <!-- SIDENAV --> + <div class="g-unit g-first" id="gc-toc"> + <ul> + <li><a href="getstarted.html">Getting Started</a></li> + <li><a href="overview.html">Overview</a></li> + <li><a href="whats_new.html">What's New?</a></li> + <li><h2><a href="devguide.html">Developer's Guide</a></h2> + <ul> + <li>Browser UI + <ul> + <li><a href="browserAction.html">Browser Actions</a></li> + <li><a href="contextMenus.html">Context Menus</a></li> + <li><a href="notifications.html">Desktop Notifications</a></li> + <li><a href="omnibox.html">Omnibox</a></li> + <li><a href="options.html">Options Pages</a></li> + <li><a href="override.html">Override Pages</a></li> + <li><a href="pageAction.html">Page Actions</a></li> + </ul> + </li> + <li>Browser Interaction + <ul> + <li><a href="bookmarks.html">Bookmarks</a></li> + <li><a href="cookies.html">Cookies</a></li> + <li><a href="devtools.html">Developer Tools</a></li> + <li><a href="events.html">Events</a></li> + <li><a href="history.html">History</a></li> + <li><a href="management.html">Management</a></li> + <li><a href="tabs.html">Tabs</a></li> + <li><a href="windows.html">Windows</a></li> + </ul> + </li> + <li>Implementation + <ul> + <li><a href="a11y.html">Accessibility</a></li> + <li><a href="background_pages.html">Background Pages</a></li> + <li><a href="content_scripts.html">Content Scripts</a></li> + <li><a href="xhr.html">Cross-Origin XHR</a></li> + <li><a href="i18n.html">Internationalization</a></li> + <li><a href="messaging.html">Message Passing</a></li> + <li><a href="permissions.html">Optional Permissions</a></li> + <li><a href="npapi.html">NPAPI Plugins</a></li> + </ul> + </li> + <li>Finishing + <ul> + <li><a href="hosting.html">Hosting</a></li> + <li><a href="external_extensions.html">Other Deployment Options</a></li> + </ul> + </li> + </ul> + </li> + <li><h2><a href="apps.html">Packaged Apps</a></h2></li> + <li><h2><a href="tutorials.html">Tutorials</a></h2> + <ul> + <li><a href="tut_debugging.html">Debugging</a></li> + <li><a href="tut_analytics.html">Google Analytics</a></li> + <li><a href="tut_oauth.html">OAuth</a></li> + </ul> + </li> + <li><h2>Reference</h2> + <ul> + <li>Formats + <ul> + <li><a href="manifest.html">Manifest Files</a></li> + <li><a href="match_patterns.html">Match Patterns</a></li> + </ul> + </li> + <li><a href="permission_warnings.html">Permission Warnings</a></li> + <li><a href="api_index.html">chrome.* APIs</a></li> + <li><a href="api_other.html">Other APIs</a></li> + </ul> + </li> + <li><h2><a href="samples.html">Samples</a></h2></li> + <div class="line"> </div> + <li><h2>More</h2> + <ul> + <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li> + <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li> + <li><a href="themes.html">Themes</a></li> + </ul> + </li> + </ul> + </div> + <script> + initToggles(); + </script> + <div class="g-unit" id="gc-pagecontent"> + <div id="pageTitle"> + <h1 class="page_title">chrome.declarative</h1> + </div> + <!-- TABLE OF CONTENTS --> + <div id="toc"> + <h2>Contents</h2> + <ol> + <li> + <a href="#notes">Notes</a> + <ol> + </ol> + </li><li> + <a href="#manifest">Manifest</a> + <ol> + </ol> + </li><li> + <a href="#rules">Rules</a> + <ol> + </ol> + </li><li> + <a href="#eventobjects">Event objects</a> + <ol> + <li> + <a href="#addingrules">Adding rules</a> + </li><li> + <a href="#removingrules">Removing rules</a> + </li><li> + <a href="#retrievingrules">Retrieving rules</a> + </li> + </ol> + </li> + <li> + <a href="#apiReference">API reference: chrome.declarative</a> + <ol> + <li> + <a href="#global-methods">Methods</a> + <ol> + <li> + <a href="#method-addRules">addRules</a> + </li><li> + <a href="#method-getRules">getRules</a> + </li><li> + <a href="#method-removeRules">removeRules</a> + </li> + </ol> + </li> + <li> + <a href="#types">Types</a> + <ol> + <li> + <a href="#type-Rule">Rule</a> + <ol> + </ol> + </li><li> + <a href="#type-UrlFilter">UrlFilter</a> + <ol> + </ol> + </li> + </ol> + </li> + </ol> + </li> + </ol> + </div> + <!-- /TABLE OF CONTENTS --> + <!-- Standard content lead-in for experimental API pages --> + <p class="warning"> + <!-- Standard content lead-in for APIs that are not yet available on + the stable channel. --> + <em>Warning:</em> This API is still under development. It is only + available for Chrome users on the + <span> + <strong>dev</strong> + <a href="http://www.chromium.org/getting-involved/dev-channel">early + release channel</a>.</span> + <a href="TODO">Learn more</a>. + </p> + <!-- STATIC CONTENT PLACEHOLDER --> + <div id="static"><!-- BEGIN AUTHORED CONTENT --> +<h2 id="notes">Notes</h2> +<p> +The Declarative API is a framework to define rules consisting of declarative +conditions and actions. Conditions are evaluated in the browser rather than the +JavaScript engine which reduces roundtrip latencies and allows for very high +efficiency. +</p> +<p></p>The Declarative API is an abstract foundation for the <a href="declarativeWebRequest.html">Declarative Web Request API</a> and +possibly further extension APIs in the future. This page describes the +underlying concepts of all Declarative APIs. +<p></p> +<h2 id="manifest">Manifest</h2> +<p> +You must declare the "declarative" permission in your extension's manifest +to use APIs that are based on this API. +</p> +<pre>{ + "name": "My extension", + ... +<b> "permissions": [ + "declarative", + ]</b>, + ... +}</pre> +<h2 id="rules">Rules</h2> +<p>The simplest possible rule consists of one or more conditions and one or more +actions:</p> +<pre>var rule = { + conditions: [ /* my conditions */ ], + actions: [ /* my actions */ ] +}; +</pre> +<p>If any of the conditions is fulfilled, all actions are executed.</p> +<p>In addition to conditions and actions you may give each rule an identifier, +which simplifies unregistering previously registered rules, and a priority to +define precedences among rules. Priorities are only considered if rules conflict +each other or need to be executed in a specific order.</p> +<pre>var rule = { + id: "my rule", // optional, will be generated if not set. + priority: 100, // optional, defaults to 100. + conditions: [ /* my conditions */ ], + actions: [ /* my actions */ ] +}; +</pre> +<h2 id="eventobjects">Event objects</h2> +<p> +<a href="events.html">Event objects</a> may support rules. These event objects +don't call a callback function when events happer but test whether any +registered rule has at least one fulfilled condition and execute the actions +associated with this rule. Event objects supporting the declarative API have +three relevant methods: <a href="#method-addRules"><code>addRules()</code></a>, +<a href="#method-removeRules"><code>removeRules()</code></a>, and +<a href="#method-getRules"><code>getRules()</code></a>. +</p> +<h3 id="addingrules">Adding rules</h3> +<p> +To add rules call the <code>addRules()</code> function of the event object. It +takes an array of rule instances as its first parameter and a callback function +that is called on completion. +</p> +<pre>var rule_list = [rule1, rule2, ...]; +function addRules(rule_list, function callback(details) {...}); +</pre> +<p> +If the rules were inserted successfully, the <code>details</code> parameter +contains an array of inserted rules appearing in the same order as in the passed +<code>rule_list</code> where the optional parameters <code>id</code> and +<code>priority</code> were filled with the generated values. If any rule is +invalid, e.g., because it contained an invalid condition or action, none of the +rules are added and the <a href="extension.html#property-lastError">lastError</a> variable is set when +the callback function is called. Each rule in <code>rule_list</code> must +contain a unique identifier that is not currently used by another rule or an +empty identifier. +</p> +<h3 id="removingrules">Removing rules</h3> +<p> +To remove rules call the <code>removeRules()</code> function. It accepts an +optional array of rule identifiers as its first parameter and a callback +function as its second parameter. +</p> +<pre>var rule_ids = ["id1", "id2", ...]; +function removeRules(rule_ids, function callback() {...}); +</pre> +<p> +If <code>rule_ids</code> is an array of identifiers, all rules having +identifiers listed in the array are removed. If <code>rule_ids</code> lists an +identifier, that is unknown, this identifier is silently ignored. If +<code>rule_ids</code> is <code>undefined</code>, all registered rules of this +extension are removed. The <code>callback()</code> function is called when the +rules were removed. +</p> +<h3 id="retrievingrules">Retrieving rules</h3> +<p> +To retrieve a list of currently registered rules, call the +<code>getRules()</code> function. It accepts an optional array of rule +identifiers with the same semantics as <code>removeRules</code> and a callback +function. +</p><p> +</p><pre>var rule_ids = ["id1", "id2", ...]; +function getRules(rule_ids, function callback(details) {...}); +</pre> +<p> +The <code>details</code> parameter passed to the <code>calback()</code> function +refers to an array of rules including filled optional parameters. +</p> +<!-- END AUTHORED CONTENT --> +</div> + <!-- API PAGE --> + <div class="apiPage"> + <a name="apiReference"></a> + <h2>API reference: chrome.declarative</h2> + <!-- PROPERTIES --> + <!-- /apiGroup --> + <!-- METHODS --> + <div id="methodsTemplate" class="apiGroup"> + <a name="global-methods"></a> + <h3>Methods</h3> + <!-- iterates over all functions --> + <div class="apiItem"> + <a name="method-addRules"></a> <!-- method-anchor --> + <h4>addRules</h4> + <div class="summary"> + <!-- Note: intentionally longer 80 columns --> + <span>chrome.declarative.addRules</span>(<span class="null"><span>array of Rule</span> + <var><span>rules</span></var></span><span class="optional"><span>, </span><span>function</span> + <var><span>callback</span></var></span>)</div> + <div class="description"> + <p>Registers rules to handle events. Note that you cannot call this function as <code>chrome.declarative.addRules(...)</code>. Instead a function of this signature is provided for event objects supporting the declarative API such as <code>chrome.declarativeWebRequest.onRequest</code>.</p> + <!-- PARAMETERS --> + <h4>Parameters</h4> + <dl> + <div> + <div> + <dt> + <var>rules</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span id="typeTemplate"> + <span> + <span> + array of <span><span> + <span> + <a href="declarative.html#type-Rule">Rule</a> + </span> + </span></span> + </span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Rules to be registered. These do not replace previously registered rules.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>callback</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>function</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Called with registered rules.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div> + </dl> + <!-- RETURNS --> + <dl> + </dl> + <!-- CALLBACK --> + <div> + <div> + <h4>Callback function</h4> + <p> + If you specify the <em>callback</em> parameter, it should + specify a function that looks like this: + </p> + <!-- Note: intentionally longer 80 columns --> + <pre>function(<span>array of Rule rules</span>) <span class="subdued">{...}</span>;</pre> + <dl> + <div> + <div> + <dt> + <var>rules</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span id="typeTemplate"> + <span> + <span> + array of <span><span> + <span> + <a href="declarative.html#type-Rule">Rule</a> + </span> + </span></span> + </span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Rules that were registered, the optional parameters are filled with values.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div> + </dl> + </div> + </div> + <!-- MIN_VERSION --> + </div> <!-- /description --> + </div><div class="apiItem"> + <a name="method-getRules"></a> <!-- method-anchor --> + <h4>getRules</h4> + <div class="summary"> + <!-- Note: intentionally longer 80 columns --> + <span>chrome.declarative.getRules</span>(<span class="optional"><span>array of string</span> + <var><span>ruleIdentifiers</span></var></span><span class="null"><span>, </span><span>function</span> + <var><span>callback</span></var></span>)</div> + <div class="description"> + <p>Returns currently registered rules. Note that you cannot call this function as <code>chrome.declarative.getRules(...)</code>. Instead a function of this signature is provided for event objects supporting the declarative API such as <code>chrome.declarativeWebRequest.onRequest</code>.</p> + <!-- PARAMETERS --> + <h4>Parameters</h4> + <dl> + <div> + <div> + <dt> + <var>ruleIdentifiers</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span> + array of <span><span> + <span> + <span>string</span> + </span> + </span></span> + </span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>If an array is passed, only rules with identifiers contained in this array are returned.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>callback</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span id="typeTemplate"> + <span> + <span>function</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Called with registered rules.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div> + </dl> + <!-- RETURNS --> + <dl> + </dl> + <!-- CALLBACK --> + <div> + <div> + <h4>Callback function</h4> + <p> + The callback <em>parameter</em> should specify a function + that looks like this: + </p> + <!-- Note: intentionally longer 80 columns --> + <pre>function(<span>array of Rule rules</span>) <span class="subdued">{...}</span>;</pre> + <dl> + <div> + <div> + <dt> + <var>rules</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span id="typeTemplate"> + <span> + <span> + array of <span><span> + <span> + <a href="declarative.html#type-Rule">Rule</a> + </span> + </span></span> + </span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Rules that were registered, the optional parameters are filled with values.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div> + </dl> + </div> + </div> + <!-- MIN_VERSION --> + </div> <!-- /description --> + </div><div class="apiItem"> + <a name="method-removeRules"></a> <!-- method-anchor --> + <h4>removeRules</h4> + <div class="summary"> + <!-- Note: intentionally longer 80 columns --> + <span>chrome.declarative.removeRules</span>(<span class="optional"><span>array of string</span> + <var><span>ruleIdentifiers</span></var></span><span class="optional"><span>, </span><span>function</span> + <var><span>callback</span></var></span>)</div> + <div class="description"> + <p>Unregisters currently registered rules. Note that you cannot call this function as <code>chrome.declarative.removeRules(...)</code>. Instead a function of this signature is provided for event objects supporting the declarative API such as <code>chrome.declarativeWebRequest.onRequest</code>.</p> + <!-- PARAMETERS --> + <h4>Parameters</h4> + <dl> + <div> + <div> + <dt> + <var>ruleIdentifiers</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span> + array of <span><span> + <span> + <span>string</span> + </span> + </span></span> + </span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>If an array is passed, only rules with identifiers contained in this array are unregistered.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>callback</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>function</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Called when rules were unregistered.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div> + </dl> + <!-- RETURNS --> + <dl> + </dl> + <!-- CALLBACK --> + <div> + <div> + <h4>Callback function</h4> + <p> + If you specify the <em>callback</em> parameter, it should + specify a function that looks like this: + </p> + <!-- Note: intentionally longer 80 columns --> + <pre>function(<span></span>) <span class="subdued">{...}</span>;</pre> + <dl> + </dl> + </div> + </div> + <!-- MIN_VERSION --> + </div> <!-- /description --> + </div> <!-- /apiItem --> + </div> <!-- /apiGroup --> + <!-- EVENTS --> + <!-- /apiGroup --> + <!-- TYPES --> + <div class="apiGroup"> + <a name="types"></a> + <h3 id="types">Types</h3> + <!-- iterates over all types --> + <div class="apiItem"> + <a name="type-Rule"></a> + <h4>Rule</h4> + <div> + <dt> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span id="typeTemplate"> + <span> + <span>object</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Description of a declarative rule for handling events.</dd> + <!-- OBJECT PROPERTIES --> + <dd> + <dl> + <div> + <div> + <dt> + <var>id</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Optional identifier that allows referencing this rule.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>conditions</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span id="typeTemplate"> + <span> + <span> + array of <span><span> + <span> + <span>any</span> + </span> + </span></span> + </span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>List of conditions that can trigger the actions.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>actions</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span id="typeTemplate"> + <span> + <span> + array of <span><span> + <span> + <span>any</span> + </span> + </span></span> + </span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>List of actions that are triggered if one of the condtions is fulfilled.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>priority</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>integer</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Optional priority of this rule. Defaults to 100.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div> + </dl> + </dd> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div class="apiItem"> + <a name="type-UrlFilter"></a> + <h4>UrlFilter</h4> + <div> + <dt> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span id="typeTemplate"> + <span> + <span>object</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Filters URLs for various criteria</dd> + <!-- OBJECT PROPERTIES --> + <dd> + <dl> + <div> + <div> + <dt> + <var>hostContains</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the host name of the URL contains a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>hostEquals</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the host name of the URL is equal to a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>hostPrefix</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the host name of the URL starts with a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>hostSuffix</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the host name of the URL ends with a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>pathContains</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the path segment of the URL contains a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>pathEquals</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the path segment of the URL is equal to a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>pathPrefix</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the path segment of the URL starts with a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>pathSuffix</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the path segment of the URL ends with a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>queryEquals</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the query segment of the URL is equal to a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>queryPrefix</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the query segment of the URL starts with a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>querySuffix</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the query segment of the URL ends with a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>urlSuffix</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the URL ends with a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>urlEquals</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the URL is equal to a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>urlPrefix</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span>string</span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the URL starts with a specified string.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>schemes</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span> + array of <span><span> + <span> + <span>string</span> + </span> + </span></span> + </span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the scheme of the URL is equal to any of the schemes specified in the array.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div><div> + <div> + <dt> + <var>ports</var> + <em> + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <span> + array of <span><span> + <span> + <span>integer or array of integer</span> + </span> + </span></span> + </span> + </span> + </span> + ) + </div> + </em> + </dt> + <dd>Matches if the port of the URL is contained in any of the specified port lists. For example <code>[80, 443, [1000, 1200]]</code> matches all requests on port 80, 443 and in the range 1000-1200.</dd> + <!-- OBJECT PROPERTIES --> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div> + </dl> + </dd> + <!-- OBJECT METHODS --> + <!-- OBJECT EVENT FIELDS --> + <!-- FUNCTION PARAMETERS --> + </div> + </div> <!-- /apiItem --> + </div> <!-- /apiGroup --> + </div> <!-- /apiPage --> + </div> <!-- /gc-pagecontent --> + </div> <!-- /g-section --> + </div> <!-- /codesiteContent --> + <div id="gc-footer" --=""> + <div class="text"> + <p> + Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, + the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons + Attribution 3.0 License</a>, and code samples are licensed under the + <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. + </p> + <p> + ©2011 Google + </p> +<!-- begin analytics --> +<script src="https://www.google-analytics.com/urchin.js" type="text/javascript"></script> +<script src="https://www.google-analytics.com/ga.js" type="text/javascript"></script> +<script type="text/javascript"> + // chrome doc tracking + try { + var engdocs = _gat._getTracker("YT-10763712-2"); + engdocs._trackPageview(); + } catch(err) {} + // code.google.com site-wide tracking + try { + _uacct="UA-18071-1"; + _uanchor=1; + _uff=0; + urchinTracker(); + } + catch(e) {/* urchinTracker not available. */} +</script> +<!-- end analytics --> + </div> + </div> <!-- /gc-footer --> + </div> <!-- /gc-container --> +</body></html> diff --git a/chrome/common/extensions/docs/declarativeWebRequest.html b/chrome/common/extensions/docs/declarativeWebRequest.html index cce38585..f39906d 100644 --- a/chrome/common/extensions/docs/declarativeWebRequest.html +++ b/chrome/common/extensions/docs/declarativeWebRequest.html @@ -191,6 +191,23 @@ <div id="toc"> <h2>Contents</h2> <ol> + <li> + <a href="#notes">Notes</a> + <ol> + </ol> + </li><li> + <a href="#manifest">Manifest</a> + <ol> + </ol> + </li><li> + <a href="#rules">Rules</a> + <ol> + </ol> + </li><li> + <a href="#TODO">Todo</a> + <ol> + </ol> + </li> <li> <a href="#apiReference">API reference: chrome.declarativeWebRequest</a> <ol> @@ -238,7 +255,108 @@ <a href="TODO">Learn more</a>. </p> <!-- STATIC CONTENT PLACEHOLDER --> - <div id="static"></div> + <div id="static"><!-- BEGIN AUTHORED CONTENT --> +<h2 id="notes">Notes</h2> +<p> +Use the <code>chrome.declarativeWebRequest</code> module to intercept, block, or +modify requests in-flight. It is significantly faster than the <a href="webRequest.html"><code>chrome.webRequest</code> API</a> because you can +register rules that are evaluated in the browser rather than the +JavaScript engine which reduces roundtrip latencies and allows for very high +efficiency. +</p> +<h2 id="manifest">Manifest</h2> +<p> +You must declare the "declarative" and the "declarativeWebRequest" permission in +the <a href="manifest.html">extension manifest</a> to use this API, +along with <a href="manifest.html#permissions">host permissions</a> for any +hosts whose network requests you want to access. +</p> +<pre>{ + "name": "My extension", + ... +<b> "permissions": [ + "declarative", + "declarativeWebRequest", + "*://*.google.com" + ]</b>, + ... +}</pre> +<h2 id="rules">Rules</h2> +<p> +The Declarative Web Request API follows the concepts of the <a href="declarative.html">Declarative API</a>. You can register rules to the +<code>chrome.declarativeWebRequest.onRequest</code> event object. +</p> +<p> +The Declarative Web Request API supports a single type of match criteria, the +<code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network +requests if and only if all listed criteria are met. The following +<code>RequestMatcher</code> would match a network request when the user enters +"http://www.example.com" in the URL bar: +</p> +<pre>var matcher = new chrome.declarativeWebRequest.RequestMatcher({ + url: { hostSuffix: 'example.com', schemes: ['http'] }, + resourceType: 'main_frame' + }); +</pre> +<p> +Requests to "https://www.example.com" would be rejected by the +<code>RequestMatcher</code> due to the scheme. Also all requests for an embedded +iframe would be rejected due to the <code>resourceType</code>. +</p> +<p class="note"> +<strong>Note:</strong> All conditions and actions are created via a constructor +as shown in the example above. +</p><p> +</p><p> +In order to cancel all requests to "example.com", you can define a rule as +follows: +</p> +<pre>var rule = { + conditions: [ + new chrome.declarativeWebRequest.RequestMatcher({ + url: { hostSuffix: 'example.com' } }) + ], + actions: [ + new chrome.declarativeWebRequest.CancelRequest() + ]}; +</pre> +<p> +In order to cancel all requests to "example.com" and "foobar.com", you can add a +second condition, as each condition is sufficient to trigger all specified +actions: +</p> +<pre>var rule2 = { + conditions: [ + new chrome.declarativeWebRequest.RequestMatcher({ + url: { hostSuffix: 'example.com' } }), + new chrome.declarativeWebRequest.RequestMatcher({ + url: { hostSuffix: 'foobar.com' } }) + ], + actions: [ + new chrome.declarativeWebRequest.CancelRequest() + ]}; +</pre> +<p> +Register rules as follows: +</p> +<pre>chrome.declarativeWebRequest.onRequest.addRules([rule2]); +</pre> +<p class="note"> +<strong>Note:</strong> You should always register or unregister rules in bulk rather than +individually because each of these operations recreates internal data +structures. This re-creation is computationally expensive but facilitates a +very fast URL matching algorithm for hundreds of thousands of URLs. +</p> +<h2 id="TODO">Todo</h2> +<ul> + <li>Explain precedences, once we can ignore rules based on their priority + (e.g. how can I cancel all requests except for a specific whitelist?) + </li><li>Explain when conditions can be evaluated, when actions can be executed, + and when rules can be executed (e.g. you cannot cancel a request when you + have received the response already) +</li></ul> +<!-- END AUTHORED CONTENT --> +</div> <!-- API PAGE --> <div class="apiPage"> <a name="apiReference"></a> @@ -255,16 +373,54 @@ <div class="apiItem"> <a name="event-onRequest"></a> <h4>onRequest</h4> + <!-- /description --> <div class="summary"> - <!-- Note: intentionally longer 80 columns --> - <span class="subdued">chrome.declarativeWebRequest.</span><span>onRequest</span><span class="subdued">.addListener</span>(function(<span></span>) <span class="subdued">{...}</span><span></span>); + <span class="subdued">chrome.declarativeWebRequest.</span><span>onRequest</span><span class="subdued">.addRules</span>(...); </div> <div class="description"> - <!-- LISTENER PARAMETERS --> - <!-- EXTRA PARAMETERS --> - <!-- LISTENER RETURN VALUE --> - <dl> - </dl> + <p>See <a href="declarative.html#method-addRules"><code>chrome.declarative.addRules()</code></a>. + </p> + <!-- CONDITIONS --> + <div> + <h4>Supported conditions</h4> + <dl> + <div> + <div> + <dt> + <a href="declarativeWebRequest.html#type-RequestMatcher">RequestMatcher</a> + </dt> + <dd class="todo"> + Undocumented. + </dd> + </div> + </div> + </dl> + </div> <!-- /conditions --> + <!-- ACTIONS --> + <div> + <h4>Supported actions</h4> + <dl> + <div> + <div> + <dt> + <a href="declarativeWebRequest.html#type-CancelRequest">CancelRequest</a> + </dt> + <dd class="todo"> + Undocumented. + </dd> + </div> + </div><div> + <div> + <dt> + <a href="declarativeWebRequest.html#type-RedirectRequest">RedirectRequest</a> + </dt> + <dd class="todo"> + Undocumented. + </dd> + </div> + </div> + </dl> + </div> <!-- /actions --> </div> <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> @@ -306,7 +462,7 @@ <span class="optional">optional</span> <span id="typeTemplate"> <span> - <a>UrlFilter</a> + <a href="declarative.html#type-UrlFilter">UrlFilter</a> </span> </span> ) @@ -458,7 +614,7 @@ </div> </em> </dt> - <dd>Declarative event action that redirects a network request. (TODO: add destination)</dd> + <dd>Declarative event action that redirects a network request.</dd> <!-- OBJECT PROPERTIES --> <dd> <dl> diff --git a/chrome/common/extensions/docs/devtools.inspectedWindow.html b/chrome/common/extensions/docs/devtools.inspectedWindow.html index c60d652..d1f6b48 100644 --- a/chrome/common/extensions/docs/devtools.inspectedWindow.html +++ b/chrome/common/extensions/docs/devtools.inspectedWindow.html @@ -785,6 +785,7 @@ You can find more examples that use Developer Tools APIs in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onResourceContentCommitted"></a> <h4>onResourceContentCommitted</h4> @@ -854,6 +855,7 @@ You can find more examples that use Developer Tools APIs in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/devtools.network.html b/chrome/common/extensions/docs/devtools.network.html index afff247..a69c5b4 100644 --- a/chrome/common/extensions/docs/devtools.network.html +++ b/chrome/common/extensions/docs/devtools.network.html @@ -441,6 +441,7 @@ You can find more examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onRequestFinished"></a> <h4>onRequestFinished</h4> @@ -485,6 +486,7 @@ You can find more examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/devtools.panels.html b/chrome/common/extensions/docs/devtools.panels.html index 896e87c..94593a0 100644 --- a/chrome/common/extensions/docs/devtools.panels.html +++ b/chrome/common/extensions/docs/devtools.panels.html @@ -824,6 +824,7 @@ You can find examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> </dd> @@ -996,6 +997,7 @@ You can find examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-ExtensionPanel-onSearch"></a> <h4>onSearch</h4> @@ -1064,6 +1066,7 @@ You can find examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-ExtensionPanel-onShown"></a> <h4>onShown</h4> @@ -1108,6 +1111,7 @@ You can find examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> </dd> @@ -1461,6 +1465,7 @@ You can find examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-ExtensionSidebarPane-onShown"></a> <h4>onShown</h4> @@ -1506,6 +1511,7 @@ You can find examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> </dd> @@ -1655,6 +1661,7 @@ You can find examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> </dd> diff --git a/chrome/common/extensions/docs/experimental.devtools.audits.html b/chrome/common/extensions/docs/experimental.devtools.audits.html index 5e30de0..a0ba71e 100644 --- a/chrome/common/extensions/docs/experimental.devtools.audits.html +++ b/chrome/common/extensions/docs/experimental.devtools.audits.html @@ -526,6 +526,7 @@ You can find more examples that use this API in <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> </dd> diff --git a/chrome/common/extensions/docs/experimental.devtools.console.html b/chrome/common/extensions/docs/experimental.devtools.console.html index 514c6b7..90004e3 100644 --- a/chrome/common/extensions/docs/experimental.devtools.console.html +++ b/chrome/common/extensions/docs/experimental.devtools.console.html @@ -467,6 +467,7 @@ allows an extension to add new messages. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/experimental.fontSettings.html b/chrome/common/extensions/docs/experimental.fontSettings.html index 32e01fd..c1a0c586 100644 --- a/chrome/common/extensions/docs/experimental.fontSettings.html +++ b/chrome/common/extensions/docs/experimental.fontSettings.html @@ -2409,6 +2409,7 @@ directory. For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onDefaultFixedFontSizeChanged"></a> <h4>onDefaultFixedFontSizeChanged</h4> @@ -2506,6 +2507,7 @@ directory. For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onDefaultFontSizeChanged"></a> <h4>onDefaultFontSizeChanged</h4> @@ -2603,6 +2605,7 @@ directory. For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onFontChanged"></a> <h4>onFontChanged</h4> @@ -2749,6 +2752,7 @@ directory. For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onMinimumFontSizeChanged"></a> <h4>onMinimumFontSizeChanged</h4> @@ -2846,6 +2850,7 @@ directory. For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/experimental.keybinding.html b/chrome/common/extensions/docs/experimental.keybinding.html index 5c12c6d..6d820a9 100644 --- a/chrome/common/extensions/docs/experimental.keybinding.html +++ b/chrome/common/extensions/docs/experimental.keybinding.html @@ -351,6 +351,7 @@ code. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/experimental.offscreenTabs.html b/chrome/common/extensions/docs/experimental.offscreenTabs.html index 3920fba..8aa4f25 100644 --- a/chrome/common/extensions/docs/experimental.offscreenTabs.html +++ b/chrome/common/extensions/docs/experimental.offscreenTabs.html @@ -1521,6 +1521,7 @@ <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/experimental.runtime.html b/chrome/common/extensions/docs/experimental.runtime.html index 0dcc761..cf39107 100644 --- a/chrome/common/extensions/docs/experimental.runtime.html +++ b/chrome/common/extensions/docs/experimental.runtime.html @@ -339,6 +339,7 @@ <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onInstalled"></a> <h4>onInstalled</h4> @@ -354,6 +355,7 @@ <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/experimental.speechInput.html b/chrome/common/extensions/docs/experimental.speechInput.html index 3b5cb53..858d820 100644 --- a/chrome/common/extensions/docs/experimental.speechInput.html +++ b/chrome/common/extensions/docs/experimental.speechInput.html @@ -643,6 +643,7 @@ chrome.experimental.speechInput.start({ "language": "en" }, checkStart); <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onResult"></a> <h4>onResult</h4> @@ -687,6 +688,7 @@ chrome.experimental.speechInput.start({ "language": "en" }, checkStart); <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onSoundEnd"></a> <h4>onSoundEnd</h4> @@ -702,6 +704,7 @@ chrome.experimental.speechInput.start({ "language": "en" }, checkStart); <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onSoundStart"></a> <h4>onSoundStart</h4> @@ -717,6 +720,7 @@ chrome.experimental.speechInput.start({ "language": "en" }, checkStart); <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/extension.html b/chrome/common/extensions/docs/extension.html index af9ba77..fbcad44 100644 --- a/chrome/common/extensions/docs/extension.html +++ b/chrome/common/extensions/docs/extension.html @@ -1221,6 +1221,7 @@ For details, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onConnectExternal"></a> <h4>onConnectExternal</h4> @@ -1267,6 +1268,7 @@ For details, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onMessage"></a> <h4>onMessage</h4> @@ -1414,6 +1416,7 @@ For details, see </div> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onMessageExternal"></a> <h4>onMessageExternal</h4> @@ -1561,6 +1564,7 @@ For details, see </div> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/fileBrowserHandler.html b/chrome/common/extensions/docs/fileBrowserHandler.html index 5f271d8..faa460c 100644 --- a/chrome/common/extensions/docs/fileBrowserHandler.html +++ b/chrome/common/extensions/docs/fileBrowserHandler.html @@ -442,6 +442,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/history.html b/chrome/common/extensions/docs/history.html index 56fcbc2..3e280d9 100644 --- a/chrome/common/extensions/docs/history.html +++ b/chrome/common/extensions/docs/history.html @@ -1307,6 +1307,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onVisited"></a> <h4>onVisited</h4> @@ -1353,6 +1354,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/idle.html b/chrome/common/extensions/docs/idle.html index 4ef08fd..61e0804 100644 --- a/chrome/common/extensions/docs/idle.html +++ b/chrome/common/extensions/docs/idle.html @@ -414,6 +414,7 @@ For example: <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/js/api_page_generator.js b/chrome/common/extensions/docs/js/api_page_generator.js index 7f1e028..0a06635 100644 --- a/chrome/common/extensions/docs/js/api_page_generator.js +++ b/chrome/common/extensions/docs/js/api_page_generator.js @@ -30,6 +30,7 @@ var MODULE_SCHEMAS = [ '../api/contextMenus.json', '../api/cookies.json', '../api/debugger.json', + '../api/declarative.json', '../api/declarativeWebRequest.json', '../api/devtools.json', '../api/experimental.accessibility.json', @@ -489,6 +490,22 @@ function getTypeRef(type) { return type['$ref']; } +function getTypeByName(typeName) { + var module = typeModule[typeName] || {}; + for (var type in module.types) { + if (module.types.hasOwnProperty(type) && type.id === typeName) + return type; + } + return undefined; +} + +function getDescription(typeName) { + var type = getTypeByName(typeName); + if (!type) + return undefined; + return type.description; +} + function getEnumValues(enumList, type) { if (type === 'string') { enumList = enumList.map(function(e) { return '"' + e + '"'}); @@ -720,7 +737,7 @@ function getSignatureString(parameters) { if (!parameters) return ''; var retval = []; - parameters.forEach(function(param, i) { + filterDocumented(parameters).forEach(function(param, i) { retval.push(getTypeName(param) + ' ' + param.name); }); @@ -744,5 +761,5 @@ function sortByName(a, b) { } function disableDocs(obj) { - return !!obj.nodoc || !!obj.internal; + return !!obj.nodoc; } diff --git a/chrome/common/extensions/docs/management.html b/chrome/common/extensions/docs/management.html index 5bd861e..65e7e798 100644 --- a/chrome/common/extensions/docs/management.html +++ b/chrome/common/extensions/docs/management.html @@ -1045,6 +1045,7 @@ The one method that doesn't require the "management" permission is <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onEnabled"></a> <h4>onEnabled</h4> @@ -1091,6 +1092,7 @@ The one method that doesn't require the "management" permission is <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onInstalled"></a> <h4>onInstalled</h4> @@ -1137,6 +1139,7 @@ The one method that doesn't require the "management" permission is <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onUninstalled"></a> <h4>onUninstalled</h4> @@ -1181,6 +1184,7 @@ The one method that doesn't require the "management" permission is <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/omnibox.html b/chrome/common/extensions/docs/omnibox.html index d10110a..1afa34b 100644 --- a/chrome/common/extensions/docs/omnibox.html +++ b/chrome/common/extensions/docs/omnibox.html @@ -411,6 +411,7 @@ You can find samples of this API on the <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onInputChanged"></a> <h4>onInputChanged</h4> @@ -517,6 +518,7 @@ You can find samples of this API on the <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onInputEntered"></a> <h4>onInputEntered</h4> @@ -563,6 +565,7 @@ You can find samples of this API on the <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onInputStarted"></a> <h4>onInputStarted</h4> @@ -578,6 +581,7 @@ You can find samples of this API on the <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/pageAction.html b/chrome/common/extensions/docs/pageAction.html index 5bf39be..4bd5254 100644 --- a/chrome/common/extensions/docs/pageAction.html +++ b/chrome/common/extensions/docs/pageAction.html @@ -1101,6 +1101,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/permissions.html b/chrome/common/extensions/docs/permissions.html index 937d95c..3ccfc16 100644 --- a/chrome/common/extensions/docs/permissions.html +++ b/chrome/common/extensions/docs/permissions.html @@ -883,6 +883,7 @@ You can specify any of the following as optional permissions: <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onRemoved"></a> <h4>onRemoved</h4> @@ -927,6 +928,7 @@ You can specify any of the following as optional permissions: <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/proxy.html b/chrome/common/extensions/docs/proxy.html index e0be65c..5eba638 100644 --- a/chrome/common/extensions/docs/proxy.html +++ b/chrome/common/extensions/docs/proxy.html @@ -610,6 +610,7 @@ identical to the <code>value</code> object passed to callback function of <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/samples.html b/chrome/common/extensions/docs/samples.html index 7cc02c6..20e92e5 100644 --- a/chrome/common/extensions/docs/samples.html +++ b/chrome/common/extensions/docs/samples.html @@ -292,6 +292,8 @@ </span><span> <a href="javascript:void(0);" onclick="setFilter('chrome.debugger', this)">chrome.debugger</a><span>, </span> </span><span> + <a href="javascript:void(0);" onclick="setFilter('chrome.declarative', this)">chrome.declarative</a><span>, </span> + </span><span> <a href="javascript:void(0);" onclick="setFilter('chrome.declarativeWebRequest', this)">chrome.declarativeWebRequest</a><span>, </span> </span><span> <a href="javascript:void(0);" onclick="setFilter('chrome.experimental', this)">chrome.experimental</a><span>, </span> diff --git a/chrome/common/extensions/docs/samples.json b/chrome/common/extensions/docs/samples.json index 32ec975..6a25a95 100644 --- a/chrome/common/extensions/docs/samples.json +++ b/chrome/common/extensions/docs/samples.json @@ -66,6 +66,9 @@ "chrome.debugger.onDetach": "debugger.html#event-onDetach", "chrome.debugger.onEvent": "debugger.html#event-onEvent", "chrome.debugger.sendCommand": "debugger.html#method-sendCommand", + "chrome.declarative.addRules": "declarative.html#method-addRules", + "chrome.declarative.getRules": "declarative.html#method-getRules", + "chrome.declarative.removeRules": "declarative.html#method-removeRules", "chrome.declarativeWebRequest.onRequest": "declarativeWebRequest.html#event-onRequest", "chrome.devtools.inspectedWindow.Resource.getContent": "devtools.inspectedWindow.html#method-Resource-getContent", "chrome.devtools.inspectedWindow.Resource.setContent": "devtools.inspectedWindow.html#method-Resource-setContent", diff --git a/chrome/common/extensions/docs/static/declarative.html b/chrome/common/extensions/docs/static/declarative.html new file mode 100644 index 0000000..87bcd42 --- /dev/null +++ b/chrome/common/extensions/docs/static/declarative.html @@ -0,0 +1,140 @@ +<!-- BEGIN AUTHORED CONTENT --> + +<h2 id="notes">Notes</h2> + +<p> +The Declarative API is a framework to define rules consisting of declarative +conditions and actions. Conditions are evaluated in the browser rather than the +JavaScript engine which reduces roundtrip latencies and allows for very high +efficiency. +</p> + +</p>The Declarative API is an abstract foundation for the <a + href="declarativeWebRequest.html">Declarative Web Request API</a> and +possibly further extension APIs in the future. This page describes the +underlying concepts of all Declarative APIs. +</p> + +<h2 id="manifest">Manifest</h2> + +<p> +You must declare the "declarative" permission in your extension's manifest +to use APIs that are based on this API. +</p> + +<pre>{ + "name": "My extension", + ... +<b> "permissions": [ + "declarative", + ]</b>, + ... +}</pre> + +<h2 id="rules">Rules</h2> + +<p>The simplest possible rule consists of one or more conditions and one or more +actions:</p> +<pre> +var rule = { + conditions: [ /* my conditions */ ], + actions: [ /* my actions */ ] +}; +</pre> + +<p>If any of the conditions is fulfilled, all actions are executed.</p> + +<p>In addition to conditions and actions you may give each rule an identifier, +which simplifies unregistering previously registered rules, and a priority to +define precedences among rules. Priorities are only considered if rules conflict +each other or need to be executed in a specific order.</p> + +<pre> +var rule = { + id: "my rule", // optional, will be generated if not set. + priority: 100, // optional, defaults to 100. + conditions: [ /* my conditions */ ], + actions: [ /* my actions */ ] +}; +</pre> + +<h2 id="eventobjects">Event objects</h2> + +<p> +<a href="events.html">Event objects</a> may support rules. These event objects +don't call a callback function when events happer but test whether any +registered rule has at least one fulfilled condition and execute the actions +associated with this rule. Event objects supporting the declarative API have +three relevant methods: <a href="#method-addRules"><code>addRules()</code></a>, +<a href="#method-removeRules"><code>removeRules()</code></a>, and +<a href="#method-getRules"><code>getRules()</code></a>. +</p> + +<h3 id="addingrules">Adding rules</h3> + +<p> +To add rules call the <code>addRules()</code> function of the event object. It +takes an array of rule instances as its first parameter and a callback function +that is called on completion. +</p> + +<pre> +var rule_list = [rule1, rule2, ...]; +function addRules(rule_list, function callback(details) {...}); +</pre> + +<p> +If the rules were inserted successfully, the <code>details</code> parameter +contains an array of inserted rules appearing in the same order as in the passed +<code>rule_list</code> where the optional parameters <code>id</code> and +<code>priority</code> were filled with the generated values. If any rule is +invalid, e.g., because it contained an invalid condition or action, none of the +rules are added and the <a + href="extension.html#property-lastError">lastError</a> variable is set when +the callback function is called. Each rule in <code>rule_list</code> must +contain a unique identifier that is not currently used by another rule or an +empty identifier. +</p> + +<h3 id="removingrules">Removing rules</h3> + +<p> +To remove rules call the <code>removeRules()</code> function. It accepts an +optional array of rule identifiers as its first parameter and a callback +function as its second parameter. +</p> + +<pre> +var rule_ids = ["id1", "id2", ...]; +function removeRules(rule_ids, function callback() {...}); +</pre> + +<p> +If <code>rule_ids</code> is an array of identifiers, all rules having +identifiers listed in the array are removed. If <code>rule_ids</code> lists an +identifier, that is unknown, this identifier is silently ignored. If +<code>rule_ids</code> is <code>undefined</code>, all registered rules of this +extension are removed. The <code>callback()</code> function is called when the +rules were removed. +</p> + +<h3 id="retrievingrules">Retrieving rules</h3> + +<p> +To retrieve a list of currently registered rules, call the +<code>getRules()</code> function. It accepts an optional array of rule +identifiers with the same semantics as <code>removeRules</code> and a callback +function. +<p> + +<pre> +var rule_ids = ["id1", "id2", ...]; +function getRules(rule_ids, function callback(details) {...}); +</pre> + +<p> +The <code>details</code> parameter passed to the <code>calback()</code> function +refers to an array of rules including filled optional parameters. +</p> + +<!-- END AUTHORED CONTENT --> diff --git a/chrome/common/extensions/docs/static/declarativeWebRequest.html b/chrome/common/extensions/docs/static/declarativeWebRequest.html new file mode 100644 index 0000000..5b7f621 --- /dev/null +++ b/chrome/common/extensions/docs/static/declarativeWebRequest.html @@ -0,0 +1,124 @@ +<!-- BEGIN AUTHORED CONTENT --> + +<h2 id="notes">Notes</h2> + +<p> +Use the <code>chrome.declarativeWebRequest</code> module to intercept, block, or +modify requests in-flight. It is significantly faster than the <a + href="webRequest.html"><code>chrome.webRequest</code> API</a> because you can +register rules that are evaluated in the browser rather than the +JavaScript engine which reduces roundtrip latencies and allows for very high +efficiency. +</p> + +<h2 id="manifest">Manifest</h2> + +<p> +You must declare the "declarative" and the "declarativeWebRequest" permission in +the <a href="manifest.html">extension manifest</a> to use this API, +along with <a href="manifest.html#permissions">host permissions</a> for any +hosts whose network requests you want to access. +</p> + +<pre>{ + "name": "My extension", + ... +<b> "permissions": [ + "declarative", + "declarativeWebRequest", + "*://*.google.com" + ]</b>, + ... +}</pre> + +<h2 id="rules">Rules</h2> + +<p> +The Declarative Web Request API follows the concepts of the <a + href="declarative.html">Declarative API</a>. You can register rules to the +<code>chrome.declarativeWebRequest.onRequest</code> event object. +</p> + +<p> +The Declarative Web Request API supports a single type of match criteria, the +<code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network +requests if and only if all listed criteria are met. The following +<code>RequestMatcher</code> would match a network request when the user enters +"http://www.example.com" in the URL bar: +</p> + +<pre> +var matcher = new chrome.declarativeWebRequest.RequestMatcher({ + url: { hostSuffix: 'example.com', schemes: ['http'] }, + resourceType: 'main_frame' + }); +</pre> + +<p> +Requests to "https://www.example.com" would be rejected by the +<code>RequestMatcher</code> due to the scheme. Also all requests for an embedded +iframe would be rejected due to the <code>resourceType</code>. +</p> + +<p class="note"> +<strong>Note:</strong> All conditions and actions are created via a constructor +as shown in the example above. +<p> + +<p> +In order to cancel all requests to "example.com", you can define a rule as +follows: +</p> +<pre> +var rule = { + conditions: [ + new chrome.declarativeWebRequest.RequestMatcher({ + url: { hostSuffix: 'example.com' } }) + ], + actions: [ + new chrome.declarativeWebRequest.CancelRequest() + ]}; +</pre> + +<p> +In order to cancel all requests to "example.com" and "foobar.com", you can add a +second condition, as each condition is sufficient to trigger all specified +actions: +</p> +<pre> +var rule2 = { + conditions: [ + new chrome.declarativeWebRequest.RequestMatcher({ + url: { hostSuffix: 'example.com' } }), + new chrome.declarativeWebRequest.RequestMatcher({ + url: { hostSuffix: 'foobar.com' } }) + ], + actions: [ + new chrome.declarativeWebRequest.CancelRequest() + ]}; +</pre> + +<p> +Register rules as follows: +</p> +<pre> +chrome.declarativeWebRequest.onRequest.addRules([rule2]); +</pre> + +<p class="note"> +<strong>Note:</strong> You should always register or unregister rules in bulk rather than +individually because each of these operations recreates internal data +structures. This re-creation is computationally expensive but facilitates a +very fast URL matching algorithm for hundreds of thousands of URLs. +</p> + +<h2 id="TODO">Todo</h2> +<ul> + <li>Explain precedences, once we can ignore rules based on their priority + (e.g. how can I cancel all requests except for a specific whitelist?) + <li>Explain when conditions can be evaluated, when actions can be executed, + and when rules can be executed (e.g. you cannot cancel a request when you + have received the response already) +</ul> + +<!-- END AUTHORED CONTENT --> diff --git a/chrome/common/extensions/docs/static/samples.html b/chrome/common/extensions/docs/static/samples.html index 2cd56a3..3175916 100644 --- a/chrome/common/extensions/docs/static/samples.html +++ b/chrome/common/extensions/docs/static/samples.html @@ -15,7 +15,6 @@ pageData.api_modules = []; schema.forEach(function(mod) { if (mod.nodoc || - mod.internal || mod.namespace.indexOf('experimental') != -1) { return; } diff --git a/chrome/common/extensions/docs/storage.html b/chrome/common/extensions/docs/storage.html index 9b300f6..35f554e 100644 --- a/chrome/common/extensions/docs/storage.html +++ b/chrome/common/extensions/docs/storage.html @@ -661,6 +661,7 @@ You can find examples that use this API on the <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/tabs.html b/chrome/common/extensions/docs/tabs.html index 5a67109..014798f 100644 --- a/chrome/common/extensions/docs/tabs.html +++ b/chrome/common/extensions/docs/tabs.html @@ -3106,6 +3106,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onAttached"></a> <h4>onAttached</h4> @@ -3232,6 +3233,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onCreated"></a> <h4>onCreated</h4> @@ -3276,6 +3278,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onDetached"></a> <h4>onDetached</h4> @@ -3402,6 +3405,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onHighlighted"></a> <h4>onHighlighted</h4> @@ -3505,6 +3509,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onMoved"></a> <h4>onMoved</h4> @@ -3656,6 +3661,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onRemoved"></a> <h4>onRemoved</h4> @@ -3755,6 +3761,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onUpdated"></a> <h4>onUpdated</h4> @@ -3924,6 +3931,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/template/api_template.html b/chrome/common/extensions/docs/template/api_template.html index 60ac931..445c480 100644 --- a/chrome/common/extensions/docs/template/api_template.html +++ b/chrome/common/extensions/docs/template/api_template.html @@ -103,6 +103,20 @@ </div> <!-- /VALUE --> + <div id="conditionAndActionTemplate"> + <dt> + <a jsvalues=".href: typeModule[$this].namespace + '.html#type-' + $this" + jscontent="$this">condition name</a> + </dt> + <dd class="todo" jsdisplay="!typeModule[$this].description"> + Undocumented. + </dd> + <dd jsdisplay="getDescription($this)" + jsvalues=".innerHTML:substituteTypeRefs(getDescription($this))"> + Description of this parameter from the json schema. + </dd> + </div> + <div id="functionParametersTemplate" jsdisplay="$this.parameters.length > 0"> <h5>Parameters</h5> <dl> @@ -400,7 +414,7 @@ <div class="summary"><span jsdisplay="returns" jscontent="getTypeName(returns)">void</span> <!-- Note: intentionally longer 80 columns --> - <span jscontent="getFullyQualifiedFunctionName($scope, $this)">chrome.module.methodName</span>(<span jsselect="parameters" jsvalues="class:optional ? 'optional' : ''"><span jsdisplay="$index">, </span><span jscontent="getTypeName($this)"></span> + <span jscontent="getFullyQualifiedFunctionName($scope, $this)">chrome.module.methodName</span>(<span jsselect="filterDocumented(parameters)" jsvalues="class:optional ? 'optional' : ''"><span jsdisplay="$index">, </span><span jscontent="getTypeName($this)"></span> <var><span jscontent="$this.name"></span></var></span>)</div> <div class="description"> @@ -410,9 +424,9 @@ </p> <!-- PARAMETERS --> - <h4 jsdisplay="$this.parameters && $this.parameters.length > 0">Parameters</h4> + <h4 jsdisplay="$this.parameters && filterDocumented($this.parameters).length > 0">Parameters</h4> <dl> - <div jsselect="parameters"> + <div jsselect="filterDocumented(parameters)"> <div transclude="valueTemplate"> </div> </div> @@ -474,12 +488,12 @@ <a jsvalues=".name:getAnchorName('event', name, $scope)"></a> <h4 jscontent="name">event name</h4> - <div class="summary"> + <div class="summary" jsdisplay="!($this.options && $this.options.supportsListeners === false)"> <!-- Note: intentionally longer 80 columns --> <span jscontent="(getObjectName($scope) || getModuleName()) + '.'" class="subdued">chrome.bookmarks</span><span jscontent="name">onEvent</span><span class="subdued">.addListener</span>(function(<span jscontent="getSignatureString($this.parameters)">Type param1, Type param2</span>) <span class="subdued">{...}</span><span jscontent="getOptionalSignatureSubstring($this.extraParameters)">, Type opt_param1, Type opt_param2</span>); </div> - <div class="description"> + <div class="description" jsdisplay="!($this.options && $this.options.supportsListeners === false)"> <p class="todo" jsdisplay="!description">Undocumented.</p> <p jsdisplay="description" jsvalues=".innerHTML:description"> A description from the json schema def of the event goes here. @@ -517,6 +531,43 @@ </dl> </div> <!-- /description --> + + <div class="summary" jsdisplay="$this.options && $this.options.supportsRules === true"> + <span jscontent="(getObjectName($scope) || getModuleName()) + '.'" class="subdued">chrome.bookmarks</span><span jscontent="name">onEvent</span><span class="subdued">.addRules</span>(...); + </div> + + <div class="description" jsdisplay="$this.options && $this.options.supportsRules === true"> + <p class="todo" jsdisplay="!description">Undocumented.</p> + <p jsdisplay="description" jsvalues=".innerHTML:description"> + A description from the json schema def of the event goes here. + </p> + + <p>See <a href="declarative.html#method-addRules"><code>chrome.declarative.addRules()</code></a>. + </p> + + <!-- CONDITIONS --> + <div jsdisplay="options && options.conditions && options.conditions.length > 0"> + <h4>Supported conditions</h4> + <dl> + <div jsselect="options.conditions"> + <div transclude="conditionAndActionTemplate"> + </div> + </div> + </dl> + </div> <!-- /conditions --> + + <!-- ACTIONS --> + <div jsdisplay="options && options.actions && options.actions.length > 0"> + <h4>Supported actions</h4> + <dl> + <div jsselect="options.actions"> + <div transclude="conditionAndActionTemplate"> + </div> + </div> + </dl> + </div> <!-- /actions --> + </div> <!-- /description --> + </div> <!-- /apiItem --> </div> <!-- /apiGroup --> diff --git a/chrome/common/extensions/docs/ttsEngine.html b/chrome/common/extensions/docs/ttsEngine.html index b1bf42c..95ed74c 100644 --- a/chrome/common/extensions/docs/ttsEngine.html +++ b/chrome/common/extensions/docs/ttsEngine.html @@ -637,6 +637,7 @@ dynamically decide whether to handle it.</p> <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onStop"></a> <h4>onStop</h4> @@ -652,6 +653,7 @@ dynamically decide whether to handle it.</p> <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/types.html b/chrome/common/extensions/docs/types.html index b1993d4..be59c32 100644 --- a/chrome/common/extensions/docs/types.html +++ b/chrome/common/extensions/docs/types.html @@ -961,6 +961,7 @@ considering the precedence rules. It is used by Chrome. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> </dd> diff --git a/chrome/common/extensions/docs/webNavigation.html b/chrome/common/extensions/docs/webNavigation.html index af79ed2..a850253 100644 --- a/chrome/common/extensions/docs/webNavigation.html +++ b/chrome/common/extensions/docs/webNavigation.html @@ -917,6 +917,7 @@ unexpected results. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onCommitted"></a> <h4>onCommitted</h4> @@ -1117,6 +1118,7 @@ unexpected results. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onCompleted"></a> <h4>onCompleted</h4> @@ -1262,6 +1264,7 @@ unexpected results. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onCreatedNavigationTarget"></a> <h4>onCreatedNavigationTarget</h4> @@ -1428,6 +1431,7 @@ unexpected results. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onDOMContentLoaded"></a> <h4>onDOMContentLoaded</h4> @@ -1573,6 +1577,7 @@ unexpected results. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onErrorOccurred"></a> <h4>onErrorOccurred</h4> @@ -1741,6 +1746,7 @@ unexpected results. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onReferenceFragmentUpdated"></a> <h4>onReferenceFragmentUpdated</h4> @@ -1941,6 +1947,7 @@ unexpected results. <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/webRequest.html b/chrome/common/extensions/docs/webRequest.html index 45a0852..3f4b7eb 100644 --- a/chrome/common/extensions/docs/webRequest.html +++ b/chrome/common/extensions/docs/webRequest.html @@ -1148,6 +1148,7 @@ samples</a>.</p> </div> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onBeforeRedirect"></a> <h4>onBeforeRedirect</h4> @@ -1588,6 +1589,7 @@ samples</a>.</p> <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onBeforeRequest"></a> <h4>onBeforeRequest</h4> @@ -1912,6 +1914,7 @@ samples</a>.</p> </div> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onBeforeSendHeaders"></a> <h4>onBeforeSendHeaders</h4> @@ -2260,6 +2263,7 @@ samples</a>.</p> </div> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onCompleted"></a> <h4>onCompleted</h4> @@ -2677,6 +2681,7 @@ samples</a>.</p> <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onErrorOccurred"></a> <h4>onErrorOccurred</h4> @@ -3015,6 +3020,7 @@ samples</a>.</p> <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onHeadersReceived"></a> <h4>onHeadersReceived</h4> @@ -3387,6 +3393,7 @@ samples</a>.</p> </div> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onResponseStarted"></a> <h4>onResponseStarted</h4> @@ -3804,6 +3811,7 @@ samples</a>.</p> <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onSendHeaders"></a> <h4>onSendHeaders</h4> @@ -4127,6 +4135,7 @@ samples</a>.</p> <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> diff --git a/chrome/common/extensions/docs/windows.html b/chrome/common/extensions/docs/windows.html index 4ec0213..48ce56c 100644 --- a/chrome/common/extensions/docs/windows.html +++ b/chrome/common/extensions/docs/windows.html @@ -1771,6 +1771,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onFocusChanged"></a> <h4>onFocusChanged</h4> @@ -1815,6 +1816,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div><div class="apiItem"> <a name="event-onRemoved"></a> <h4>onRemoved</h4> @@ -1859,6 +1861,7 @@ For other examples and for help in viewing the source code, see <dl> </dl> </div> <!-- /description --> + <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> |