diff options
Diffstat (limited to 'chromium/docs/website/site/developers/design-documents/extensions')
76 files changed, 0 insertions, 10012 deletions
diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/accessibility/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/accessibility/index.md deleted file mode 100644 index ec12f0c623b..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/accessibility/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/how-the-extension-system-works - - How the Extension System Works -page_name: accessibility -title: Accessibility ---- - -**[TOC]** - -**### Keyboard navigation** - -**Fundamental to keyboard-only and screen reader users is navigational access -and interaction using the keyboard alone. This includes means to set keyboard -focus to toolstrips and Omnibox icons for background page functionality, as well -as any popups, dialogs or other UI elements the extensions might generate. Also -required is a way to discern and trigger any associated behavior/action -connected to these UI elements.** - -**Setting keyboard focus to a toolstrip could be provided either through a -keyboard shortcut (much like we have for the -[toolbar](/user-experience/toolbar)), or by unifying access to all of our -toolbars ([toolbar](/user-experience/toolbar), -[infobars](/developers/design-documents/info-bars), -[bookmarks](/user-experience/bookmarks), extensions) by a single shortcut and a -way to circle through them. The first approach is simpler, but the second has -more long-term merit, avoiding discoverability issues with multiple keyboard -shortcuts.** - -**Once focus is on the toolstrip, arrow keys should be used to traverse between -toolstrip buttons, and Space/Enter keys to activate them.** - -**### Screen reader support** - -**The first piece for supporting screen readers is provided by enabling full -keyboard access (including focus tracking) to the UI. Secondly, correct -information needs to be exposed through the platform-specific accessibility -interface ([MSAA](http://msdn.microsoft.com/en-us/library/ms971310.aspx) on -Windows). Providing this information for toolstrips themselves is almost landed -(<http://codereview.chromium.org/155446>), and the next step will be to provide -coverage for the toolstrip buttons.** - -**The real challenge here will be to appropriately give access to the -information otherwise connected to the toolstrip buttons (e.g. the slideout with -builder status), as well as interactive Omnibox icons.** - -**### Low vision** - -**The Extensions toolstrip already respects OS font resizing (on Windows: -Control Panel > Display > Appearance tab, and choose 'Extra Large Fonts'). -Theming (as below with High Contrast) will help for users with contrast -issues.** - -**### High contrast** - -**All of the extensions UI should respect the theming imposed by the [High -Contrast -mode](http://www.microsoft.com/windowsxp/using/accessibility/highcontrast.mspx). -Support for this is being developed this quarter (Q3) by Stephen White, and -should cover Extensions as well.** - -**### Developer documentation** - -Anyone developing an extension should be aware of accessibility best practices -for the parts not covered by Chrome browser accessibility. Included in this are -things such as HTML files and JS content (including dynamically generated HTML). - -Developer documentation pages should be built along accepted guidelines and best -practices for accessible static HTML, where appropriate.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/api-pattern-design-doc/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/api-pattern-design-doc/index.md deleted file mode 100644 index d596939e57f..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/api-pattern-design-doc/index.md +++ /dev/null @@ -1,346 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/how-the-extension-system-works - - How the Extension System Works -page_name: api-pattern-design-doc -title: APIs as stateless service calls ---- - -**Note:** This is the original proposal and is kept for historical reasons. It -may be made obsolete by more recent documentation. - ---- - -We want to give extensions programmatic APIs to interact with many of the -browsers' subsystems. Some examples include: tabs, history, bookmarks, -downloads, and the omnibar. - -An interesting wrinkle in Chrome is that in reality, these data structures exist -in another process. Because of this, it's impossible to keep a perfectly -consistent view of the world in the extension process. There will at time be -conflicts between what the extension thinks the current state of the system is, -and what it actually is. We need to design APIs that makes this fundamental -problem as easy to deal with as possible. - -## Proposal - -We could model these APIs as stateless service calls, similar to the way AJAX -applications work. Each call will be asynchronous, and just dumb data gets -passed back and forth across the void. - -For example: - -window.onload = populate; - -function populate() { - -extension.bookmarks.getAllBookmarks(function(results) { - -// Assuming something MochiKit-ish is present. - -forEach(results, function(bookmark) { - -var div = DIV(A(bookmark.title, bookmark.url), " ", A("edit")); - -div.id = "b" + result.id; - -div.lastChild.onclick = bind(edit, result.id); - -return div; - -}); - -}); - -} - -function edit(id) { - -var newTitle = prompt("Enter new title"); - -extension.bookmarks.updateBookmark({id: id, title: newTitle}); - -} - -The advantages of this approach: - -* Chrome doesn't have to send copies of browser state to any extension - process until it is requested. -* Chrome doesn't have to have complex machinery to keep multiple - copies of browser state synchronized across processes. -* The API reflects the underlying reality -- that the interaction with - the browser is asynchronous. -* Fits a wide variety of applications, so many APIs can follow a - similar pattern, making new APIs easier for chrome-team to build and - easier for developers to learn. -* This feels like idiomatic JavaScript. - -The disadvantages: - -* Not object-oriented. The verbs are at the top level and accept nouns - as arguments. This could get ugly in cases where a subsystem has - many nouns. -* More coupled to JavaScript (bad if we ever wanted to make these APIs - available to other languages). -* May encourage us to be lazy with API design by trying to wedge - everything into this CRUD idiom. - -## Details - -#### Conflicts - -Without cross-process locking, conflicts can occur in any of our APIs. For -example, you can attempt to navigate a tab that has since been closed. My -feeling is that conflicts should \*not\* be treated as exceptions. For simple -things, we should just let the last change win. For more complex cases that make -no sense, we should print a warning to the console, but not treat it as a -fully-fledged error. In the limit, there is nothing the developer can really do -about these cases. We can propagate the real state back to the extension via -events and the extension can do something about it if it wants (I think in most -cases, it won't care). - -#### Constraints - -Many of these data models have constraints and side-effects. For example, it -doesn't make sense to set a window's zIndex negative, and changing the index of -a tab affects the index of other tabs in the same window. Constraints and -side-effects in this system would typically be handled by the server side and -propagated back to the client by events, if the extension developer had -registered to receive them. - -#### Non-data APIs - -Some APIs don't fit this model. For example, interacting with the omnibar or -receiving requests from content scripts. We'd just have to handle these on a -case-by-cases basis. I've outlined some ideas below. - -## Alternative Ideas - -The main alternative is to have a stateful DOM-style API, like this: - -foreach(window.extensions.bookmarks, function(bookmark) { - -var div = DIV(A(bookmark.title, bookmark.url), " ", A("edit")); - -div.id = "b" + result.id; - -div.lastChild.onclick = bind(edit, bookmark); - -return div; - -}); - -function edit(bookmark) { - -var newTitle = prompt("Enter new title"); - -bookmark.title = newTitle; - -bookmark.save(); - -} - -The main downside of this approach is that it requires synchronizing the state -of the relevant object models between the extension and browser processes, and -resolving conflicts. Also, as in my example here, we still might want to have an -explicit update step if the operation would require writing to disk in the -browser process. - -## API Hierarchy Proposal - -chromium. - -// An event is a way to register to be notified when something happens. In the -rest of this - -// documentation, Events are referred to as first-class, with the following -notation: - -// - -// event name(Arg1Type arg1, Arg2Type arg2, ...); - -// - -// What this means is that the Event in variable "name" wants handlers with the -signature: - -// - -// void handler(Arg1Type arg1, Arg2Type arg2, ...) - -class Event - -void addListener(object callback(...)) - -void removeListener(object callback(...)) - -bool hasListener(object callback(...)) - -// Dispatches the event. Mainly this would be used by the framework, but it -might be useful - -// to expose to developers. - -void dispatch(...) - -// A class that is essentially a client to an extension "server" process. -Provides ways to - -// interact with the extension server, usually from a content script, but -theoretically from - -// content or another extension. - -class Extension - -constructor(int id) - -Port connect() - -string getURL(string path) - -// One end of a connection between an extension process and a content script (or -content, or - -// another extension). - -class Port - -event onmessage - -void postMessage(object args) // args is any json-compatible type - -[browser.](/system/errors/NodeNotFound) - -[downloads.](/developers/design-documents/extensions/proposed-changes/apis-under-development/downloads-api) - -[bookmarks.](/system/errors/NodeNotFound) - -[history.](/developers/design-documents/extensions/proposed-changes/apis-under-development/history-api) - -// TODO: - -thumbnails. - -// I think these all fit the basic CRUD pattern. - -[omnibox.](/developers/design-documents/extensions/proposed-changes/apis-under-development/omnibox-api) - -// This one should be really fun to figure out. - -// The "self" module is defined differently depending on whether you are inside -a content - -// script or not. - -// When in an extension, 'self' is a module, just like 'tabs', 'history', etc, -that - -// provides access to some meta features. - -self. - -// For access to other parts of an extension. - -DOMWindow background // Gets the single background process if there is one - -DOMWindow\[\] toolstrips // Gets a list of live toolstrip instances - -// Fired when somebody first creates a channel to this extension - -Event onconnect(Port port) - -// When in a content script, 'self' is an Extension instance referring to the -parent - -// extension. Content scripts can use this to talk to their parent without -having to - -// know its ID, which should be handy during development. - -Extension self - -## Examples - -Move all google tabs into a new window: - -chromium.tabs.getAllTabs(function(tabs) { - -var tabsToMove = \[\]; - -tabs.forEach(function(tab) { - -// Too bad the URL isn't a parsed representation :( - -if (tab.url.indexOf("google.com")) { - -tabsToMove.push(tab); - -} - -} - -if (tabsToMove.length > 0) { - -chromium.tabs.createWindow(null, function(newWindow) { - -tabsToMove.forEach(function(tab) { - -chromium.tabs.updateTab({ - -id: tab.id, - -windowId: newWindow.id - -}); - -}); - -}); - -} - -}); - -Write out navigation entries to console: - -chromium.tabs.ontabchange.addListener(function(old, new) { - -if (old.url != new.url) { - -console.log("navigated to: " + newTab.url); - -} - -}); - -Communication between content scripts and extension: - -// Content script - -var port = chromium.self.connect(); - -port.onmessage.addListener(function(message) { - -console.log("got message: " + message); - -}); - -port.postMessage({pageUrl: location.href}); - -// Extension - -chromium.self.onconnect.addListener(function(port) { - -console.log("received message from: " + port.pageUrl); - -port.postMessage("ack"); - -});
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-lg.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-lg.png.sha1 deleted file mode 100644 index c1df4894529..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-lg.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -23bb28f778364279328ecc48e2c5cf7db71836c1
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-sm.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-sm.png.sha1 deleted file mode 100644 index eea5a59d217..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-sm.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -9c302f2c4fd38756d3eb75a36e057876ae9a7ea4
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-sm2.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-sm2.png.sha1 deleted file mode 100644 index eea5a59d217..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-sm2.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -9c302f2c4fd38756d3eb75a36e057876ae9a7ea4
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark.crx.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark.crx.sha1 deleted file mode 100644 index fd46d70bb57..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark.crx.sha1 +++ /dev/null @@ -1 +0,0 @@ -4b5a5e85ba7294cfe5ed655c23dcf2758677cfd4
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/index.md deleted file mode 100644 index 7aa983b70c9..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/index.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/how-the-extension-system-works - - How the Extension System Works -page_name: chrome-benchmarking-extension -title: Benchmarking Extension ---- - -The Chromium Benchmarking Extension is a quick-and-dirty way to test page load -time performance within Chrome. - -### Features - -* Can clear the cache between each page load -* Can clear existing connections between each page load -* Works with both SPDY and HTTP -* Measures time-to-first-paint, overall page load time KB - read/written, and several other metrics -* Can compare performance between SPDY and HTTP - -### Requirements - -* Chrome version 7 or later -* Command-line flag "--enable-benchmarking" should be used to start - chrome - -### Screenshot - -> ### [<img alt="image" -> src="/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-sm2.png">](/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-sm2.png) - -> ### [(Click to -> enlarge)](/developers/design-documents/extensions/how-the-extension-system-works/chrome-benchmarking-extension/benchmark-lg.png) - -### Instructions - -> **Option 1: Use the benchmark from the chromium source code** - -> The benchmark is part of the chromium source code. You'll find it here: - -> <path-to-chrome-tree>\\src\\chrome\\common\\extensions\\docs\\examples\\extensions\\benchmark - -> To run Chrome with the benchmark, use the following command line: -> chrome.exe --enable-benchmarking -> --load-extension=<path-to-chrome-tree>\\src\\chrome\\common\\extensions\\docs\\examples\\extensions\\benchmark -> **Option 2: Install from Chrome Extension Gallery** -> Install the extension from Chrome Extension Gallery following [this -> link](https://chrome.google.com/extensions/detail/channimfdomahekjcahlbpccbgaopjll). -> Then you'll need to restart the browser to use it. -> When you run chrome, use: -> chrome.exe --enable-benchmarking -> As of M34, the method that seems to work is to load the source code as an -> unpacked extension after enabling developer mode and use the flag -> --enable-net-benchmarking in addition to --enable-benchmarking - -Options - -> * Iterations: How many times the test page should be loaded to - collect performance date. -> * Clear Results: Clear result table. -> * Clear connectons: Reset the internal socket pool, oherwise chrome - will reuse the socket connections if possible. -> * Clear cache: Reset the cache, otherwise chrome could load the page - from cache if possible. -> * Enable Spdy: Use spdy to load a page. When enabled, if the web - server does not support spdy, an error is reported and test will - stop. -> * URL to load: A comma separated list of urls to collect performance - date. Note, the urls listed here should be the final url. E.g.: if - url1 will be redirect to url2, url2 should be used. Otherwise, an - error will be reported and test will stop. You can use "Load URLs - From File" to load the comma separated url list from file if your - test set is large.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/default-apps/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/default-apps/index.md deleted file mode 100644 index 167c3ad52dc..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/default-apps/index.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/how-the-extension-system-works - - How the Extension System Works -page_name: default-apps -title: Default Apps ---- - -Branded Chrome builds ship with a few default apps (Gmail, YouTube, etc.) that -are installed for new users. Default apps are implemented using a variant of the -[external -extensions](http://code.google.com/chrome/extensions/external_extensions.html) -mechanism. - -**Adding a new default app** - -1. Locate the app in the Chrome Web Store -2. Select the "Debug" tab -3. Save its .crx using the "CRX Package Download: Published version" - link -4. Copy the .crx to - [src/chrome/browser/resources/default_apps](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/browser/resources/default_apps/). -5. Add it to - [external_extensions.json](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/browser/resources/default_apps/external_extensions.json?view=markup) - and - [common.gypi](http://src.chromium.org/viewvc/chrome/trunk/src/build/common.gypi?view=markup) - (look for default_apps_list and default_apps_list_linux_dest) - -Testing your changes by making a branded build is tedious. Instead you can -manually copy the default apps directory in your build output, e.g.: - -$ cp -r chrome/browser/resources/default_apps out/Debug/ - -Then you can start chrome with out/Debug/chrome ---user-data-dir=/tmp/<somenewdir> to simulate the new user experience. - -For an example, see [the -changelist](https://chromiumcodereview.appspot.com/10535133) that added Google -Docs as a default app.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served/ExtSourceServer.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served/ExtSourceServer.png.sha1 deleted file mode 100644 index 86b89dacf05..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served/ExtSourceServer.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -949171695de9ea9f6ef2b0aa281553839845e75e
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served/extension-doc-server.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served/extension-doc-server.png.sha1 deleted file mode 100644 index d83da27adba..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served/extension-doc-server.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -5b853fc4fb8b2c0f9c34f31372d3a13dfdf5daa6
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served/index.md deleted file mode 100644 index cd036ae7cbd..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served/index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/how-the-extension-system-works - - How the Extension System Works -- - /developers/design-documents/extensions/how-the-extension-system-works/docs - - Extension Documentation System -page_name: how-docs-are-served -title: How Extension Docs Are Served ---- - -The documentation for Chrome extensions and apps is served at -[developer.chrome.com/extensions](https://developer.chrome.com/extensions) and -[developer.chrome.com/apps](https://developer.chrome.com/apps) by Google App -Engine. - -See -<https://cs.>[chromium.org/chrome/common/extensions/docs/README](http://chromium.org/chrome/common/extensions/docs/README) -to learn how the extension/app docs are generated. - -## Contributing documentation - -Have you found an error in the documentation? Either submit a patch (see below) -or file a bug with label `Cr-Platform-Extensions` at the [the issue -tracker](https://code.google.com/p/chromium/issues/list). - -1. Check out Chromium's source code, see [Get the Code: Checkout, - Build, Run & Submit](/developers/how-tos/get-the-code) (`gclient - runhooks` is optional for this purpose). -2. Find the relevant file that you need to edit (e.g. by visiting - [cs.chromium.org](http://cs.chromium.org) and pasting a quoted - snippet from the page that you want to edit). -3. To view the documentation locally, run - `src/chrome/common/extensions/docs/server2/preview.py` (this will - serve the documentation at http://localhost:8888, add `-p [port]` to - serve on a different port). -4. After updating the documentation, upload the patch to - codereview.chromium.org (see also: [Contributing - Code](/developers/contributing-code)). -5. Others can preview your changes by visiting - `https://chrome-apps-doc.appspot.com/_patch/*[issue - id]*/extensions/` (or /apps/).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-to-update-the-release-notes/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-to-update-the-release-notes/index.md deleted file mode 100644 index afc4dfe7ec3..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/how-to-update-the-release-notes/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/how-the-extension-system-works - - How the Extension System Works -- - /developers/design-documents/extensions/how-the-extension-system-works/docs - - Extension Documentation System -page_name: how-to-update-the-release-notes -title: Updating the Release Notes ---- - -This page has some tips on figuring out what's changed between two releases. -I've used this technique to update the [What's -New](http://code.google.com/chrome/extensions/whats_new.html) page in the -extensions doc, but the technique is more generally useful. - -To see what's changed between two releases (e.g. M9 and M10): - -1. Go to <https://omahaproxy.appspot.com/viewer>, and get the current - versions of the two releases. E.g.: - 1. M9 (win stable): 9.0.597.107 - 2. M10 (win beta): 10.0.648.119 -2. Go to <https://omahaproxy.appspot.com/changelog>, enter the versions - in the fields, and click **Get SVN logs**. E.g.: - 1. Old Version: 9.0.597.107 - 2. New Version: 10.0.648.119 - 3. <click!> - You'll see a big page of revisions, with a revision range (e.g. - 67679:72316). - 4. Search for interesting strings in this page, and open relevant - links to check whether they're worth talking about. - **Note:** This tells you the differences between these branches at the - time the branches were created. If you substitute 1 for the last tuple - of each version #, you get exactly the same information. -3. Do #2 again, but this time change the old version to be the same as - the new version, but with a 1 as the last tuple. E.g.: - 1. Old Version: 10.0.648.1 - 2. New Version: 10.0.648.119 - 3. <click!> - You'll see another page of revisions with a different (higher) revision - range (e.g. 72323:75907). - 4. Search for interesting strings in this page. -4. Once you have a list of probable changes, make sure they weren't - merged into the previous release. One way to do this is to do #3 - again, using the previous release's numbers. E.g.: - 1. Old Version: 9.0.597.1 - 2. New Version: 9.0.597.107 - 3. <click!> - 4. Search for the revision #s you found interesting in steps 2 & 3. - If you find something that *was* backported, make sure it's in - the release notes for the old release (if it's worthy). - -The most useful strings strings to search for (for extensions/apps release -notes): - -* src/chrome/common/extensions/ -* content script -* theme \[haven't done this in the past, but we really should\] - -I used to also/instead search for these: - -* extension_api.json -* permission -* manifest -* extensions/docs -* packaged app -* hosted app -* apps -* theme -* extension - -Don't bother searching for "api".
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/index.md deleted file mode 100644 index 341e395cda1..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/docs/index.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/how-the-extension-system-works - - How the Extension System Works -page_name: docs -title: Extension Documentation System ---- - -[TOC] - -If you're interested in contributing to the developer docs for extensions (or -you're just curious how it works), you've found the right place. - -## How you can contribute to the doc - -You can help improve the extension docs for Google Chrome in a couple of ways: - -* [File a bug](http://crbug.com/) about each doc - mistake/omission/improvement - * If possible, tell us the exact text you'd like to see -* Fix the doc yourself - * See [Contributing - Code](http://www.chromium.org/developers/contributing-code) for - general rules - * Note that pages could take months to show up in the default doc. - To get around this, someone needs to merge your changes into the - various branches. - -## Overview of the doc system - -Although the doc appears to be on code.google.com, it isn't. It's really in the -Chromium project and served up by an AppEngine app. To modify the doc, you need -to build it. - -For details on where doc content comes from (from the server's point of view), -see [How Extension Docs Are -Served](/developers/design-documents/extensions/how-the-extension-system-works/docs/how-docs-are-served).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/extension-manifesto/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/extension-manifesto/index.md deleted file mode 100644 index e5cf1a589ac..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/extension-manifesto/index.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/how-the-extension-system-works - - How the Extension System Works -page_name: extension-manifesto -title: Extensions Manifesto ---- - -### Problem statement - -Chromium can't be everything to all people. People use web browsers in a variety -of environments and for a wide variety of jobs. Personal tastes and needs vary -widely from one user to the next. The feature needs of one person often conflict -directly with those of another. Further, one of the design goals of Chromium is -to have a minimal light-weight user interface, which itself conflicts with -adding lots of features. - -User-created extensions have been proposed to solve these problems: - -* The addition of features that have specific or limited appeal ("that - would be great as an extension"). -* Users coming from other browsers who are used to certain extensions - that they can't live without. -* Bundling partners who would like to add features to Chromium - specific to their bundle. - -### Goals - -An extension system for Chromium should be: - -* Webby - * Developing and using extensions should be very similar to - developing and using web pages. - * We should reuse the web platform wherever possible instead of - creating new proprietary APIs. - * Web developers should be able to easily create Chromium - extensions. - * Installing and using an extension should feel lightweight and - simple, like using a web app. -* Rich - * It should be possible to create extensions as polished as if - they had been developed by the Chromium team. - * Eventually, it should be possible to implement major chunks of - Chromium itself as extensions. -* General - * There should be only one extension system in Chromium that - handles all types of extensibility. - * Infrastructure like autoupdate, packaging, and security should - be shared. - * Even traditional NPAPI plugins should be deployable as - extensions. -* Maintainable - * The system should require low ongoing maintenance from the - Chromium team, and minimize potential for forward compatibility - issues. - * We should not need to disable deployed extensions when we - release new versions of Chromium. -* Stable - * Extensions should not be able to crash or hang the browser - process. - * Chromium should assign blame to extensions that are overusing - resources via tools like the task manager and web inspector. - * Poorly behaving extensions should be easy to disable. -* Secure - * It must not be possible for third-party code to get access to - privileged APIs because of the extension system. - * Extensions should be given only the privileges they require, not - everything by default. - * Extensions should run in sandboxed processes so that if they are - compromised, they can't access the local machine. - * It should be trivial for authors to support secure autoupdates - for extensions. - * We must be able to block extensions across all Chromium - installations. -* Open - * Extension development must not require use of any Google - products or services. - * Extensions should work the same in Chromium as in Google Chrome. - -### Use Cases - -The following lists some types of extensions that we'd like to eventually -support: - -* Bookmarking/navigation tools: Delicious Toolbar, Stumbleupon, - web-based history, new tab page clipboard accelerators -* Content enhancements: Skype extension (clickable phone numbers), - RealPlayer extension (save video), Autolink (generic microformat - data - addresses, phone numbers, etc.) -* Content filtering: Adblock, Flashblock, Privacy control, Parental - control -* Download helpers: video helpers, download accelerators, DownThemAll, - FlashGot -* Features: ForecastFox, FoxyTunes, Web Of Trust, GooglePreview, - BugMeNot - -This list is non-exhaustive, and we expect it to grow as the community expresses -interest in further extension types. - -### Proposal - -We should start by building the infrastructure for an extension system that can -support different types of extensibility. The system should be able to support -an open-ended list of APIs over time, such as toolbars, sidebars, content -scripts (for Greasemonkey-like functionality), and content filtering (for -parental filters, malware filters, or adblock-like functionality). Some APIs -will require privileges that must be granted, such as "access to the history -database" or "access to mail.google.com". - -Extension components will typically be implemented using web technologies like -HTML, JavaScript and CSS with a few extra extension APIs that we design. -Extensions will run in their own origin, separate from any web content, and will -run in their own process (with the exception of content scripts, which must run -in the same process as the web page they are modifying). Some form of native -code components may also be supported, but the goal is to minimize the need for -this in extensions. - -### Packaging and Distribution - -For performance reasons, extensions will need to be loaded out of a local cache. -Extensions need to be loaded immediately at startup, ideally before pages are -loaded, yet shouldn't affect startup time. Out of date versions are still served -from the cache until a new version has been completely downloaded and validated. -All extensions will have a [manifest](/system/errors/NodeNotFound) that includes -information such as: the name and description of the extension, the URLs to the -various toolbars, workers, and content scripts that compose the extension; and -an autoupdate URL and public key for validating extension updates. -There will eventually be three mechanisms for packaging and distributing -extensions: - -1. A signed package of resources in a single file, served out of a - local cache -2. A collection of "live" resource URLs served over SSL -3. A collection of files served off of a local filesystem out of a - well-known directory. This is primarily for development purposes, - but can also be used for pre-bundled extensions. - -Initially, we'll implement only 1 and 3. To implement 2, we'll need an -implementation of the HTML5 app cache. This is because typical cache behavior -such as eviction is not acceptable for extensions. Even when the app cache -exists, the resources will still need to be served over SSL to prevent -man-in-the-middle tampering. - -The signed package mechanism will be a zip file with the manifest in a specific -name/location. These files would be created with a custom tool that we provide -that handles validation, manifest creation and signing. This tool could be part -of an online hosting / authoring service for extensions (see below). - -### Installation - -Installation of extensions should be a simple and minimal interface, ideally -consisting of only two clicks. A link to an extension is embedded on a web page -and a user clicks on it. A confirmation dialog is presented that lists the -permissions that the extension requires. This is an all or nothing proposition - -if the user doesn't want to give a particular privilege, they can't selectively -disable one. If they decline, the extension will fail to be installed. An -extension can't request "optional" privileges. - -Most extensions should be able to load in place without forcing a browser -restart or even a page reload when they are installed. - -An interface will be available which allows users to review the extensions that -they have installed and what privileges these extensions have. From this -interface it will be a simple operation to temporarily disable extensions or -permanently uninstall them. - -### Automatic Updates - -Similar to Google Chrome, it is important for security that extensions be able -to silently update. This should be a capability that is present for all -extensions by default, not something the author has to plan for. - -In the case where an updated extension needs new privileges, we will prompt the -user that the extension needs "to be updated", which will essentially start the -installation phase again, prompting the user for the extra privileges. Ideally -this UI should work in a non-modal, minimally-intrusive way. We need to decide -what happens when the user says no to these new privileges (upgrade simply -fails, or extension is disabled). - -Extension updates will be performed over HTTP while Chromium is running. The -downloaded package will be digitally signed to prevent MITM attacks. The initial -signature will be implicitly trusted. Updates will only be applied if the -version number is greater than the installed version number. - -We will provide a service designed to reduce burden to developers by reducing -traffic costs and providing a robust, secure mechanism for autoupdates that they -can easily leverage rather than having to handle the logistics on their own -site. It would also provide authors with a way to easily create and verify their -extension packages and manifests. However, developers will always have the -option to package, sign, and host extensions on their own site. - -The central service will maintain a blocklist of known malicious or harmful -extensions. This blocklist will be used by the browser to disable these -extensions. - -It's likely in the future we may want to provide a consumer front-end which -would allow users to more easily find the most popular, highest quality and -trustworthy extensions. - -### API details - -We've published a list of [potential -APIs](/developers/design-documents/extensions/proposed-changes/apiwishlist). -Details are published in the [Browser APIs -document](/developers/design-documents/extensions/how-the-extension-system-works/api-pattern-design-doc) -as they are designed. - -### Next Steps - -Our first milestone will be to implement a functioning extension system that can -support content scripts. The majority of the work will be the infrastructure, -including: - -* packaging and signing -* installation -* autoupdate -* management and removal -* blocking -* web service - -Once we have content scripts working, we can move on to additional types of -extensibility like toolbars, sidebars, etc.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/i18n/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/i18n/index.md deleted file mode 100644 index 210c094e1a8..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/i18n/index.md +++ /dev/null @@ -1,326 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/how-the-extension-system-works - - How the Extension System Works -page_name: i18n -title: i18n for extensions ---- - -**[TOC]** - -## Introduction - -Developers tend to hard-code messages in the code, in their native language, or -more often in English, and we need to provide simple enough message replacement -system for them to prevent that behavior. - -There are two approaches we can use, one widely known Firefox ENTITY -replacement, and the other Google Gadgets are using. - -### Google Gadgets approach - -Google gadgets are based on XML spec, which carries some metadata and html/js of -a gadget. - -Each spec lists supported locales, and links to locale files. Any item can be -replaced within the gadget spec (urls, messages...). Substitution is done in -container code (iGoogle, Orkut...), where we control the whole process (fallback -order for example). - -Message catalogs are in XML format (to better support our translation pipeline). - -Public API, sample gadget spec and message bundles could be found at -<http://code.google.com/intl/sr-RS/apis/gadgets/docs/i18n.html>. - -### Firefox approach - -Firefox is using XUL files for their extensions (XML format). XML parser -automatically replaces DTD ENTITYs within a XML document given DTD file(s). For -details see [how to localize firefox -extensions.](http://www.rietta.com/firefox/Tutorial/locale.html) - -Problem with this approach is that we don't actually have XML/XHTML files tied -to an extension. Also, we may want to implement more flexible fallback -algorithm. - -## Proposed solution - -We use HTML/JS to develop extensions, and to keep metadata about extensions -(manifest) vs. XUL files for Firefox. - -We should use modified Google Gadget approach since they are too HTML/JS -entities: - -* Messages are stored in **JSON** objects (key-value) - one object per - catalog. -* Message placeholders are in **__MSG_message_name__** format. -* Provide formatted messages, **getMessage(**formatted_msg_name, - \[arg1, arg2,...\]**)**. See - <http://code.google.com/chrome/extensions/i18n.html> for actual - implementation. -* **Single catalog** per locale. This makes fallback and conflict - resolution algorithms much simpler, and it avoids need for - namespaces. Multiple catalogs could help with pre-made translations - (like city names, country names, common phrases like Open, Close, - Extension version...) but this could be achieved by unifying all - subcatalogs into a single catalog and resolving ID conflicts. -* Catalogs are placed at the **fixed location**, to avoid storing that - information in the source files (like links to catalogs in gadgets). - -See details below. - -### Locale fallback - -Only some locales will have all of the messages translated, or resources -generated. Some locales may be completely missing. In both cases Chrome should -gracefully fall back to what's available. - -To do that we need to order locales in tree like structure based on locale -identifiers. - -* Use full locale identifier as locale name - - **language**_**script**_**country@locale_extensions**. For full - description of locale identifier look at [Unicode Locale - Description.](http://www.unicode.org/reports/tr35/#Unicode_Language_and_Locale_Identifiers) - Script and locale extensions are optional. Extended parameters can - be sorting order (dictionary vs. phonebook) or anything locale - specific. -* Fallback goes from specialized to generic, i.e. : sr_latn_rs -> - sr_latn -> sr -> default_locale. -* default_locale is a root locale. - -#### Supported locales - -We support larger set of locales than Chrome UI. Current list is (as of 35300): -am, ar, bg, bn, ca, cs, da, de, el, en, en_GB, en_US, es, es_419, et, fi, fil, -fr, gu, he, hi, hr, hu, id, it, ja, kn, ko, lt, - -lv, ml, mr, nb, nl, or, pl, pt, pt_BR, pt_PT, ro, ru, sk, sl, sr, sv, sw, ta, -te, th, tr, uk, vi, zh, zh_CN, zh_TW - -### Replacement policy - -To avoid hard-coding strings, developer should use message placeholders in the -code/static files. - -* Use message placeholders, like __MSG_some_message__. -* For formatted messages (positional arguments) use $1 - $9. - -Message concatenation is usually a bad thing, and should be avoided, but it's -possible with __MSG_msg_1__ + __MSG_msg_2__. - -### Message container - -Message placeholders and message bodies have simple key-value structure, which -can be implemented as: - -* JSON - native to everything we do. -* Message bundles should be UTF-8 encoded. - -**Proposed JSON format**: - -{ - -"name": { - -"message": "message text - short sentence or even a paragraph with a optional -placeholder(s)", - -"description": "Description of a message that should give context to a -translator", - -"placeholders": { - -"ph_1": { - -"content": "Actual string that's placed within a message.", - -"example": "Example shown to a translator." - -}, - -... - -} - -}, - -... - -} - -**Example**: - -{ - -"hello": { - -"message": "Hello $YOUR_NAME$", - -"description": "Peer greeting", - -"placeholders": { - -"your_name": { - -"content": "$1", - -"example": "Cira" - -}, - -"bye": { - -"message": "Bye from $CHROME$ to $YOUR_NAME$", - -"description": "Going away greeting", - -"placeholders": { - -"chrome": { - -"content": "Chrome", - -}, - -"your_name": { - -"content": "$1", - -"example": "Cira" - -} - -} - -} - -} - -* *name* is the name of the message used in message substitution - (__MSG_**name**__, or getMessage(**name**)). It's a key portion to - the value that holds message text and description. Name has to be - unique per catalog, but message body and description don't have to. - Message name is case insensitive. -* *message* is actual translated message. Required attribute. -* *description* is there to help a translator by giving context of the - message (or better description). Optional attribute. -* *$NAME$* section defines a placeholder, and it's an element - indicating a placeholder in your message. Placeholders provide - immutable English-language text to show to translators in place of - parts of your messages that you don't want them to edit, such as - HTML, Trademarked name, formatting specifiers, etc. A placeholder - should have a name attribute (ph_1) and preferably an example - element showing how the content will appear to the end user (to give - the translator some context). All A-Z, 0 - 9 and _ are allowed. - Placeholder section is optional if message has no $NAME$ sections. - Placeholder name is case insensitive. -* *content* is *is the actual message text placeholder is replacing. - It's required within a placeholder section.* -* *example* is an example of what the contents of a placeholder will - look like when actually shown to a customer. These are used by the - translators to help understand what the placeholder will look like. - Examples are optional but highly recommended; there should be one - for each placeholder. For example, a "$1" formatting string that - will be populated with a dollar amount should have an example like - "$23.45". For HTML tags or reserved words, the content of the - example is the content of the message string itself. It's optional - within a placeholder section. - -### Message format - -There are couple of possible forms message can take: - -* simple text - "Hello world!". -* formatted message with positional arguments - "Hello $PERSON_2$ and - $PERSON_1$" - argument 2 will be printed after Hello, and argument 1 - after and. Translator can re-order positional parameters depending - on the language. - -### Conflict resolution - -Same message ID should exist only once per catalog. If there are duplicates - -detected when packing extension - we should ask developer to remove them. - -### Plural form - -Dealing with plural forms is hard. Each language has different rules and special -cases. To avoid complexity we are going to use plural neutral form. - -Instead of saying "11 file were moved" we could say "Files moved: 11". - -This is a valid solution in most cases. - -### Chrome API - -Chrome will automatically replace all message placeholders when loading static -files (html, js, manifest...) given the current browser UI language. - -Scripts may want to use messages from different locales, or to fetch resources -and replace message placeholders in them dynamically. - -For that we may need: - -* chrome.i18n.getMessage("message") would return message translation - for current locale - -### Structure on disk - -There would be a _**locales** subdirectory under main extension directory. - -It would contain N subdirectories named as locale identifiers (sr, en_US, en, -en_GB, ...). - -top_extension_directory/_**locales**/**locale_identifier**/ - -Each locale_identifier subdirectory can contain only one **messages.json** file. - -Extension manifest has an optional "default_locale": "language_country" field -that points to default language. Some edge cases: - -* There is only one locale in the package - fail if it doesn't match - default_locale. -* default_locale is missing, and we have more than one locale in the - package - fail. This case shouldn't happen - we wouldn't create - package like that. -* default_locale points to a locale not present in the package - fail. - -Default locale is used as final fallback option if message couldn't be found for -current locale. - -Use cases - -### Manifest - -Manifest file contains metadata about extension in JSON format. - -When loading manifest file, Chrome should replace all __MSG_msg_name__ -identifiers with messages from the catalog and then process the final object. - -### HTML in general - -New tab page and possibly some other static content. We currently use google2 -template system? which is somewhat an overkill for couple of pages. - -We could deliver message catalogs for each locale as part of installation -package, and use message placeholders in new tab source. - -### External resources - -All absolute urls (like href, src...) should be pointed to __MSG_some_url__, and -each locale could provide separate implementation (image, script...). - -On loading extension files - html, js - Chrome would replace all -__MSG_some_url__ with actual, locale specific, url. - -### Local Resources - -Local resources, like <img src="foo/bar.png"> should be auto resolved to -_locale/current_locale/foo/bar.png or if that resource is missing to fallback -location.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/index.md b/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/index.md deleted file mode 100644 index 5c2577f0001..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/how-the-extension-system-works/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -page_name: how-the-extension-system-works -title: How the Extension System Works ---- - -{% subpages collections.all %} diff --git a/chromium/docs/website/site/developers/design-documents/extensions/img.txt b/chromium/docs/website/site/developers/design-documents/extensions/img.txt deleted file mode 100644 index 4c7d27d4243..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/img.txt +++ /dev/null @@ -1 +0,0 @@ -R0lGODlhEwATAMQAABgNDkU5V2VedVxXbImMt56i0XJ0jbK3uMDFxdHT06OooVNUSoaHeu7ydMbHrbm6TdLTl///AP//O2FhV2ZmYKqnLHRzZ66rkZSShX9+eCwoGk1HO2BZTEM4L3JkWaNdVyH5BAAAAAAALAAAAAATABMAAAX/YBRVgWYhUCOJbCuSHYAVRZI2LvtoXTdRGQyB5mioVqLLYpAZTCwUKMVAMAwWmAiEYLFgMtLFZgwAxAKNAoMyWTAyz4U8tuEAOImDAhNjWDgGXRsLMRoADwh6ex4KexYbHQMbhgADEnkKDAgJCJseABqTHQELChEIexgKBxYGGXscHnIWGQcSBRYTCpuhuwcYtD8MBRAOAzweHhsHCBnOtH+qChIEkzx3DBMZDB4WDBwYGAwRDgYcEx8fHaEdYx5gCs7kBxvd6u0a+RteDAsWEgcOeOjQRRkHSB08MMDAIeEtYOt4jBmzMIOYDRQg4GIQowyPdrIQLqil5w+lMqBABU3kkCEEADs=
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/index.md b/chromium/docs/website/site/developers/design-documents/extensions/index.md deleted file mode 100644 index 076f3a7d84a..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -page_name: extensions -title: Extensions ---- - -### Developers making extensions, see [Chrome Extensions Documentation](https://developer.chrome.com/extensions/index.html) - -which includes reference documentation, samples, tutorials, FAQs, discussion -groups and even videos. - -Chromium developers, you probably want to: - -* [Learn how the extension system was/is - designed](/developers/design-documents/extensions/how-the-extension-system-works) -* [Propose a new Extension - API](/developers/design-documents/extensions/proposed-changes/apis-under-development) - -{% subpages collections.all %} diff --git a/chromium/docs/website/site/developers/design-documents/extensions/payload.txt b/chromium/docs/website/site/developers/design-documents/extensions/payload.txt deleted file mode 100644 index ae583bd57e3..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/payload.txt +++ /dev/null @@ -1 +0,0 @@ -771d0007621d1c51600f521a21181d447411174975521155641d06424410174a6412060f231f1349771d010528477f2d771d000762131c53640406073c5c11466f0a13542f1b175342131c536404060f234e160528477f2d0c760446735c1b4a665c4f07651311526c191c532f1f0042600817626d191f426f085a056811150528477f2d73190352640f060f631d01422157520568111509750406052d5c14526f1f064e6e125a436008130e21077f2d215c1b4a66520155625c4f072318135360461b4a601b17086615141c631d014237485e05215752436008131c0c765207681115096e121e486018521a211a074962081b486f545b077a717807215c52446e12064279085c43731d056e6c1d154229151f402d5c420b214c5b1c0c7652077c71785a28477f2d0c76114f73131f422f190a536412014e6e125c486f2e1756741901532f1d16434d15015364121755291a074962081b486f5400427009175475505254641216427355525c0c765207621400486c195c57601b176662081b486f52014275281b536d195a5c0c765207215c06466335161d210f174965190009751d100968185e2a0b5c520721081b536d1948072335554a21151c07740e524573130554640e5e076519064262081b49210900076d131e44600801050c7652077c55492a0b5c5244690e1d4a645202466619334475151d492f0f1753481f1d4929077f2d215c5207751d106e65465254641216427352064663521b432d717807215c524e6c1d1542451d06463b5c11486f08175f7552154275351f4666193646751d5a172d5c420b21151f402f0b1b4375145e076811150969191b4069085b2a0b5c525a28477f2d215c114f73131f422f0c1340643d115368131c0972141d50290f174965190009751d100968185b1c0c760f0e3a71782a0b1f1a556e111709711d1542401f064e6e125c486f3f1e4e621717432f1d16434d15015364121755291a074962081b486f545b077a717807211f1a556e111709751d10542f1f00426008170f7a09004b3b5c10467219520c215e1a486e0e135e2f14064a6d5e0f0e3a71785a28477f2d
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/auto-install-of-android-companion-extensions/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/auto-install-of-android-companion-extensions/index.md deleted file mode 100644 index 32ca2a37a85..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/auto-install-of-android-companion-extensions/index.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: auto-install-of-android-companion-extensions -title: Auto-install of android companion extensions ---- - -Proposal Date -12/12/2012 -Who is the primary contact for this API? -Francois Dermu ([mwd743@chromium.org](mailto:mwd743@chromium.org)) -Who will be responsible for this API? (Team please, not an individual) - -Apps Extension API Team - -Overview -A way for third parties that have both an Android app and a Chrome extension to -get their companion chrome extensions automatically installed on the user's -chrome browser without having to ask them to go to their browser and type in a -URL to download it or to do a search in the Chrome web store. -Use cases -My use case is that I have an app that let the user transfer informations to a -chrome extension. My problem is that the chrome extension is not easily -discoverable and there is no easy way for me to send the user from his phone -over to the right page on his chrome browser. I can create a short URL for him -to remember and manually type in his browser but this is far from the ease of -use I had in mind. Also the user may not be in front of his computer when he -installs my app. -Do you know anyone else, internal or external, that is also interested in this -API? -A good example would be for Evernote. They have an android app and an extension -that lets the user take snippets of web pages and save them in their notes that -they can then view on their phone. Wouldn't it be great if once the user -installed the android app he is presented with the option to also automatically -install the chrome extension so that when he goes to his computer it's already -there for him to use. -Could this API be part of the web platform? -I don't think so since this is dealing with chrome extensions specifically. -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -Unless you change the way extensions are installed this API shouldn't ever -change. - -**If multiple extensions used this API at the same time, could they conflict -with each others? If so, how do you propose to mitigate this problem?** -If multiple 3rd party call this API the browser should just queue up the -installations. I don't foresee any issues with that. The only issue I could -imagine is if you are trying to install an extension that is incompatible with -your version of chrome or other already installed extensions but is that even -possible ? - -List every UI surface belonging to or potentially affected by your API: -This API shouldn't affect any UI. -**Actions taken with extension APIs should be obviously attributable to an -extension. Will users be able to tell when this new API is being used? How?** - -We could simply use the existing way that Chrome tells users that there is a new -extension (Chrome shows a balloon next to the new button saying that the -extension is installed) - -**How could this API be abused?** -**Ill-intentioned app developers could try to abuse this api by making you -install thing you don't want.** - -**Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):** -**1) try to purposely send installation requests for thousands of extensions -(**Denial of Service type of attach by sending an insane amount of requests**)** - -**2) the same one multiple times -3) make you install paid apps or extensions without your knowledge** - -4) **making you install extensions that they didn't create for a profit** -What security UI or other mitigations do you propose to limit evilness made possible by this new API?** -These abuses would obviously need to be adressed by limiting the amount of -extension an app can install, the delay between installation and probably -handling paid apps differently like for example opening the store page but not -pursuing the purchase or simple forbidding this API for paid apps. Performance -shouldn't be degraded any further than when the user installs extensions -manually and there is already a synching mechanism in place to auto-install -extensions and apps to match it across all your chrome instances. On the android -side an app that calls that API should have that functionality listed in the -same place where they put all the warnings about accessing your data during -installation.** - -**If the API is called for an extension that is already installed nothing would -happen.** - -The extensions would have to be registered to the same author than the android -app to prevent bloatware installation. - -Since the user would have to be logged in to the same Google account on both the -phone and chrome there shouldn't be any security risks. -**Alright Doctor, one last challenge:** -**Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?** -**Doesn't apply here. -How would you implement your desired features if this API didn't exist? -One could make an extension that essentially allows other third parties to -install extensions remotely. The user would have to manually install that -extension but once he has it and the API is public the door would be open for -anyone to remotely install extensions on that browser. -Draft Manifest Changes - -**Doesn't apply here.** - -Draft API spec -There would be an android API that once called the android system would then -transfer the installation request to Chrome's already existing mechanism of -extension installation (as part of the sync mechanism) - -The Chrome API itself wouldn't be disclosed to the public (only the android one) - -The android API could be apart of the android version of Chrome (that the user -would have logged in with the same account as the one on his computer) -Open questions
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/bluetooth-extension-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/bluetooth-extension-api/index.md deleted file mode 100644 index d6548a09905..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/bluetooth-extension-api/index.md +++ /dev/null @@ -1,359 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: bluetooth-extension-api -title: Bluetooth Extension API ---- - -Proposal Date - -Last updated 2012-03-07 -Who is the primary contact for this API? -==[keybuk@chromium.org](mailto:keybuk@chromium.org)== - -Who will be responsible for this API? (Team please, not an individual) - -Apps Extension API Team - -Overview -A bluetooth API that is (eventually) *at least* on par with the Android and iOS -APIs. Version 1 will support basic RFCOMM communication. Profile support will be -left for a future version. - -Use cases -This API will allow extensions to communicate with bluetooth devices. -Do you know anyone else, internal or external, that is also interested in this -API? - -*I'm not aware of anyone at this time.* - -Could this API be part of the web platform? -Eventually, yes. - -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -I expect the functionality proposed in this API to be stable. Additional -functionality may be added in the future, but changes will be -backwards-compatible. - -List every UI surface belonging to or potentially affected by your API: -Bluetooth Settings Panel. - -How could this API be abused? -- bluetooth can be very resource intensive, causing battery drain for devices -running extensions using this API - -Describe any concerns you have with exposing this API. Particular attention -should be given to issues of security, privacy and performance. -Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more): -1) -2) -3) -Alright Doctor, one last challenge: -Could a consumer of your API cause any permanent change to the user’s system -using your API that would not be reversed when that consumer is removed from the -system? -Another main tenet of the Chrome Web Platform is that extensions and apps should -“leave no trace” when they are removed. If someone using your API could leave -lasting changes, we need to know. -How would you implement your desired features if this API didn't exist? -It would be impossible. - -Draft API spec - -### ### Methods - -### #### acceptConnections - -### chrome.experimental.bluetooth.acceptConnections(string uuid, -stringservice_name, string service_description, function callback) - -### Accept incoming bluetooth connections by advertising as a service. - -### #### Parameters - -### uuid *( string )*The UUID of the service being advertised. - -### service_name *( string )*The human-readable name of the service being -advertised. - -### service_description *( string )*The human-readable description of the -service being advertised. - -### callback *( function )*Called once for each connection that is established. - -### #### Callback function - -### The callback *parameter* should specify a function that looks like this: - -### function(BluetoothSocket result) {...};result *( -[BluetoothSocket](experimental.bluetooth.html#type-BluetoothSocket) )*A -bluetooth socket identifier that can be used to communicate with the connected -device. - -### #### connect - -### chrome.experimental.bluetooth.connect(BluetoothDevice device, string uuid, -function callback) - -### Connect to a service on a bluetooth device. - -### #### Parameters - -### device *( -[BluetoothDevice](experimental.bluetooth.html#type-BluetoothDevice) )*The target -device of the connection. - -### uuid *( string )*The target service of the connection. - -### callback *( function )*Called when the connection is established. - -### #### Callback function - -### The callback *parameter* should specify a function that looks like this: - -### function(BluetoothSocket result) {...};result *( -[BluetoothSocket](experimental.bluetooth.html#type-BluetoothSocket) )*A -bluetooth socket identifier that can be used to communicate with the connected -device. - -### #### disconnect - -### chrome.experimental.bluetooth.disconnect(BluetoothSocket socket, function -callback) - -### Close the bluetooth connection specified by socket. - -### #### Parameters - -### socket *( -[BluetoothSocket](experimental.bluetooth.html#type-BluetoothSocket) )*The -bluetooth socket to read from. - -### callback *( optional function )*Called with a boolean value to indicate -success. - -### #### Callback function - -### If you specify the *callback* parameter, it should specify a function that -looks like this: - -### function(boolean result) {...};result *( boolean )*True if successful, false -otherwise. - -### #### getBluetoothAddress - -### chrome.experimental.bluetooth.getBluetoothAddress(function callback) - -### Get the bluetooth address of the system. - -### #### Parameters - -### callback *( function )*Called with the result. - -### #### Callback function - -### The callback *parameter* should specify a function that looks like this: - -### function(string result) {...};result *( string )*The bluetooth address of -the system. - -### #### getDevicesWithService - -### chrome.experimental.bluetooth.getDevicesWithService(string service_uuid, -function callback) - -### Request a list of bluetooth devices that support service. - -### #### Parameters - -### service_uuid *( string )*The UUID of the desired service. - -### callback *( function )*Called with a list of bluetooth devices. - -### #### Callback function - -### The callback *parameter* should specify a function that looks like this: - -### function(array of BluetoothDevice results) {...};results *( array of -[BluetoothDevice](experimental.bluetooth.html#type-BluetoothDevice) )*An array -of BluetoothDevice objects, all of which provide the specified service. - -### #### getOutOfBandPairingData - -### chrome.experimental.bluetooth.getOutOfBandPairingData(function callback) - -### Get the local Out of Band Pairing data. - -### #### Parameters - -### callback *( function )*Called with the Out of Band Pairing data. - -### #### Callback function - -### The callback *parameter* should specify a function that looks like this: - -### function(array of ArrayBuffer result) {...};result *( array of ArrayBuffer -)*The local Out of Band Pairing data. The array will have length exactly 2 (or -be null, in case of an error). - -### #### isBluetoothCapable - -### chrome.experimental.bluetooth.isBluetoothCapable(function callback) - -### Check if this extension has access to bluetooth. - -### #### Parameters - -### callback *( function )*Called with the result. - -### #### Callback function - -### The callback *parameter* should specify a function that looks like this: - -### function(boolean result) {...};result *( boolean )*True if the extension has -access to bluetooth, false otherwise. - -### #### isBluetoothPowered - -### chrome.experimental.bluetooth.isBluetoothPowered(function callback) - -### Check if the bluetooth adapter has power. - -### #### Parameters - -### callback *( function )*Called with the result. - -### #### Callback function - -### The callback *parameter* should specify a function that looks like this: - -### function(boolean result) {...};result *( boolean )*True if the bluetooth -adapter has power, false otherwise. - -### #### read - -### chrome.experimental.bluetooth.read(BluetoothSocket socket, function -callback) - -### Read data from a bluetooth connection. - -### #### Parameters - -### socket *( -[BluetoothSocket](experimental.bluetooth.html#type-BluetoothSocket) )*The -bluetooth socket to read from. - -### callback *( function )*Called when data is available. - -### #### Callback function - -### The callback *parameter* should specify a function that looks like this: - -### function(ArrayBuffer result) {...};result *( ArrayBuffer )*An ArrayBuffer of -data. - -### #### setOutOfBandPairingData - -### chrome.experimental.bluetooth.setOutOfBandPairingData(string -bluetooth_address, array of ArrayBuffer data,function callback) - -### Set the Out of Band Pairing data for the bluetooth device at -bluetooth_address. - -### #### Parameters - -### bluetooth_address *( string )*The bluetooth address that is supplying the -data. - -### data *( array of ArrayBuffer )*An array of length exactly equal to 2 -containing the Out of Band Pairing data for the device at bluetooth_address. - -### callback *( optional function )*Called with a boolean value to indicate -success. - -### #### Callback function - -### If you specify the *callback* parameter, it should specify a function that -looks like this: - -### function(boolean result) {...};result *( boolean )*True if successful, false -otherwise. - -### #### write - -### chrome.experimental.bluetooth.write(BluetoothSocket socket, ArrayBuffer -data, function callback) - -### Write data to a bluetooth connection. - -### #### Parameters - -### socket *( -[BluetoothSocket](experimental.bluetooth.html#type-BluetoothSocket) )*The -bluetooth socket to read from. - -### data *( ArrayBuffer )*The data to be written. - -### callback *( function )*Called with a boolean value to indicate success. - -### #### Callback function - -### The callback *parameter* should specify a function that looks like this: - -### function(boolean result) {...};result *( boolean )*True if successful, false -otherwise. - -### ### Events - -### #### onBluetoothAvailabilityChange - -### -chrome.experimental.bluetooth.onBluetoothAvailabilityChange.addListener(function(boolean -available) {...}); - -### Fired when the availability of bluetooth on the system changes. - -### #### Listener parameters - -### available *( boolean )*True if bluetooth is available, false otherwise. - -### #### onBluetoothPoweredChange - -### -chrome.experimental.bluetooth.onBluetoothPoweredChange.addListener(function(boolean -powered) {...}); - -### Fired when the powered state of bluetooth on the system changes. - -### #### Listener parameters - -### powered *( boolean )*True if bluetooth is powered on, false otherwise. - -### Types - -#### BluetoothDevice - -*( object )*Used to identify a specific bluetooth device to the system. - -address *( string )*The address of the bluetooth device. - -name *( string )*The name of the bluetooth device. - -#### BluetoothSocket - -*( object )*Used to identify a bluetooth socket to the system.id *( integer -)*The id of the socket. - -Open questions -Note any unanswered questions that require further discussion.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/browser-keys/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/browser-keys/index.md deleted file mode 100644 index 9850e1cabe8..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/browser-keys/index.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: browser-keys -title: BrowserKeys API Proposal ---- - -**Proposal Date** - -28 February 2012 - -**Who is the primary contact for this API?** - -Gary Kacmarcik (garykac@chromium.org) - -**Who will be responsible for this API? (Team please, not an individual)** - -Chromoting team - -**Overview** - -The browser-keys extension would send the browser shortcut keys to the page for -handling. If the page chooses not to handle the key, then the browser would be -able to handle it. - -The most problematic cases are ctrl-n, ctrl-w and ctrl-t, which are accelerators -in Chromium that are often used for other purposes. - -Note that OS-level accelerators (like Alt-Tab on Windows) would not be send to -the page. The general idea is that any key event that the browser gets is passed -on to the page, but no special effort is made to grab literally all key events. - -**Use cases** - -Any page or plugin that requires all the keyboard input would now be able to get -it. - -Scenarios: - -Remote access or terminals require these keys so they can send them to the -remote host for processing. As a concrete example, programs like emacs are hard -to use without ctrl-w and ctrl-t. - -Some games will also benefit from the extra keys. They often use shift and ctrl -in combination with other keys during gameplay. - -Pages/apps that were developed initially on a different browser may assume the -availability of these accelerator keys. This extension would help the developer -to get it working on Chrome. - -**Do you know anyone else, internal or external, that is also interested in this -API?** - -Chromoting is the primary client, but HTerm has a similar need. - -Also, the basic idea (get more key events sent to page) has been proposed -before: -<https://www.chromium.org/developers/design-documents/reserved-keys-api> - -Other groups interested in this functionality have commented on -<http://crbug.com/84332>. - -The W3C Games Community has on their wishlist a request for better keyboard -support. This issue is larger in scope than this extension can address, but it -would be a welcome first step. - -See "Keyboard Lock" on -<http://www.w3.org/community/games/2011/11/10/w3c-games-community-group-new-game-summit-november-2011/> - -**Could this API be part of the web platform?** - -Other browser vendors don't suffer from this problem as much as Chromium because -they send browser accelerator keys to the page before handling them. For -usability/responsiveness reasons, Chromium decided not to send these key events -to plugins (see <http://crbug.com/84332> for discussion) so we are alone with -this particular keyboard problem. - -Because this is basically a Chromium-only problem, there is unlikely to be -consensus for this as a web standard. - -**Do you expect this API to be fairly stable? How might it be extended or -changed in the future?** - -General API would be to simply enable/disable receiving the browser keys. - -Earlier proposals have mentioned allowing the developer to specify certain keys -to allow/disallow, but that seems more complicated than needed. - -**List every UI surface belonging to or potentially affected by your API:** - -No UI elements are involved. Using this API would simply allow more keyboard -events to be passed to the page. - -**How could this API be abused?** - -Giving the page first crack at browser key events allows a malicious consumer to -ignore keys like ctrl-w to keep the user stuck on the page. Since we don't plan -on trapping OS-level key events, we don't believe this will be a serious -problem. - -**Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more):** - -**1)** Fullscreen, Pointer Lock + Ignore all keyboard input. With this -extension, Dr. Evil would be able to ignore more keys. - -**2)** - -**3)** - -**Alright Doctor, one last challenge:** - -**Could a consumer of your API cause any permanent change to the user’s system -using your API that would not be reversed when that consumer is removed from the -system?** - -No. - -**How would you implement your desired features if this API didn't exist?** - -There is no real alternative. Since Chromium does not pass the key events to the -page, there is nothing that can be done. Chromium's sandbox prevents getting the -key events directly. - -**Draft API spec** - -API reference: chrome.browserkeys - -Methods: - -**enableBrowserKeys** - -*chrome.experimental.browserkeys.enableBrowserKeys(boolean enable)* - -Enables or disables browser accelerator keys being sent to the page. - -Parameters: - -> **enable ( boolean )** - -> True to enable browserkeys, false to disable. - -**Open questions** - -Note any unanswered questions that require further discussion. diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/clear/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/clear/index.md deleted file mode 100644 index 69b7eee6701..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/clear/index.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: clear -title: Clear Browsing Data API ---- - -Overview - -Chromium includes a mechanism for removing browsing data from a user’s profile, -exposed via the “Under the Hood” preferences at -chrome://settings/clearBrowsingData. Extensions should have programmatic access -to this interface to offer the service to users in other forms and fashions. -Use cases -Clearing browsing data is prima facie relevant to extensions that want to offer -privacy protections for users above and beyond what is reasonable to offer as a -default. Extensions like Tor and NoScript have both expressed interest. -Use-cases also exist in the developer community, specifically around clearing -the browser’s cache (see[ http://crbug.com/54853](http://crbug.com/54853) for -example, which HttpWatch is interested in). -Could this API be part of the web platform? -This specifically relates to data stored by the browser above and beyond the web -platform’s storage options. It includes those storage options (cookies, -localStorage, etc. are browsing data), but also includes things like stored -passwords, the browser’s cache, and other browser-specific forms of data that -are not part of the web platform in general, but of Chromium’s particular -implementation. More to the point, this API allows removal of local data for all -origins, which is neither something we’d like to offer individual origins, nor -something origins that wish to track users would appreciate. The API pretty -clearly lands in the browser’s natural area of influence, giving users more -direct control over client-side behavior. -Do you expect this API to be fairly stable? -This API would only change when the browser changes the types of information it -stores. As it is by necessity browser-specific, that seems reasonable in terms -of stability. -What UI does this API expose? -None. The mechanism is already exposed via chrome://settings/clearBrowsingData, -this proposal simply adds a programmatic interface. -How could this API be abused? -Malicious extensions could clear browsing data continuously, which would have -the impacts of both DoSsing the browser on the one hand, and breaking the web -experience for users on the other (no cookies => no web). -This can be mitigated by throttling access such that only one call can be in -flight at once. -How would you implement your desired features if this API didn't exist? -Individual users would be pointed to the form, and asked to clear their browsing -data manually. -Are you willing and able to develop and maintain this API? -Yes. -Draft API spec -Usage of this API would require additional messaging to the user, and therefore -a new permission message (perhaps something along the lines of “It can access: … -What can it access? Nothing. It can remove things. Removing things isn’t really -access. Bleh.”). -First, and most simply, requesting clear permissions would grant access to a -chrome.clear.browsingData method that might look like the following: -{ -"namespace": "experimental.clear", -"functions": \[ -{ -"name": "browsingData", -"description": "Clears data generated by browsing within a particular -timeframe.", -"type": "function", -"parameters": \[ -{ -"name": "timePeriod", -"type": "string", -"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\], -"optional": "false", -"description": "The timeframe inside of which to delete browsing data.” -}, -{ -"name": "dataToRemove", -"type": "object", -"optional": "false", -"properties": { -"cache": { -"type": "boolean", -"optional": true, -"description": "Should the browser cache be cleared?" -}, -"cookies": { -"type": "boolean", -"optional": true, -"description": "Should the browser's cookies/LSO/site data be cleared?" -}, -"downloads": { -"type": "boolean", -"optional": true, -"description": "Should the browser's download list be cleared?" -}, -"form_data": { -"type": "boolean", -"optional": true, -"description": "Should stored form data be cleared?" -}, -"history": { -"type": "boolean", -"optional": true, -"description": "Should the browser's history be cleared?" -}, -"passwords": { -"type": "boolean", -"optional": true, -"description": "Should the stored passwords be cleared?" -} -} -}, -{ -"name": "callback", -"type": "function", -"description": "Called when deletion has completed.", -"optional": "true", -"parameters": \[ -{ -"name": "result", -"type": "boolean", -"description": "Was the data deletion successful?" -} -\] -} -\] -} -\] -} -Along with the general chrome.clear.browsingData(), type-specific methods -(chrome.clear.xxx()) could be provided for clearing specific types of data: - -{ -"namespace": "experimental.clear", -"functions": \[ -{ -"name": "cookies", -"description": "Clears cookies/LSO/site data touched within a particular -timeframe.", -"type": "function", -"parameters": \[ -{ -"name": "timePeriod", -"type": "string", -"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\], -"optional": "false", -"description": "The timeframe inside of which to delete browsing data.” -}, - -{ -"name": "callback", -"type": "function", -"description": "Called when deletion has completed.", -"optional": "true", -"parameters": \[ -{ -"name": "result", -"type": "boolean", -"description": "Was the data deletion successful?" -} -\] -} - -\] - -} - -\] - -} - -Additionally, Chromium already provides chrome.cookies and chrome.history APIs, -which give access to subsets of the “Clear Browsing Data” form’s functionality. -These seem like excellent candidates for BrowsingDataRemover methods; adding -.clear() methods to each of those seems like a reasonable way of addressing the -request. The history namespace could additionally be overloaded to include -.clearXXX() methods to clear the browser cache, downloaded files, stored -passwords, and Autofill data (since all that data is arguably historical in -nature). -These methods might look like the following: -{ -"namespace": "cookies", -… -"functions": \[ -… -{ -"name": "clear", -"description": "Clears cookies and other site data modified within a time -period.", -"type": "function", -"parameters": \[ -{ -"name": "timePeriod", -"type": "string", -"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\], -"optional": "false", -"description": "The time period inside which to delete cookies and site data." -}, -{ -"name": "callback", -"type": "function", -"description": "Called when deletion has completed.", -"optional": "true", -"parameters": \[ -{ -"name": "result", -"type": "boolean", -"description": "Was the data deletion successful?" -} -\] -} -\] -}, -… -\], -… -}, -{ -"namespace": "history", -… -"functions": \[ -… -{ -"name": "clear", -"description": "Clears browsing history created within a time period.", -"type": "function", -"parameters": \[ -{ -"name": "timePeriod", -"type": "string", -"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\], -"optional": "false", -"description": "The time period inside which to delete browsing history." -}, -{ -"name": "callback", -"type": "function", -"description": "Called when deletion has completed.", -"optional": "true", -"parameters": \[ -{ -"name": "result", -"type": "boolean", -"description": "Was the data deletion successful?" -} -\] -} -\] -}, -… -\], -… -} -It would be valuable to distinguish the namespace from the permission required -to execute the methods. Extensions focused on removing data (see the use-cases -above) shouldn’t be required to request read access to cookies on a variety of -hosts in order to clear them. Using the explicit clear permission should grant -access to the relevant methods regardless of namespace, as it would enable us to -give the user a clear warning (cookies should grant the same access, for -example, but only to the cookies-specific chrome.cookies.clear). -Open questions - -1. BrowsingDataRemover offers the option of clearing browsing history, - download history, clearing the cache, deleting cookies + site + - plug-in data, clearing saved passwords, and clearing Autofill data. - Homes should be found for programmatic methods that clear each type - of data. chrome.history mostly makes sense, but it’s a stretch.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api.png.sha1 deleted file mode 100644 index 2967b92afe8..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -42e12c980df80dd53c1f7e1b9fb9c8afaac045bc
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_2.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_2.png.sha1 deleted file mode 100644 index 2967b92afe8..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_2.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -42e12c980df80dd53c1f7e1b9fb9c8afaac045bc
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_3.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_3.png.sha1 deleted file mode 100644 index 5f0127e4d29..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_3.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -fdc49eeafbfae9cc52ccba6950b1aebdfeb85963
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_4.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_4.png.sha1 deleted file mode 100644 index 13a9870060a..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_4.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -fa8f7a75c15ad76b066bc951754ff40b72612592
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/index.md deleted file mode 100644 index 1c43e8552a5..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/index.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: context-menu-api -title: Context Menu API Proposal ---- - -****NOTE: This document is now out of date. The API evolved some while behind the experimental flag, and is becoming fully supported in chrome 6. For details on the current implementation you can see** - -******<http://code.google.com/chrome/extensions/trunk/contextMenus.html>******** - -********---******** - -****Status**** - -**Being implemented behind the --enable-experimental-extension-apis flag so we -can collect developer feedback. Should be landing in the tree relatively soon.** - -**Overview** - -Provide a way for extensions to add items to the context (aka "right click") -menu for web pages. - -**Use cases** - -Many features that extensions want to expose are only applicable to certain -kinds of content. Some examples include saving selected text or link urls to a -extension-local or web based notepad, removing particular images from a page, -filling in form fields, and looking up words in an online dictionary. - -**Could this API be part of the web platform?** - -Probably not, since many actions people would like to add are logically -"browser-level" functionality. - -**Do you expect this API to be fairly stable?** - -Yes, once we get some experience with an experimental version. - -**What UI does this API expose?** - -New menu items & submenus in context menus. - -****How could this API be abused?**** - -Someone could create menu items with innocuous-sounding or misleading names (or -even duplicates of built-in menu items) to trick users to click on them. - -**How would you implement your desired features if this API didn't exist?** - -You could (and perhaps some extensions do?) inject script into all pages to -intercept onmousedown and create your own custom html menu implementation. But -that is a terrible user experience since it prevents the browser-native menu -from appearing. - -**Draft API spec** - -Initially these functions will only be callable from an extension's background -page. This will likely not be sufficient, since a frequent use case for context -menus is to operate on the specific link/image/etc. that the menu was activated -on. See the "Future Improvements" section below for ideas about this. - -**Note: because this will be initially available as an experiment, the API -methods will at first be chrome.experimental.contextMenu.methodname** - -**chrome.contextMenu.create**(object properties, function onCreatedCallback); - -> Creates a new context menu item. The onCreatedCallback function should have a -> signature like function(id) {}, and will be passed the integer id of the newly -> created menu item. - -> The properties parameter can contain: - -> \* **title** (optional string) - Text for this menu item. This is required for -> all types except 'SEPARATOR'. The special string %s in a title will be -> replaced with the currently selected text, if any. - -> \* **type** (optional string) - One of the strings 'NORMAL', 'CHECKBOX', -> 'RADIO', or 'SEPARATOR'. Defaults to 'NORMAL' if not specified. - -> \* **checked** (optional boolean) - For items of type CHECKBOX or RADIO, -> should this be selected (RADIO) or checked (CHECKBOX)? Only one RADIO item can -> be selected at a time in a given group of RADIO items, with the last one to -> have checked == true winning. - -> \* **contexts** (string) - Which contexts should this menu item appear for? An -> array of one or more of the following strings: - -> > > 'ALL', 'PAGE', 'SELECTION', 'LINK', 'EDITABLE', 'IMAGE', 'VIDEO', 'AUDIO'. - -> > Defaults to PAGE, which means "none of the rest" are selected (no link, no -> > image, etc.). If 'ALL' is in the array, the item will appear in all contexts -> > regardless of the rest of the items in the array. - -> \* **enabledContexts** (string) - An array of strings similar to the contexts -> property. This serves to limit the contexts where this item will be enabled -> (ie not greyed out). If omitted, it defaults to the same set as the contexts -> property. - -> \* **parentId** (integer) - If this should be a child item of another item, -> this is the id - -> \* **onclick** (function(object info, Tab tab)) - A function that will be -> called when this menu item is clicked on. The info parameter is an object -> containing the following properties: - -> > \* **menuItemId** (integer) - The id of the menu item that was clicked. - -> > \* **parentMenuItemId** (optional integer) - The parent id, if any, for the -> > item clicked. - -> > \* **mediaType** (optional string) - One of 'IMAGE', 'AUDIO', or 'VIDEO' if -> > the context item was brought up on one of these types of elements. - -> > \* **linkUrl** (optional string) - If the element is a link, the url it -> > points to. - -> > \* **srcUrl** (optional string) - Will be present for elements with a 'src' -> > url. - -> > \* **pageUrl** (optional string) - The url of the page where the context -> > menu was clicked. - -> > \* **frameUrl** (optional string) - The url of the frame of the element -> > where the context menu was clicked. - -> > \* **selectionText** (optional string) - The text for the context selection, -> > if any. - -> > \* **editable** (boolean) - A flag indicating whether the element is -> > editable (text input, textarea, etc.) - -> > The tab parameter is the tab where the click happened, of the same form as -> > that returned by chrome.tabs.get. - -**chrome.contextMenu.remove**(id); - -> Removes an extension menu item with the given id. - -**Examples** - -==Define the currently selected word(s)== - -The following code would live in your background page, and you would need to -have "tabs" specified in the permissions section of your manifest. - -function getDefinition(info, tab) { - -if (!info.selectionText || info.selectionText.length == 0) { - -return; - -} - -var maxLength = 1024; - -var searchText = (info.selectionText.length <= maxLength) ? - -info.selectionText : info.selectionText.substr(0, maxLength); - -var url = "http://www.google.com/search?q=define:" + escape(searchText); - -chrome.tabs.create({"url": url}); - -} - -chrome.contextMenu.create({"title": "Define '%s'", "onclick": getDefinition, - -"contexts":\["SELECTION"\]}); - -==Remove an image from a page== - -The following code would live in your background page, and you would need to -have an entry in the permissions section of your manifest which allowed you to -run chrome.tabs.executeScript on the page where the image had its context menu -activated. This example highlights one of the limitations of the initial -proposal, which is that you don't have any way to determine the actual unique -node that was clicked on, so it removes any instances of the image from the -page. - -chrome.contextMenu.create({"title": "Remove This Image", "contexts": -\["IMAGE"\], - -"onclick": function(info, tab) { - -var frameUrl = info.frameUrl ? info.frameUrl : ""; - -var code = - -"var imgs = document.getElementsByTagName('img');" + - -"var srcUrl = unescape('" + escape(info.srcUrl) + "');" + - -"for (var i in imgs) {" + - -" var img = imgs\[i\];" + - -" if (img.src == srcUrl) {" + - -" img.parentNode.removeChild(img);" + - -" }" + - -"}"; - -chrome.tabs.executeScript(tab.id, {"allFrames": true, "code": code}); - -}}); - -****UI Design**** - -**-Extension items appear towards the bottom of the context menu, above "Inspect -element", sorted by extension name.** - -**-We will show at most one top-level menu item per extension. If an extension -adds more than 1 item, we automatically push the items into a submenu, with the -extension name as the top-level item.** - -**-The extension's icon will appear to the left of the top-level item to help -the user understand which extension added what items, and help to mitigate the -spoofing concerns raised above.** - -**[<img alt="image" -src="/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_4.png" -height=200 -width=151>](/developers/design-documents/extensions/proposed-changes/apis-under-development/context-menu-api/context_menu_api_4.png)** - -**Future Improvements** - -- Provide a mechanism for getting a handle to the precise node in the DOM where -the menu was activated. This could mean one of the following ideas: - -* Allow registration of context menus from content scripts, with a - callback function that receives a handle to the node. -* Pass the id of the node in the callback to the background page, and - if the node didn't have an id we synthesize one. -* Provide something like chrome.tabs.executeScript, where you can pass - a file or string of code to execute but also specify a function that - will be called with the node - -- Add an update(int id, object properties) method so you can change your menu -items in place. - -- Add a removeAll() method so you don't have to keep track of id's if you don't -want to. - --Add a way to limit your menu items to specific tabs or frame urls (by a given -match pattern, or perhaps automatically limit to only sites you have content -script permissions for) - --Some people have asked for a onBeforeShow() event to fire before the menu items -are displayed, but this may be infeasible given chrome's multiprocess -architecture and desire to keep the UI very responsive.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/desktop-notification-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/desktop-notification-api/index.md deleted file mode 100644 index d88f4681e8d..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/desktop-notification-api/index.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: desktop-notification-api -title: Desktop Notification API ---- - -Proposal Date - -January 2013. -Who is the primary contact for this API? - -Justin DeWitt (dewittj) - -Who will be responsible for this API? (Team please, not an individual) - -The Extensions team will own the API, but the Notifications Frontend team will -own the implementation (i.e., the actual desktop notification code) behind it. - -Overview - -This API provides rich desktop notifications to Chrome apps and extensions. - -Today, Chrome implements an [outdated version of the W3C spec for HTML5 desktop -notifications](http://www.chromium.org/developers/design-documents/desktop-notifications/api-specification). -The functionality proposed here is generally similar, but significantly more -powerful. We have yet addressed the question whether this API will replace, -enhance, or remain entirely independent of any Chrome implementation of the W3C -spec. - -Use cases - -Desktop notifications provide a convenient, non-intrusive method of notifying -users of events, particularly when those events originate from a background web -app. Today, a web app has unsatisfactory options to notify a user of important -information: - -1. Raise a JavaScript alert, which might or might not bring a - backgrounded window to the foreground. In the best case, where the - user does see the alert, the result is text-only and modal. -2. Change the window title and hope that enough of the window - (typically the tab) is prominent. An example is Gmail's "Inbox (1)" - title, originally designed to exploit the real estate available on a - background tab in a tabbed browser. -3. Try to play a sound. -4. Develop and support a native notifier application that sits in the - taskbar. - -An enumeration of specific use cases isn't needed. Today's web apps are likely -to be one of many of a user's open browser tabs, only one of which is active at -a time, any of which might have legitimate reasons to present urgent information -to the user (new mail, new instant message, completion or failure of -long-running process, scheduled reminders). - -Do you know anyone else, internal or external, that is also interested in this -API? - -Yes. -Could this API be part of the web platform? - -Yes. - -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? - -We expect many more notification layouts in the near future, as well as more -structured data supporting those layouts. Our hope is to design a flexible API -that will accommodate those changes without breaking the API or substantially -altering its shape. - -**If multiple extensions used this API at the same time, could they conflict with each other? If so, how do you propose to mitigate this problem?** -Our "message center," which is the container that will display notifications, -will intelligently manage the stream of notifications produced by API consumers. -It will also give control to users in the form of per-app mute, a global on/off -switch, and quiet hours. As no app or extension should be able to control these -settings, they won't be part of the API. -List every UI surface belonging to or potentially affected by your API: - -We'll separately mail out our message-center mocks. For purposes of this -document, a notification area or taskbar item in the host OS will expand to -display a rectangular message center. We don't expect the UI of Chrome proper to -change. -**Actions taken with extension APIs should be obviously attributable to an -extension. Will users be able to tell when this new API is being used? How?** - -Users can currently attribute a notification to a particular extension by -right-clicking on it. This names the extension and gives the user the ability to -disable notifications from the extension. - -How could this API be abused? - -* Idle detection. Raise a notification and see whether the user - dismisses it. -* Create a large number of notifications in a short period of time. -* Create a large number of notifications over a long period of time. -* Raise a notification scaring the user ("Warning, system compromised, - unplug from wall immediately"). -* Raise a notification embarrassing the user during a presentation - ("Test results received from Fungus-B-Gone Clinic"). We have - implemented a mode "Quiet Mode" that prevents new notifications from - being displayed on screen to mitigate this. -* Raise a notification demanding credentials, then steal them. Because - the notification appears to originate outside Chrome, it might carry - more clout than a typical evil website's phishing plea. -* Impersonate another app or extension. - -Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more): - -1. Pretend to be Gmail. Use the Gmail icon. Put up a notification that - sends the user to a malware site that steals Gmail credentials. -2. Send just enough inane notifications that the user gives up and - disables notifications entirely. The user is known to be an oncall - ops person at a targeted company. Destroy the company's servers and - use the delay caused by the lost notifications to escape the - country. -3. Pretend to be an instant-message service. Send "Becky: what's our - bank account #? I don't have it handy. \[Reply\]" All you need is - one husband in a hurry whose wife is named Becky for this attack to - be profitable. (This is really the same as #1; I'm out of ideas.) - -What security UI or other mitigations do you propose to limit evilness made -possible by this new API? -For the impersonation case, see answer to the "obviously attributable" question. -For local DOSing, see answer to the conflicting extensions question. -**Alright Doctor, one last challenge:** -**Could a consumer of your API cause any permanent change to the user’s system -using your API that would not be reversed when that consumer is removed from the -system?** - -No. - -How would you implement your desired features if this API didn't exist? - -We'd use the existing desktop notification API, which unfortunately is reducing -its feature set (no HTML layout option). Or we'd advise applications to use -something like Growl, which wouldn't work on ChromeOS. - -**Draft Manifest Changes** - -A "notifications" permission, which is merged with the [existing -**notifications** -permission](http://developer.chrome.com/extensions/declare_permissions.html) -that enables HTML5 desktop notifications without a runtime permissions check. - -**Draft API spec** -**Note that this API approximately matches what's in the [Chromium repository](https://code.google.com/searchframe#OAMlx_jo-ck/src/chrome/common/extensions/api/experimental_notification.idl&exact_package=chromium&l=5). The source code is authoritative.** - -```none -namespace notifications { enum TemplateType { // icon, title, message simple, // icon, title, message, expandedMessage, up to two buttons basic, // icon, title, message, expandedMessage, image, up to two buttons image, // icon, title, message, items, up to two buttons list }; dictionary NotificationItem { // Title of one item of a list notification. DOMString title; // Additional details about this item. DOMString message; }; dictionary NotificationButton { DOMString title; DOMString? iconUrl; }; dictionary NotificationOptions { // Which type of notification to display. TemplateType type; // Sender's avatar, app icon, or a thumbnail for image notifications. DOMString iconUrl; // Title of the notification (e.g. sender name for email). DOMString title; // Main notification content. DOMString message; // Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero // is default. long? priority; // A timestamp associated with the notification, in milliseconds past the // epoch (e.g. Date.now() + n). Currently unimplemented, but planned for // a forthcoming release. double? eventTime; // Text and icons of the notification action button. NotificationButton[]? buttons; // Image thumbnail for image-type notifications DOMString? imageUrl; // Items for multi-item notifications. NotificationItem[]? items; }; callback CreateCallback = void (DOMString notificationId); callback UpdateCallback = void (boolean wasUpdated); callback DeleteCallback = void (boolean wasDeleted); interface Functions { // Creates and displays a notification having the contents in |options|, // identified by the id |notificationId|. If |notificationId| is empty, // |create| generates an id. If |notificationId| matches an existing // notification, |create| first deletes that notification before proceeding // with the create operation. |callback| returns the notification id (either // supplied or generated) that represents the created notification. static void create(DOMString notificationId, NotificationOptions options, CreateCallback callback); // Updates an existing notification having the id |notificationId| and the // options |options|. |callback| indicates whether a matching notification // existed. static void update(DOMString notificationId, NotificationOptions options, UpdateCallback callback); // Given a |notificationId| returned by the |create| method, clears the // corresponding notification. |callback| indicates whether a matching // notification existed. static void clear(DOMString notificationId, DeleteCallback callback); }; interface Events { // The notification closed, either by the system or by user action. static void onClosed(DOMString notificationId, boolean byUser); // The user clicked in a non-button area of the notification. static void onClicked(DOMString notificationId); // The user pressed a button in the notification. static void onButtonClicked(DOMString notificationId, long buttonIndex); };}; -```
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/downloads-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/downloads-api/index.md deleted file mode 100644 index 189d37f703a..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/downloads-api/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: downloads-api -title: Downloads API ---- - -The downloads extension API draft proposal is available at <http://goo.gl/6hO1n>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/executecontentscript-proposal/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/executecontentscript-proposal/index.md deleted file mode 100644 index 31afa8141aa..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/executecontentscript-proposal/index.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: executecontentscript-proposal -title: executeScript() and executeCSS() ---- - -### Problem - -Sometimes, extension developers don't need to execute content script in a page -until some event happens in the extension. It is wasteful to execute content -script in every web page on the off chance that this event will happen. - -For example, consider an extension that wants to translate web pages. There will -be a button in the UI that enables translation. When this button is pressed, the -DOM needs to be crawled, collecting text nodes, and concatenating them for -translation. However, it would be nice to avoid running content scripts until -this button is pressed. - -### Proposal - -chrome.tabs - -// Executes JavaScript in the root frame of a tab. The script is executed in the -same type of - -// sandbox that content scripts are. - -// - -// Each time this method is called a new sandbox is created to run the script -and the sandbox - -// persists following the usual rules of GC. This isn't particularly -heavyweight, but it also - -// isn't something you'd want to do in a loop. - -// - -// If you need lots of small communication with a tab, consider executing script -once and - -// then using content script messaging to communicate between that script and -the extension. - -// - -// tabId: Optional, defaults to selected tab of the current window (as -determined by - -// chrome.windows.getCurrent()). - -// js: Optional, string of JavaScript to execute. - -// js_files: Optional, array of JavaScript files to execute, in order. - -// callback: Optional, callback to invoke with result of execution (result of -last statement). - -// - -// If the extension does not have access to interact with the URL in the -specified tab, or if a - -// js file is specified that does not exist, an error is reported to the console -associated with the - -// view that called the API. Execution errors in the script are reported to the -console associated - -// with the tab. - -void **executeScript**(\[int tabId\], {\[string js\], \[string\[\] js_files\]}, -\[callback onSuccess(Object result)\]); - -// Applies CSS to the root frame of a tab. - -// - -// tabId: Optional, defaults to selected tab of the current window (as -determined by - -// chrome.windows.getCurrent()). - -// css: Optional, string of CSS to execute. - -// css_files: Optional, array of CSS files to execute, in order. - -void **insertCSS**(\[int tabId\], {\[string css\], \[string\[\] css_files\]}); - -Example - -chrome.tabs.executeScript(null, {js_files: \["jquery/min.js", "woo.js"\]}); - -### Details - -* When we implement permissions, this API should fail if the extension - doesn't have access to the page loaded into the tab. -* No attempt is made to dedupe these. Each time you call the API, the - script gets executed again. Callers need to maintain state if they - don't want to execute duplicate scripts. -* Executing script in subframes is not supported.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/font-settings/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/font-settings/index.md deleted file mode 100644 index 7c8bd8863a3..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/font-settings/index.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: font-settings -title: Font Settings ---- - -Font Settings API is now stable! See the -**[chrome.fontSettings](http://developer.chrome.com/stable/extensions/fontSettings.html) -documentation.** - -Proposal Date -Jan 17, 2012 - -Who is the primary contact for this API? -*@)*Matt Falkenhagen (falken -Who will be responsible for this API? (Team please, not an individual) - -Chrome Tokyo team / Chrome i18n team - -Overview -Expose Chrome/WebKit font preferences to extensions, much like the Proxy Settings API. -Use cases -We want to add a more advanced font settings UI than is currently available, and -it might be decided that it should be an extension in interest of keeping the -Chrome UI simple. - -Specifically, Chrome/WebKit recently added per-script font settings, so e.g., -the "sans-serif" font setting for Simplified Chinese script can be different -than the one for Traditional Chinese, or Japanese, etc. We want users to have -access to these preferences. This is [crbug.com/2685](http://crbug.com/2685). - -Furthermore, there are other font settings not currently exposed in the UI, such -as for fantasy and cursive fonts. This API would allow extensions for those -settings. - -Do you know anyone else, internal or external, that is also interested in this -API? -No. -Could this API be part of the web platform? -No, this is simply client-side Chrome/WebKit settings. I don't see how it could be part of the web platform. -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -Yes, it will be fairly stable, only changing when the underlying Chrome/WebKit -settings change. Some reasons it may change are: - -* It could be extended if support for additional scripts or CSS font - families is needed. -* The per-script settings may be extended to be per-script+language. - For example, Farsi/Persian may need to use a different font than the - one for Arabic language although both are written in Arabic script. -* Some settings like default font size, default fixed font size, - minimum font size that are currently global settings may become - per-script settings in the future. -* We could also add more parameters like font settings for certain URL - patterns. - -List every UI surface belonging to or potentially affected by your API: -Since it's exposing Chrome/WebKit font settings, it should affect only the web -content renderer. These settings are not used in native UI surfaces to my -knowledge. - -How could this API be abused? -Describe any concerns you have with exposing this API. Particular attention -should be given to issues of security, privacy and performance. - -Since Chrome observes font settings changes and propagates them to WebKit, which -redraws as necessary, maybe an extension can cause performance disruptions. - -Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more): -1) An extension that trashes the font settings. Uninstalling the extension would -undo the damage. - -2) An extension that rapidly keeps changing the fonts. It could conceivably be a -DOS attack as WebKit tries to keep up. 3) An extension that reads font settings -and uploads to a server to try to build a database fingerprinting users by the -font settings. Also, if the API exposes a list of fonts installed on the system, -it can also be a source of information for fingerprinting. See: -<http://trac.webkit.org/wiki/Fingerprinting> - -Alright Doctor, one last challenge: -Could a consumer of your API cause any permanent change to the user’s system -using your API that would not be reversed when that consumer is removed from the -system? - -No. It just uses the standard [extension-controlled -preferences](http://www.chromium.org/developers/design-documents/preferences#TOC-Extension-Controlled-Preferences) -feature which handles cleanup when the extension is uninstalled. - -How would you implement your desired features if this API didn't exist? -It could be part of the built-in Settings UI instead of relying on extensions. -Draft API spec -For the appropriate style, please refer to [existing -APIs](http://code.google.com/chrome/extensions/docs.html) as well as the [other -API proposals](/developers/design-documents/extensions/). -For example, note that API calls that affect the browser process must be -asynchronous, to prevent extension JavaScript from blocking on the browser UI. -See the [current API -spec](http://code.google.com/chrome/extensions/trunk/experimental.fontSettings.html) -on trunk documentation. - -Originally I planned to use -[ChromeSetting](http://code.google.com/chrome/extensions/types.html#ChromeSetting) -to expose all preferences, but there would be too many of them (about 30 scripts -with 6 font families each...). - -Open questions -Note any unanswered questions that require further discussion. - -There was a possibility of putting per-script and other advanced font settings -in the built-in UI, but to keep Chrome UI simple this is unlikely to happen.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/get-extension-views-by-type-proposal/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/get-extension-views-by-type-proposal/index.md deleted file mode 100644 index c7acbc4dbc6..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/get-extension-views-by-type-proposal/index.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: get-extension-views-by-type-proposal -title: Get Views by Type ---- - -### Problem - -Right now we have chrome.extension.getViews() which returns a list of all active -views (toolstrips, tab contents, the background page) in the extension. This is -cool, but you also frequently need to get all views of a certain type. For -example, all toolstrips, or just the background page. Also, people frequently -want to get the toolstrips associated with a particular window. - -### Proposal - -chrome.extension - -// Returns an array of DOMWindows for the toolstrips running in the current -extension. - -// - -// windowId: optional. If specified only returns toolstrips from that window. If - -// omitted, defaults to the current window as defined by -chrome.windows.getCurrent(). - -// Can also be the string "all", in which case all toolstrips in all windows -will be - -// returned. - -DOMWindow\[\] **getToolstrips**(\[int-or-string windowId\]); - -// Returns an array of DOMWindows for any tabs running in the current extension. - -// - -// windowId: optional. If specified only returns toolstrips from that window. If - -// omitted, defaults to the current window as defined by -chrome.windows.getCurrent(). - -// Can also be the string "all", in which case all toolstrips in all windows -will be - -// returned. - -DOMWindow\[\] **getTabs**(\[int-or-string windowId\]); - -// Returns the DOMWindow for the extension's background page, or null if the -extension - -// doesn't have a background page. - -DOMWindow **getBackgroundPage**(); - -### Example - -// Assuming the extension has a background page and has a global function called -"foobar". - -chrome.extension.getBackgroundPage().foobar();
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/gleam-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/gleam-api/index.md deleted file mode 100644 index 68c22cc535d..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/gleam-api/index.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: gleam-api -title: Gleam API ---- - -## Overview - -Extension developers often want a way to offer contextual actions with different -parts of a web page. For example: - -* The Skype extension would like to offer to make calls to phone - numbers in the text of a page -* Many extensions would like to offer to download or edit embedded - images and video -* Annotation extensions would like to offer to act on the current - selection, and to highlight passages of text in a web page - -The Gleam API would allow extension developers to do these things, in a way -that: - -* Cannot slow down page load -* Cannot break the rendering of web pages -* Simplifies handling all the tricky edge cases in dynamic pages that - add, edit, and remove nodes at runtime -* Offers a nice, consistent UI that users will understand and that - allows multiple extensions to interact nicely without conflict - -## Status - -Proposal - -## Details - -Extensions can register interest in several different types of objects: - -* Images -* Plugins -* Video (the <video> tag) -* Links -* Text -* Selection - -Gleams are registered in the manifest, and multiple gleams can be registered -per-extension. If an extension is only interested in a subset of objects of a -given type on the page, they can be filtered with optional filter declarations -in the manifest or a filter function. - -Once an object has been selected by at least one extension, it is visually -highlighted by Chrome. For most types, the available actions wouldn't be visible -on an object by default, only a highlight indicating that some actions are -available. When the user hovers over the object, buttons for the available -actions are rendered. When a Gleam is invoked, a callback is fired in the -extension with details of the invoked Gleam and the relevant object. - -<todo: need mocks!> - -## Manifest - -{ - -... - -"gleam": \[ - -{ - -"type": "image" | "plugin" | "video" | "link" | "text" | "selection", - -"id": <string>, /\* a unique ID (within this extension) for the gleam \*/ - -"name": <string>, /\* the name to display in the UI \*/ - -"icon": <path>, /\* A path to an icon to display in the UI \*/ - -"regexp": <string>, /\* optional, only valid for type "text". a regexp -that filters text objects before invoking the filter function \*/ - -"content-types": <string\[\]> /\* optional, only valid for types "image", -"plugin", and "video". an array of content-types to filter to \*/ - -"filter": <string>, /\* optional, an expression that evaluates to a -function to use to filter objects to select \*/ - -"callback": <string> /\* an expression that evaluates to a function to -call when the gleam is invoked \*/ - -} - -\] - -... - -} - -## Filters - -Each page action can specify an optional filter. The filter is a string that -should evaluate to a JavaScript function. The function is called for each object -found that matches the specified type and any applicable declarative filters. - -The filter callback receives an object with the following properties: - -String id // The ID of the gleam that a matching object was found for. - -String documentUrl // The URL of the document the object was found on. - -int tabId // The ID of the tab the object was found on. - -String contentType // The content type of the matching object. Only valid for -image, video, and plugin. - -String url // The URL of the object. Only valid for image, video, and link - -String text // The text of the object. Only valid for text and link. - -int width // The width of the object, if known. Only valid for image, video, and -plugin - -int height // The height of the object, if known. Only valid for image, video, -and plugin - -For all types except text, the filter callback should return a boolean -indicating whether the object should be selected. For type text, the filter -callback should return an array of begin/end pairs indicating the ranges inside -the text that should be selected. - -Note that extension developers may choose to never select any objects if they -are only interested in knowing about certain types of objects on the page, not -performing actions on them. - -## Callbacks - -Each action must specify a callback. The callback is a string that should -evaluate to a JavaScript function. The function is called when the gleam is -invoked by the user. The parameters to the callback are the same as the -parameters to the filter (see above), and there is no return value. - -## Extra Details - -One of the neat things about this API is that we describe "objects" at a higher -level than DOM nodes. So Chrome gets to decide how to translate the DOM into -these "objects". We have an opportunity to really reduce complexity for -developers by doing these translations smartly. - -* For type "image", we shouldn't send images that are very small, or - off screen. These are layout-related, most likely, and not useful to - users. -* For type "text", we should construct a text string for entire - paragraphs at a time, removing all inline formatting tags, links, - etc. This is very difficult to do correctly and we can save - developer lots of work and bugginess by doing it for them. When the - extension returns ranges, we translate these back into the DOM tree. - This is hard, but we have all the data necessary to do it. Extension - developers don't because it isn't surfaced through DOM APIs. This - also means that we need to track tree changes so that we can - invalidate filters requests that are outstanding. -* We could add other high-level objects in the future, like - "phone-number" and "address". (thanks erikkay for the idea!)
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/history-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/history-api/index.md deleted file mode 100644 index 184dc19ccdf..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/history-api/index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: history-api -title: History API ---- - -history. - -void search(HistoryQuery query, void callback(HistoryItem\[\] results)) - -void clear(HistoryQuery query) // defaults to clearing all. Should we prompt? - -// NOTE: these could be done in a v2 -- I don't see huge use cases for them, -except perhaps for synchronization. - -void create({int date, string url, string title, \[string favIconUrl\], \[int -fromId\]}, \[void callback(HistoryItem result)\]) - -event onHistoryItemCreated(HistoryItem new) - -event onHistoryItemRemoved(HistoryItem removed) - -struct HistoryItem { - -int id - -int date - -string url - -string title - -string favIconUrl - -int fromId - -int totalVisitCount - -int totalTypedCount - -} - -struct HistoryQuery { - -// limited to 100, defaults to current day. - -optional int\[\] ids - -optional string search - -optional Date startDate - -optional Date endDate - -}
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/i18n-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/i18n-api/index.md deleted file mode 100644 index 85385d27b5e..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/i18n-api/index.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: i18n-api -title: i18n-api ---- - -### Overview - -The i18n API allows you to manipulate the i18n related browser settings, such as -the accept languages. (Note: since the first version will only implement the -access of accept languages, this document will focus on accept languages below.) - -### Use cases - -It allows extensions to read and write the browser's i18n related settings. -Given accept languages as an example, page translation extension and dictionary -extension will need to get the accept languages from the browser and use them as -the targeted languages for page or word translation. - -### Could this API be part of the web platform? - -Given accept languages as an example, read accept languages could be part of the -web platform, it could be exposed by window.navigator.acceptLanguages while UI -language is exposed through widow.navigator.language. But we would also like to -be able to modify accept languages preferences as well by extension, for -example, it'd be nice if we could "learn" the accept-languages through -translate, such as if you decline to translate a French page, that would be a -good signal that you want it added to the accept-languages. - -### Do you expect this API to be fairly stable? - -Yes*.* - -### What UI does this API expose? - -None*.* - -### How could this API be abused? - -Read accept languages should be OK. - -### Are you willing and able to develop and maintain this API? - -Yes*.* - -### Draft API spec - -## chrome.i18n. - -## void getAcceptLanguages(void callback(String acceptLanguages)) - -## void setAcceptLanguages(Value newAcceptLanguages) - -## void appendAcceptLanguage(Value acceptLanguage) - -### Notes - -The first version will only implement the access of accept languages. - -### Issues - -* Any issues with modifying the browser's accept languages through - extension API?
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/index.md deleted file mode 100644 index a92c0ec5962..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -page_name: apis-under-development -title: API Proposals (New APIs Start Here) ---- - -This page has moved to -<https://chromium.googlesource.com/chromium/src/+/HEAD/extensions/docs/new_api_proposal.md>.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/input-method-editor/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/input-method-editor/index.md deleted file mode 100644 index ff5641ca2de..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/input-method-editor/index.md +++ /dev/null @@ -1,452 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: input-method-editor -title: Input Method Editor ---- - -Overview -The purpose of this API is to allow third parties to develop IMEs for Chrome OS -via extensions. -Use cases -This API would be used to create IMEs that aren’t included in Chrome OS. This -could include Cloud IME solutions, alternate CJK IMEs, or English IMEs and -writing assistants. -There are three basic types of input we should support: - -* Text Generators: Generates a block of text to input into a text - window. Voice Input is an example of this. -* Keystroke Generators: Generates distinct keystroke, which are passed - to the active IME. Virtual Keyboard and Handwriting inputs are - examples of this. -* IMEs: Manages the candidate window, composition, and processes key - events. - -An input method extension can behave as any or all of these, but only a single -extension can be active as an IME at a time. -Could this API be part of the web platform? -This is a client side feature, and doesn’t make much sense to add to HTML5 -Do you expect this API to be fairly stable? -Once finalized, I don’t expect this API to change in any way that would break -backwards compatibility. - -What UI does this API expose? -On ChromeOS, the user interacts with this API through the IME selection button, -and the candidate window. As such, no new UI would need to be added. To -implement this API on Windows, Mac and Linux, an IME selection method would need -to be added, and the candidate window would need to be exposed. -Candidate Window<img alt="image" -src="https://lh6.googleusercontent.com/GPuIhveTIycZtycoRX-UpMyjUtTbRagxaFBSumy_lXMm_Jk5XrwNC2c7MDZMY_dsVhIu8yqUXC62eTajN4evCvBJqAbeBa9inZc0EHPEDrEdh7AQzRbIGjlF4p5Q4bM" -height=273px; width=372px;> -Language Selection<img alt="image" -src="https://lh4.googleusercontent.com/mI9f05co5OXWt9epa7Q7dXh0jAqPwaySZ94CI_PlzahEQvMHt0uHupj_gXhIfoMK0DPd0LKqEDie3zEz_EwFbVPAYmKCMKDHsu_x4Vp5oDlGXOufP6iC1sJMF3YGomY" -height=305px; width=337px;> -How could this API be abused? -The biggest danger of this API is that it could easily be used to create key -loggers. Android deals with this issue by adding additional security dialogs to -enable third party IMEs. The danger is mitigated slightly by the fact that -password dialogs do not send their keystrokes to IME. Extensions that generate -keystrokes such as virtual keyboards will still be able to send keystrokes to -password fields and could record this data, however. -This should be protected by both the standard security warning during -installation, and an additional warning/confirmation dialog when enabled for the -first time. -How would you implement your desired features if this API didn’t exist? -There is currently no way for third parties to add IMEs to Chrome OS. Allowing -IMEs executing in any other context than sandboxed Javascript seems much more -dangerous from a security standpoint. -Are you willing and able to develop and maintain this API? -Yes. - -Draft API spec -To prevent abuse of IMEs, the API will be guarded by the “ime” permission in -manifest.json. - -Manifest Entries: - -To use the ime.engine APIs, you need to specify an input_components entry in the -manifest. It will contain an array describing any input components in the -extension. - -It should look like: - -"input_components" = \[ - -{ - -"name": "My IME", // A user visible name. - -"type": "ime", // The type of input component. - -"id": "my_ime", // The id that will be passed to callbacks - -"description": "My Input method for Japanese", // A user visible description - -"language": "ja", // The primary language this IME is used for - -"layouts": {"jp::jpn", "us:dvorak:eng"} // The supported keyboard layouts for -this IME - -} - -\] - -Types: - -* MenuItem (Object) - * id (String) - * label (optional String) (default: “”) - * style (optional Integer) - Enum representing if this item is: - None, Check, Radio, or a Separator. Radio buttons between - separators are considered grouped. - * visible (optional Boolean) (default: true) - * enabled (optional Boolean) (default: true) - * checked (optional Boolean) (default: false) - * children (optional Array of MenuItem) -* KeyboardEvent (Object) - See - <http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent> - * type (String) - One of 'keyup' or 'keydown'. - * key (String) - Value of the key being pressed - * altKey (optional Boolean) - Whether or not the ALT key is - pressed. - * ctrlKey (optional Boolean) - Whether or not the CTRL key is - pressed. - * shiftKey (optional Boolean) - Whether or not the SHIFT key is - pressed. -* InputContext (Object) - * textID (Integer) - This is used to specify targets of text field - operations. This ID becomes invalid as soon as onBlur is called. - * type (String) - Type of value this text field edits, (Text, - Number, Password, etc) - -Methods: -chrome. - -****input.ime**** - -.setComposition** - -* Description - * Set the current composition. If this extension does not own the - active IME, this fails. -* Parameters - * Object - * contextID (Integer) - ID of the context with the composition - text. This is the value provided in the InputContext from - onFocus. - * text (String) - * selectionStart (optional Integer) - Position in the text - that the selection starts at. - * selectionEnd (optional Integer) - Position in the text that - the selection ends at. - * cursor (Integer) - Position in the text of the cursor - * segments (optional Array) - List of segments and their - associated types. - * Object - * start (Integer) - * end (Integer) - * style (String) - \[underline, doubleUnderline\] This - is an enum that indicates what type this segment is. - * callback (optional Function(Boolean success) {} ) - Called when - the operation completes. success indicates whether the operation - succeeded, on failure, chrome.extension.lastError is set. - -chrome. - -********input******** - -****.ime**** - -.clearComposition** - -* Description - * Clear the current composition. If this extension does not own - the active IME, this fails. -* Parameters - * Object - * contextID (Integer) - ID of the context with the composition - text. This is the value provided in the InputContext from - onFocus. - * callback (optional Function(Boolean success) {} ) - Called when - the operation completes. success indicates whether the operation - succeeded, on failure, chrome.extension.lastError is set. - -chrome. - -********input******** - -****.ime**** - -.commitText** - -* Description - * Commits the provided text to the current input. -* Parameters - * Object - * contextID (Integer) - ID of the context where the text will - be committed. - * text (String) - * callback (optional Function(Boolean success) {}) - Called when - the operation completes with a boolean indicating if the text - was accepted or not. on failure, chrome.extension.lastError is - set. - -chrome. - -********input******** - -****.ime**** - -.setCandidateWindowProperties** - -* Description - * Sets the properties of the candidate window. This fails if the - extension doesn’t own the active IME -* Parameters - * Object - * engineID (String) - * properties (Object) - * visible (optional Boolean) - True to show the Candidate - window, false to hide it. - * cursorVisible (optional Boolean) - True to show the - cursor, false to hide it. - * vertical (optional Boolean) - True if the candidate - window should be rendered vertical, false to make it - horizontal. - * pageSize (optional Integer) - The number of candidates - to display per page. - * auxiliaryText (optional String) - Text that is shown at - the bottom of the candidate window. - * auxiliaryTextVisible (optional Boolean) - True to - display the auxiliary text, false to hide it. - * callback (optional Function(Boolean success) {}) - Called when - the operation completes. - -chrome. - -********input******** - -****.ime**** - -.setCandidates** - -* Description - * Sets the current candidate list. This fails if this extension - doesn’t own the active IME -* Parameters - * Object - * contextID (Integer) - * candidates (Array) - * item (Object) - * candidate (String) - * id (Integer) - User defined id that will be used to - identify this candidate. It must be unique in the - current list of candidates. - * label (optional String) - * annotation (optional String) - * candidates (Array of items) - Sub-candidates - * callback (optional Function(Boolean success) {}) - Called when - the operation completes. - -chrome. - -********input******** - -****.ime**** - -.setCursorPosition** - -* Description - * Set the position of the cursor in the candidate window. This is - a no-op if this extension does not own the active IME. -* Parameters - * Object - * contextID (Integer) - * candidateID (Integer) - ID of the candidate to select. - * callback (optional Function) - Called when the operation - completes - -chrome. - -********input******** - -****.ime**** - -.setMenuItems** - -* Description - * Adds the provided menu items to the language menu when this IME - is active. -* Parameters - * Object - * engineID (String) - ID of the engine to use - * items (array of MenuItem) - MenuItems to add. They will be - added in the order they exist in the array. - * callback (optional Function) - Called when the operation - completes - -chrome. - -********input******** - -****.ime**** - -.updateMenuItems** - -* Description - * Updates the state of the MenuItems specified -* Parameters - * Object - * engineID (String) - ID of the engine to use - * item (MenuItem or array of MenuItem) - One or more MenuItems - to update. - * callback (optional Function) - Called when the operation - completes - -chrome. - -********input******** - -****.ime**** - -.sendKeyEvent** - -* Description - * Sends a keystroke to the system -* Parameters - * Object - * contextID (Integer) - ID of the context with the composition - text. - * key (KeyEvent) - Key data to send - * callback (optional Function) - Called when the operation - completes - -Events -chrome. - -********input******** - -****.ime**** - -.onActivate** - -* Description - * This event is sent when an IME is activated. It signals that the - IME will be receiving onKeyPress events. -* Parameters - * engineID (String) - ID of the engine receiving the event - -chrome. - -********input******** - -****.ime**** - -.onDeactivated** - -* Description - * This event is sent when an IME is deactivated. It signals that - the IME will no longer be receiving onKeyPress events. -* Parameters - * engineID (String) - ID of the engine receiving the event - -chrome. - -********input******** - -****.ime**** - -.onFocus** - -* Description - * This event is sent when focus enters a text box. It is sent to - all extensions that are listening to this event, and enabled by - the user. -* Parameters - * context (InputContext) - an InputContext object describing the - text field that has acquired focus. - -chrome. - -********input******** - -****.ime**** - -.onBlur** - -* Description - * This event is sent when focus leaves a text box. It is sent to - all extensions that are listening to this event, and enabled by - the user. -* Parameters - * contextID (Integer) - the ID of the text field that has lost - focus. The ID is invalid after this call - -chrome. - -********input******** - -****.ime**** - -.onInputContextUpdate** - -* Description - * This event is sent when the properties of the current - InputContext change, such as the the type. It is sent to all - extensions that are listening to this event, and enabled by the - user. -* Parameters - * context (InputContext) - an InputContext object describing the - text field that has changed. - -chrome. - -********input******** - -****.ime**** - -.onKeyEvent** - -* Description - * This event is sent if this extension owns the active IME. -* Parameters - * engineID (String) - ID of the engine receiving the event - * keyData (KeyEvent) - Data on the key event -* Return value - * handled (Boolean) - True if the keystroke was handled, or false - if it should be - -chrome. - -********input******** - -****.ime**** - -.onCandidateClicked** - -* Parameters - * engineID (String) - ID of the engine receiving the event - * candidateID (Integer) - ID of the candidate that was clicked. - * button (String) -\[left, right, middle\] Which mouse buttons was - clicked. - -**chrome.** - -******input****** - -**.ime.onMenuItemActivated** - -* Parameters - * engineID (String) - ID of the engine receiving the event - * name (String) - Name of the MenuItem which was activated - -**Open questions**
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/instructions-for-api-shepherds/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/instructions-for-api-shepherds/index.md deleted file mode 100644 index 0ef7ae8c214..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/instructions-for-api-shepherds/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: instructions-for-api-shepherds -title: '[Deprecated] Instructions for API launch engineers' ---- - -## [API -launch](/developers/design-documents/extensions/proposed-changes/apis-under-development) -no longer utilizes launch engineers.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/language-detection/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/language-detection/index.md deleted file mode 100644 index c23e6982d8d..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/language-detection/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: language-detection -title: Language Detection for chunks of text ---- - -## Overview - -## Add a new chrome.i18n.detectLanguage that enables CLD language detection for a chunk of user-supplied text. - -## Use cases - -## This API would be useful for extensions that want to translate parts of a page that are in a different language than the page itself. This is also useful in implementing an extension that translates user-supplied text (in a gadget, for example) into a language of the user’s choice, without needing to rely on an external server for language detection of the text. The existing chrome.tabs.detectLanguage API only provides language detection on a page-level granularity. - -## Could this API be part of the web platform? - -## No, this is intended to fill in a functionality gap with an existing chrome extension API, and not to introduce new web standards. - -## Do you expect this API to be fairly stable? - -## The set of languages that can be detected by the CLD may change over time, which affects the results of this function in a similar way as chrome.tabs.detectLanguage. - -## What UI does this API expose? - -## None. - -## How could this API be abused? - -## There’s nothing obvious that could be abused here. - -## How would you implement your desired features if this API didn't exist? - -## The only way to detect the language of a chunk of text from a page right now would be to transmit the text to a third party server and wait for a reply. This is not desirable as it introduces privacy concerns about sending text scraped from parts of a page to a server before a user explicitly requests they be translated. - -## Are you willing and able to develop and maintain this API? - -## Yes. - -## Draft API spec - -## Methods - -## detectLanguage - -## chrome.i18n.detectLanguage(string text, function callback) - -## Detects the primary language of a supplied chunk of text. Language detection is more reliable for larger chunks of text (preferably 100 characters or more), but may be able to make a determination with small chunks for languages that use unique characters, such as Arabic or Hebrew. - -## Parameters - -## text ( string ) - -## The text to analyze. - -## callback ( function ) - -## The callback parameter should specify a function that looks like this: - -## function(array of DetectedLanguage languages) {...}; - -## result ( LanguageDetectionResult ) - -## Will contain up to three languages that were detected in text. - -## Types - -## DetectedLanguage - -## ( object ) - -## language ( string ) - -## An ISO language code such as en or fr. For a complete list of languages that could be returned here, see [kLanguageInfoTable](http://src.chromium.org/viewvc/chrome/trunk/src/third_party/cld/languages/internal/languages.cc). The 2nd to 4th columns will be checked and the first non-NULL value will be returned except for Simplified Chinese for which zh-CN will be returned. - -## confidence ( integer ) - -## A value between 0 and 100, inclusive, that indicates Chrome’s percentage confidence that the supplied text is in this language. High values indicate high confidence. - -## LanguageDetectionResult - -## ( Object) - -## reliable ( boolean ) - -## True if language detection was considered reliable. This is the case when a single language emerges with a confidence value that is significantly higher than the next most likely language. - -## languages ( array of DetectedLanguage ) - -## The possible languages that were detected for the supplied text, if any. - -## Open questions - -## Is it useful to return the raw confidence numbers for each language? These may change with each new implementation of the CLD.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/managed-storage-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/managed-storage-api/index.md deleted file mode 100644 index d3fb83f71ec..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/managed-storage-api/index.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: managed-storage-api -title: Managed Storage API ---- - -**Proposal Date** - -June 27 2012 - -Who is the primary contact for this API? -joaodasilva@chromium.org -Who will be responsible for this API? - -Chrome Enterprise team: chrome-enterprise-muc@google.com, -chrome-enterprise@google.com - -Overview -This is a proposal to extend the storage API -([proposal](/developers/design-documents/extensions/proposed-changes/apis-under-development/settings), -[API](http://code.google.com/chrome/extensions/storage.html)) to add support for -managed values that can be set by an administrator, allowing the administrator -to configure extensions for their domains. - -Extensions will have a new 'managed' namespace under 'chrome.storage' that is -read-only and provides the values of the settings configured by the -administrator for that extension. - -Use cases - -Many features of Chrome can be configured using -[policies](/administrators/policy-list-3). We'd like to give administrators the -capability to further customize Chrome for their deployments by allowing them to -not only [force extensions to be -installed](/administrators/policy-list-3#ExtensionInstallForcelist), but also to -configure them. Some examples: - -* Use an extension to preconfigure bookmarks, and to keep them in sync - with a shared list retrieved using XHR -* Use an extension to block URLs, using blocklists downloaded from - other websites -* Use an extension to manipulate cookies for internal sites -* Use an extension to customize the Omnibox results for their domain -* Use an extension to periodically publish the recent history to an - internal logging server -* Use an extension to configure the proxy settings -* Use an extension to configure the privacy settings - -Many of these scenarios can be achieved by creating a custom extension with the -desired features; we'd like to simplify that by allowing generic extensions to -be configured via the policy mechanisms. - -Do you know anyone else, internal or external, that is also interested in this -API? -Administrators often post feature requests on the bug tracker, and some of them could be served by extensions. There are also management scenarios on ChromeOS that would benefit from this feature. -Could this API be part of the web platform? - -That's not planned at this stage. In the future we might consider another proposal to also manage preferences for a website, possibly through the localStorage API. -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -We expect these modified APIs to be stable and don't foresee any further -changes. They are also designed with compatibility with existing extensions in -mind. - -**If multiple extensions used this API at the same time, could they conflict with each others? If so, how do you propose to mitigate this problem?** -Each extension can only read its own stored settings, so we don't expect this to -introduce conflicts. -List every UI surface belonging to or potentially affected by your API: -This proposal does not introduce new UI. -**Actions taken with extension APIs should be obviously attributable to an -extension. Will users be able to tell when this new API is being used? How?** - -The modified APIs don't results in any browser-side actions, as they are purely -informational to the extension. The only user-visible aspect of this API is the -local storage view in the resources inspector. However, managed settings will -not be shown there, since they come from the policy system and are not persisted -in local storage. - -How could this API be abused? -This is a read-only API that is only meant to allow extensions to read managed -settings that have been set explicitly for the requesting extension. - -Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more): -No idea how this can be abused, really. -What security UI or other mitigations do you propose to limit evilness made possible by this new API? -No need for this is foreseen. -Alright Doctor, one last challenge: -Could a consumer of your API cause any permanent change to the user’s system -using your API that would not be reversed when that consumer is removed from the -system? - -No. - -How would you implement your desired features if this API didn't exist? -Administrators could roll their own extension and push an extension update when -they want to modify the extension's behavior. This isn't as flexible as the -existing policy mechanisms, and would require the developer of the extension to -roll their own policy delivery mechanism. Many administrators also don't have -the technical skills or resources to create their own extensions or to maintain -a fork of a pre-made extension. - -Another possibility would be to implement a "native" Chrome policy that supports -the administrator's use case, but it is not reasonable to introduce a new policy -for every corner case. Allowing policy to override the storage settings of some -extensions greatly broadens the customizability of Chrome for administrators. - -Draft API spec -This proposal involves a backend modification and an extension to the existing -[storage API](http://code.google.com/chrome/extensions/storage.html). - -On the backend, a new storage API implementation will be added that pulls values -from the [policy -service](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/browser/policy/policy_service.h?view=markup) -for the particular extension, when available. These values are exposed in the -'managed' namespace. The 'managed' namespace is similar to 'local' and 'sync', -but is a read-only namespace. - -The callback of -[storage.get](http://code.google.com/chrome/extensions/storage.html#method-StorageArea-get) -currently gets an object mapping a setting key to its value. It will be extended -to receive a second object that maps a setting key to an object with metadata -about that setting (existing code can still work with the first argument only). -For now, the only well-known metadata key will be "policyLevel", which takes the -value "mandatory" or "recommended". This indicates whether the administrator -would like the value to be enforced, or if it is just a suggested default that -the user can override. The metadata object can be extended in the future to -include other details (for example, the sync version). - -Other remarks: - -* Settings configured via a policy do not count towards the - extension's quota. getBytesInUse() is 0 for the 'managed' namespace. -* The extension can still set() a key that is being overridden by a - policy in another namespace. It is up to the extension to give - priority to a managed value, if it exists.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/media-gallery/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/media-gallery/index.md deleted file mode 100644 index dadfde70e0b..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/media-gallery/index.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: media-gallery -title: MediaGallery ---- - -Proposal Date - -*1/24/2012 updated 4/24/2012* - -Who is the primary contact for this API? -*Steve VanDeBogart. This document was authored by Tony Payne* - -Who will be responsible for this API? (Team please, not an individual) - -*owp-media-gallery@* - -Overview -Media and metadata access API. -Use cases -This API makes media applications much simpler and provides a standard interface -for both local and online galleries. -Do you know anyone else, internal or external, that is also interested in this -API? -This will be used in Q2 2012 by an internal application for both local -(removable media) galleries and remote galleries. At least 2 other internal -teams have expressed interest in using the API. - -Could this API be part of the web platform? -We intend to make this part of the web platform but are looking to release an -experimental extension API first for 2 reasons: 1) to meet the aggressive goals -of the internal project, 2) To vet the API before going to standards bodies. -There are existing Gallery API proposals but they do not meet our needs (provide -no metadata access and rely on synchronous APIs) - -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -As mentioned above, we don't expect to go beyond the experimental stage with -this API. For backwards compatibility, the eventual OWP API can be wrapped by -the existing experimental API. - -List every UI surface belonging to or potentially affected by your API: -*Settings: We may need a settings interface for adding and removing galleries -from the browser.* - -*Permissions: As an extension, a manifest permissions entry will be used. -However, as a web platform API, applications that have not been given permission -to access the browser's galleries will cause a permissions prompt when they -attempt to access galleries for the first time.* - -How could this API be abused? -*This API contains write and delete operations that can cause permanent data -loss.* - -*Quite a lot of attention has been given to making it easy to write well-performing applications using this API but there is always the potential for trying to keep too much data in memory, since this API gives access to a potentially enormous amount of media file data on the system and online.* -Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more): -1) Delete all media files from the system -2) Corrupt all media files on the system -3) Upload all media files on the system to an evil host - -4) Fill up the user's local drive - -5) Copy malware onto the system, hoping the user will execute it. - -Alright Doctor, one last challenge: -Could a consumer of your API cause any permanent change to the user’s system -using your API that would not be reversed when that consumer is removed from the -system? -*Yes. The MediaGallery API provides write and delete methods for making permanent changes to media files in the gallery.* -How would you implement your desired features if this API didn't exist? -*File access via existing HTML5 file APIs using a File dialog to gain permission -(this is a terrible user experience)* - -*Metadata parsing using client-side parsers. These have terrible performance* - -Draft API spec -*The current draft is in WebIDL format here: -<https://docs.google.com/a/google.com/document/pub?id=1UpwxoIBoTgrA9fLujXCirNp4NYB0Z0F0LiX_SuS9c5U> - -*The previous draft can be found here: -<https://docs.google.com/a/google.com/document/pub?id=1RsLin39Zmun9kaxNUpChL55IoEHmLHF3EU8NRy28168>* - -*We will update the draft style to match other extension APIs once we've -received more feedback.* - -Open questions -*TBD*
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/notifications-of-web-request-and-navigation/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/notifications-of-web-request-and-navigation/index.md deleted file mode 100644 index 8cecae5b3a9..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/notifications-of-web-request-and-navigation/index.md +++ /dev/null @@ -1,860 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: notifications-of-web-request-and-navigation -title: Notifications of Web Request and Navigation ---- - -## Overview - -This document describes the following API: - -* [chrome.webRequest](http://code.google.com/chrome/extensions/trunk/experimental.webRequest.html): - Monitors events of HTTP requests. -* [chrome.webNavigation](http://code.google.com/chrome/extensions/trunk/experimental.webNavigation.html): - Monitors events of navigations happening in tab content windows as - well as subframes (iframe / frame elements). - -## Use cases - -An API of detailed Web progress notifications can be used to log traffic data, -measure browser performance, etc. Please note that this requirement has been -listed in the [API Wish -List](/developers/design-documents/extensions/apiwishlist) (the Network item). - -* Configure proxy for each request. -* Modify headers (e.g. change User-Agent:). -* Block requests to certain servers. -* Log traffic data and measure performance. - -## Could this API be part of the web platform? - -To the best of my knowledge, it could not. - -## Do you expect this API to be fairly stable? - -I think the API will be fairly stable, since the way how HTTP works, as well as -how the browser handles Web page navigations, is mature and stable. However, as -described in the Open questions section, there may be some improvements in the -future. - -## What UI does this API expose? - -The API doesn’t expose any UI. - -## How could this API be abused? - -There may be privacy issues since extensions can collect detailed information -about network traffic via this API. - -## How would you implement your desired features if this API didn't exist? - -Without this API, - -* I probably cannot monitor HTTP requests. -* To monitor Web navigation events, I would use chrome.tabs.onUpdated, - chrome.{tabs,windows}.onCreated and inject content scripts to - monitor subframe navigations. But there are still things I cannot - know about, e.g., when a navigation is about to occur, accurate - timestamp of events, transition type of a navigation, etc. - -## Draft API spec - -### Manifest - -In order to use chrome.webRequest or chrome.webNavigation, the "web_progress" -permission has to be declared in the permissions section of the extension -manifest. - -Moreover, if you would like to receive extra information along with -chrome.webRequest.\* (please see the description of extraInfoSpec), you need to -add hosts (or host match patterns) to the permissions section as well. You can -only request extra information for URLs whose hosts are specified in the -permissions section. For example: - -```none -{ - "name": "My extension", - ... - "permissions": [ - "web_progress", - "http://www.google.com/" - ], - ... -} -// This isn’t allowed since it requests extra information for any URL. -chrome.webRequest.onBeforeRequest.addListener( - function(object details) { ... }, null, ["requestHeaders"]); -// This is allowed. -chrome.webRequest.onBeforeRequest.addListener( - function(object details) { ... }, {urls: ["http://www.google.com/foo*bar"]}, - ["requestHeaders"]); -// This is allowed too, since it doesn’t request any extra information. -chrome.webRequest.onBeforeRequest.addListener( - function(object details) { ... }, {urls: ["http://www.youtube.com/*"]}); -``` - -### chrome.webRequest - -#### **Events** - -#### onBeforeRequest - -```none -chrome.webRequest.onBeforeRequest.addListener( - function(object details) { ... }, RequestFilter filter, - array of string extraInfoSpec); -``` - -Fires when a request is about to occur. This is sent before any TCP connection -is made. - -**Parameters** - -***details (object)*** - -> ***requestId (integer)*** - -> > The ID of the request. Request IDs are unique within a browser session. As a -> > result, they could be used to relate different events of the same request. - -> ***url (string)*** - -> ***method (string)*** - -> > Standard HTTP method. - -> ***tabId (integer)*** - -> > The ID of the tab in which the request takes place. Set to null if the -> > request isn’t related to a tab. - -> ***type (string)*** - -> > Please refer to the request types below for detailed explanation. - -> ***timeStamp (Date)*** - -> > The time when the browser was about to make the request. - -***filter (optional RequestFilter)*** - -> Please refer to RequestFilter in the Types section for detailed explanation. - -***extraInfoSpec (optional array of string)*** - -> Extra information that needs to be passed into the callback function. Each -> element of extraInfoSpec requires a corresponding string property being added -> to the details object. Array elements can be: - - * **"blocking"** - -**#### onBeforeSendHeaders** - -**```none -chrome.webRequest.onBeforeSendHeaders.addListener( - function(object details) { ... }, RequestFilter filter, - array of string extraInfoSpec); -```** - -**Fires when an HTTP request is about to occur. This may occur after a TCP connection is made to the server, but before any HTTP data is sent. The HTTP request headers are available at this point.** - -****Parameters**** - -*****details (object)***** - -> *****requestId (integer)***** - -> > **The ID of the request. Request IDs are unique within a browser session. As -> > a result, they could be used to relate different events of the same -> > request.** - -> *****url (string)***** - -> *****timeStamp (Date)***** - -> > **The time when the browser was about to make the request.** - -*****filter (optional RequestFilter)***** - -> **Please refer to RequestFilter in the Types section for detailed -> explanation.** - -*****extraInfoSpec (optional array of string)***** - -> **Extra information that needs to be passed into the callback function. Each -> element of extraInfoSpec requires a corresponding string property being added -> to the details object. Array elements can be:** - - * ****"requestLine"**** - * ****"requestHeaders"**** - * ****"blocking"**** - -#### onSendHeaders - -```none -chrome.webRequest.onSendHeaders.addListener( - function(object details) { ... }, RequestFilter filter, - array of string extraInfoSpec); -``` - -Fires just before the headers are sent to the server (after all users of the -webrequest api had a chance to modify the request in onBeforeSendHeaders). - -**Parameters** - -***details (object)*** - -> ***requestId (integer)*** - -> > The ID of the request. - -> ***url (string)*** - -> ***timeStamp (Date)*** - -> > The time when the browser finished sending the request. - -***filter (optional RequestFilter)*** - -> Please refer to RequestFilter in the Types section for detailed explanation. - -***extraInfoSpec (optional array of string)*** - -> Extra information that needs to be passed into the callback function. Each -> element of extraInfoSpec requires a corresponding string property being added -> to the details object. Array elements can be: - - * **"requestLine"** - * **"requestHeaders"** - -#### onResponseStarted - -```none -chrome.webRequest.onResponseStarted.addListener( - function(object details) { ... }, RequestFilter filter, - array of string extraInfoSpec); -``` - -Fires when the first byte of the response body is received. For HTTP requests, -this means that the status line and response headers are available. - -**Parameters** - -***details (object)*** - -> ***requestId (integer)*** - -> > The ID of the request. - -> ***url (string)*** - -> ***ip (string)*** - -> > The server IP address that is actually connected to. Note that it may be a -> > literal IPv6 address. - -> ***statusCode (integer)*** - -> > Standard HTTP status code returned by the server. - -> ***timeStamp (Date)*** - -> > The time when the status line and response headers were received. - -***filter (optional RequestFilter)*** - -> Please refer to RequestFilter in the Types section for detailed explanation. - -***extraInfoSpec (optional array of string)*** - -> Extra information that needs to be passed into the callback function. Each -> element of extraInfoSpec requires a corresponding string property being added -> to the details object. Array elements can be: - - * **"statusLine"** - * **"responseHeaders"** - -#### onBeforeRedirect - -```none -chrome.webRequest.onBeforeRedirect.addListener( - function(object details) { ... }, RequestFilter filter, - array of string extraInfoSpec); -``` - -Fires when a server initiated redirect is about to occur. - -**Parameters** - -***details (object)*** - -> ***requestId (integer)*** - -> > The ID of the request. - -> ***url (string)*** - -> > The URL of the current request. - -> ***ip (string)*** - -> > The server IP address that is actually connected to. Note that it may be a -> > literal IPv6 address. - -> ***statusCode (integer)*** - -> > Standard HTTP status code returned by the server. - -> ***redirectUrl (string)*** - -> > The new URL. - -> ***timeStamp (Date)*** - -> > The time when the browser was about to make the redirect. - -***filter (optional RequestFilter)*** - -> Please refer to RequestFilter in the Types section for detailed explanation. - -***extraInfoSpec (optional array of string)*** - -> Extra information that needs to be passed into the callback function. Each -> element of extraInfoSpec requires a corresponding string property being added -> to the details object. Array elements can be: - - * **"statusLine"** - * **"responseHeaders"** - -#### onCompleted - -```none -chrome.webRequest.onCompleted.addListener( - function(object details) { ... }, RequestFilter filter, - array of string extraInfoSpec); -``` - -Fires when a request is completed. - -**Parameters** - -***details (object)*** - -> ***requestId (integer)*** - -> > The ID of the request. - -> ***url (string)*** - -> ***ip (string)*** - -> > The server IP address that is actually connected to. Note that it may be a -> > literal IPv6 address. - -> ***statusCode (integer)*** - -> > Standard HTTP status code returned by the server. - -> ***timeStamp (Date)*** - -> > The time when the response was received completely. - -***filter (optional RequestFilter)*** - -> Please refer to RequestFilter in the Types section for detailed explanation. - -***extraInfoSpec (optional array of string)*** - -> Extra information that needs to be passed into the callback function. Each -> element of extraInfoSpec requires a corresponding string property being added -> to the details object. Array elements can be: - - * **"statusLine"** - * **"responseHeaders"** - -#### onErrorOccurred - -```none -chrome.webRequest.onErrorOccurred.addListener( - function(object details) { ... }, RequestFilter filter); -``` - -Fires when an error occurs. - -**Parameters** - -***details (object)*** - -> ***requestId (integer)*** - -> > The ID of the request. - -> ***url (string)*** - -> ***ip (string)*** - -> > The server IP address that is actually connected to. Note that it may be a -> > literal IPv6 address. - -> ***error (string)*** - -> > The error description. - -> ***timeStamp (Date)*** - -> > The time when the error occurred. - -***filter (optional RequestFilter)*** - -> Please refer to RequestFilter in the Types section for detailed explanation. - -#### **Event order** - -For any successful request, events are fired in the following order: - -```none -onBeforeRequest -> onBeforeSendHeaders[1] -> onSendHeaders -> - (onBeforeRedirect -> onBeforeRequest -> onBeforeSendHeaders[1] -> onSendHeaders ->)* -> - onResponseStarted -> onCompleted -``` - -\[1\] Note: onBeforeSendHeaders is only fired for HTTP requests. It will not be -fired for e.g. file:/// URLs. - -The part enclosed in parentheses indicates that there may be zero or more server -initiated redirects. - -Any error that occurs during the process results in an onErrorOccurred event. -For a specific request, there is no further events fired after onErrorOccurred. - -### chrome.webNavigation - -#### **Events** - -#### onBeforeNavigate - -```none -chrome.webNavigation.onBeforeNavigate.addListener(function(object details) { ... }); -``` - -Fires when a navigation is about to occur. - -**Parameters** - -***details (object)*** - -> ***tabId (integer)*** - -> > The ID of the tab in which the navigation is about to occur. - -> ***url (string)*** - -> ***frameId (integer)*** - -> > 0 indicates the navigation happens in the tab content window; positive value -> > indicates navigation in a subframe. Frame IDs are unique within a tab. - -> ***requestId (integer)*** - -> > The ID of the request to retrieve the document of this navigation. Note that -> > this event is fired prior to the corresponding -> > chrome.webRequest.onBeforeRequest. - -> ***timeStamp (Date)*** - -> > The time when the browser was about to start the navigation. - -#### onCommitted - -```none -chrome.webNavigation.onCommitted.addListener(function(object details) { ... }); -``` - -Fires when a navigation is committed. The document (and the resources it refers -to, such as images and subframes) might still be downloading, but at least part -of the document has been received from the server and the browser has decided to -switch to the new document. - -**Parameters** - -***details (object)*** - -> ***tabId (integer)*** - -> > The ID of the tab in which the navigation occurs. - -> ***url (string)*** - -> ***frameId (integer)*** - -> > 0 indicates the navigation happens in the tab content window; positive value -> > indicates navigation in a subframe. - -> ***transitionType (string)*** - -> > Cause of the navigation. Use the same transition types as those defined for -> > [chrome.history -> > API](http://code.google.com/chrome/extensions/history.html#transition_types). - -> ***transitionQualifiers (string)*** - -> Zero or more transition qualifiers delimited by "|". Please refer to the -> qualifier values below for detailed explanation. - -> ***timeStamp (Date)*** - -> > The time when the navigation was committed. - -#### onDOMContentLoaded - -```none -chrome.webNavigation.onDOMContentLoaded.addListener(function(object details) { ... }); -``` - -Fires when the page’s DOM is fully constructed, but the referenced resources may -not finish loading. - -**Parameters** - -***details (object)*** - -> ***tabId (integer)*** - -> > The ID of the tab in which the navigation occurs. - -> ***url (string)*** - -> ***frameId (integer)*** - -> > 0 indicates the navigation happens in the tab content window; positive value -> > indicates navigation in a subframe. - -> ***timeStamp (Date)*** - -> > The time when the page’s DOM was fully constructed. - -#### onCompleted - -```none -chrome.webNavigation.onCompleted.addListener(function(object details) { ... }); -``` - -Fires when a document, including the resources it refers to, is completely -loaded and initialized. - -**Parameters** - -***details (object)*** - -> ***tabId (integer)*** - -> > The ID of the tab in which the navigation occurs. - -> ***url (string)*** - -> ***frameId (integer)*** - -> > 0 indicates the navigation happens in the tab content window; positive value -> > indicates navigation in a subframe. - -> ***timeStamp (Date)*** - -> > The time when the document finished loading. - -#### onErrorOccurred - -```none -chrome.webNavigation.onErrorOccurred.addListener(function(object details) { ... }); -``` - -Fires when an error occurs. - -**Parameters** - -***details (object)*** - -> ***tabId (integer)*** - -> > The ID of the tab in which the navigation occurs. - -> ***url (string)*** - -> ***frameId (integer)*** - -> > 0 indicates the navigation happens in the tab content window; positive value -> > indicates navigation in a subframe. - -> ***error (string)*** - -> > The error description. - -> ***timeStamp (Date)*** - -> > The time when the error occurred. - -#### onBeforeRetarget - -```none -chrome.webNavigation.onBeforeRetarget.addListener(function(object details) { ... }); -``` - -Fires when a new window, or a new tab in an existing window, is about to be -created to host a navigation. - -**Parameters** - -***details (object)*** - -> ***sourceTabId (integer)*** - -> > The ID of the tab in which the navigation is triggered. - -> ***sourceUrl (string)*** - -> > The URL of the document that is opening the new window. - -> ***targetUrl (string)*** - -> > The URL to be opened in the new window. - -> ***timeStamp (Date)*** - -> > The time when the browser was about to create a new view. - -#### **Event order** - -For a navigation that is successfully completed, events are fired in the -following order: - -```none -onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted -``` - -Any error that occurs during the process results in an onErrorOccurred event. -For a specific navigation, there is no further events fired after -onErrorOccurred. - -Note that it is possible that a new navigation occurs in the same frame before -the former navigation completes. As a result, even if a navigation proceeds -successfully, the event sequence doesn’t necessarily end with an onCompleted. - -If a navigating frame contains subframes, its onCommitted is fired before any of -its children’s onBeforeNavigate; while its onCompleted is fired after any of its -children’s onCompleted. - -### Types - -#### Request types - -How the requested resource will be used. - -* **"main_frame"**: The resource is the document of a tab content - window. -* **"sub_frame"**: The resource is the document of a subframe (iframe - or frame). -* **"stylesheet"**: The resource is a CSS stylesheet. -* **"script"**: The resource is an external script. -* **"image"**: The resource is an image (jpg/gif/png/etc). -* **"object"**: The resource is an object (or embed) tag for a plugin, - or a resource that a plugin requested. -* **"other"**: Other kinds of resource. - -#### Transition qualifier values - -Any transition type can be augmented by qualifiers, which further define the -navigation. - -* **"client_redirect"**: Redirects caused by JavaScript or a meta - refresh tag on the page. -* **"server_redirect"**: Redirects sent from the server by HTTP - headers. -* **"forward_back"**: Users use Forward or Back button to navigate - among browsing history. - -#### RequestFilter - -***(object)*** - -> ***urls (optional array of string)*** - -> > Each element is a URL or URL pattern. Please refer to [content script match -> > patterns](http://code.google.com/chrome/extensions/dev/match_patterns.html) -> > for URL pattern definition. Requests that cannot match any of the URLs will -> > be filtered out. - -> ***types (optional array of string)*** - -> > Each element is a request type described above. Requests that cannot match -> > any of the types will be filtered out. - -> ***tabId (optional integer)*** - -> > The ID of the tab in which requests takes place. - -> ***windowId (optional integer)*** - -> > The ID of the window in which requests takes place. - -## Open questions - -### Accessing request and response bodies from extensions? - -We could support extensions to specify "requestBody" element in the -extraInfoSpec array of chrome.webRequest.onBeforeRequest (or onRequestSent), so -that an extra property, requestBody, will be added to the details object passed -into the event handler. Similarly, we could support extensions to ask for -responseBody, too. - -Both requestBody and responseBody are EntityBody objects. - -#### EntityBody - -#### **Methods** - -```none -readBytes(integer length, boolean wait, function callback) -``` - -**Parameters** - -***length (integer)*** - -> How many bytes to read. - -***wait (boolean)*** - -> If wait is set to false, the browser will respond as soon as possible, -> returning the bytes it has got currently; otherwise, it won’t invoke the -> callback function until it collects enough bytes or reaches the end of the -> entity body. - -***callback (function)*** - -**Callback function** - -It should specify a function that looks like this: - -```none -function (integer actualLength, string base64EncodedData) -``` - -***actualLength (integer)*** - -> The actual number of bytes that are returned. -1 indicates the end of the -> entity body has been reached or error occurred. Please note that 0 doesn’t -> indicate the end of the entity body, if the wait parameter of readBytes() is -> set to false. - -***base64EncodedData (string)*** - -> Base64 encoded bytes. Please note that normally the string length of -> base64EncodedData is different from actualLength. - -Some issues need to be considered: - -* An important issue is how to manage the lifetime of request bodies - and response bodies properly. - -Please consider the following scenario: an extension requests responseBody to be -passed into the handler of chrome.webRequest.onCompleted. In the handler, it -calls responseBody.readBytes() to read the content. However, since events are -asynchronous, the browser fires onCompleted and proceeds immediately. If it -finishes using the response body and discards it, the call of -responseBody.readBytes() at the extension side may fail, depending on the -timing. This is undesired. -As a result, the browser has to properly manage the lifetime of request bodies -and response bodies. One possible approach is to keep track of references to -each EntityBody object (either requestBody or responseBody). An entity body -maybe be accessed by several EntityBody objects, which are passed to different -extensions. If all these EntityBody objects are no longer referenced, the -browser knows that the entity body is no long needed by any extension, and it is -safe to remove it. - -* It may be inconvenient to use an EntityBody object directly. We - could also provide helper classes. For example, define - TextEntityBody class to convert entity body to a text stream: - -```none -// entityBody is an EntityBody object, which deals with bytes. -var textEntityBody = new TextEntityBody(entityBody, ‘UTF-8’); -// textEntityBody calls entityBody.readBytes() and converts the result to text. -textEntityBody.readText(10, true, function (text, reachEnd) { - // Handle text directly. -}); -``` - -### Synchronous (blocking) notifications? - -The API proposed above is supposed to be asynchronous (non-blocking) -notifications. This is consistent with other chrome.\* APIs. More importantly, -notification publishers / consumers live in different processes. If we block the -publisher side for sending each notifications, it may hurt browser performance. - -However, in some cases we would like to affect the control flow in event -handlers. (Please note that this has been listed as a requirement on the [API -Wish List](/developers/design-documents/extensions/apiwishlist), the Navigation -Interception item.) - -Consider the following use case: in the callback function of -chrome.webRequest.onBeforeRequest we may want to cancel the request or modify -the request headers. If the notification is asynchronous, the browser fires the -notification and immediately makes the request. There is no way for extensions -to make a change. - -One possible solution is to design some functions like "installSyncOnXyzHandler" -that installs a short snippet of JavaScript to run synchronously within the -browser process for the notifications that may need synchronous responses. -However, this may not fit with the overall Chrome architecture where we want to -avoid running javascript in the browser process; and the JavaScript snippet in -the browser process might need to communicate back to the extension for some of -its decisions as well. - -Another feasible solution is to add support for browser to wait for a response -from an extension. Take chrome.webRequest.onBeforeRequest as an example, we -could reform it the extraInfoSpec parameter to accept an optional string -**"blocking".** If present, then the browser needs to be blocked and wait for a -response from the callback function. - -If blocking is present, the callback function could optionally return an object -to cancel or modify the request: - -**result (optional object)** - -> ***requestLine (optional string)*** - -> > Modified request line. - -> ***reqeustHeaders (optional string)*** - -> > Modified request headers. - -> ***cancel (optional boolean)*** - -> > Set to true to cancel the request. - -> ***redirectUrl (optional string)*** - -> > Redirects the request to a different URL (only available in onBeforeRequest -> > and onBeforeRedirect). - -The biggest concern is the impact on browser performance. We have to measure the -performance impact very carefully if we really want to make the move. - -## References - -* [DWebBrowserEvents2 Interface of - IE](http://msdn.microsoft.com/en-us/library/aa768283%28VS.85%29.aspx) -* [WinINet Status - Callback](http://msdn.microsoft.com/en-us/library/aa385121%28v=VS.85%29.aspx) -* [nsIWebProgressListener Interface of - Firefox](https://developer.mozilla.org/en/nsIWebProgressListener)
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/book_screenshot.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/book_screenshot.png.sha1 deleted file mode 100644 index bf65a6ccc99..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/book_screenshot.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -b45b3fe4ea234324c5d639063ae98f959ea40f06
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/coverflow_screenshot.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/coverflow_screenshot.png.sha1 deleted file mode 100644 index 293633ca912..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/coverflow_screenshot.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -673de30aa21afdf423ecc94ad14b105857eaedfa
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/index.md deleted file mode 100644 index a3a96e86d00..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/index.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: offscreen-tabs -title: Offscreen Tabs (experimental) ---- - -[TOC] - -## Introduction - -The chrome.experimental.offscreenTabs.\* API module allows for interacting with -multiple web pages on the screen at the same time. Example applications might -look like the [Safari’s “Top -Sites”](http://decoding.files.wordpress.com/2009/02/safari_40_beta_1.jpg) or -[Chrome’s “Most -Visited”](http://www.revthatup.com/wp-content/uploads/2011/04/chrome.jpg) page -augmented with real-time display updates and user interaction. In combination -with WebGL and its texture API capabilities the offscreen tabs module could be -used to create true 3D browser environments on the web! - -### Display - -The real-time display could be achieved by updating standard HTML <img> or -<canvas> elements while capturing snapshots of offscreen tabs with the -***toDataUrl*** method. - -### Interaction - -For interaction, we propose the ***sendMouse*** and ***sendKeyboard*** methods. -These methods could pass standard JavaScript mouse and keyboard events along -with the offscreen tab ID specifying the offscreen tab these events should be -applied to. In the case of mouse events appropriate x and y coordinates should -be passed as well. Why? Because when an application or extension is responsible -for rendering an offscreen tab's contents, only that application knows exactly -where a click against the tab's canvas is supposed to be dispatched. Once Chrome -picks up the JavaScript events new synthesized events will be sent to the -appropriate offscreen tab. Most of the fields of the synthesized events will be -the same as the ones of the incoming JavaScript events. One exception, for -example, are the x and y coordinates for mouse events as explained above. - -### Window Size - -Since the offscreen tabs will not be displayed by the browser in separate tabs -the developer has to explicitly specify width and height of each offscreen tab's -window. - -## Manifest - -The module requires the specification of an *offscreenTabs* permission type. -This permission would enable the API to see all web sites' user data. The -developer will have to declare the *offscreenTabs* permission in the [extension -manifest](http://code.google.com/chrome/extensions/manifest.html). For example: -**{** -**"name": "My extension",** -**...** -**"permissions": \[** -**"offscreenTabs"** -**\],** -**...** -**}** - -## Example Extensions - -Above you can see a video of a Chrome extension we have developed with the -Offscreen Tab API and WebGL. Here are some additional screenshots: - -[<img alt="image" -src="/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/book_screenshot.png" -height=220 -width=400>](/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/book_screenshot.png) - -[<img alt="image" -src="/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/coverflow_screenshot.png" -height=211 -width=400>](/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/coverflow_screenshot.png) - -## **Design Review Slides** - -[Slides from API design -review](https://docs.google.com/a/chromium.org/present/edit?id=dcz7497p_9gzwfsfgs) - -## Spec (outdated) - -Note: the information below is outdated. The current API is in the process of -being checked in [here](http://codereview.chromium.org/7720002/). - -### Types - -#### OffscreenTab - -***id (int)*** -The ID of the offscreen tab. Tab IDs are unique within a browser session. -***url (string)*** -The URL the offscreen tab is displaying. -***width (int)*** -Width of the window. -***height (int)*** -Height of the window. - -### Methods - -#### create - -create (object createProperties, function callback) -Creates a new offscreen tab. -**Parameters** -**createProperties (object)** -***url (string)*** -The URL the offscreen tab should be displaying. -***width (optional int)*** -Width of the visible window. Defaults to width of the current window. -***height (****optional** **int)*** -Height of the visible window. Defaults to height of the current window. -***callback (****optional** **function)*** -The callback parameter should specify a function that looks like this: -function (OffscreenTab offscreenTab) {...}; -Details of the offscreen tab. - -#### get - -get (int offscreenTabId, function callback) -Gets details about the specified offscreen tabs. -**Parameters** -*offscreenTabId (int)*** -ID of the offscreen tab. -***callback (function)*** -The callback parameter should specify a function that looks like this: -function (OffscreenTab offscreenTab) {...}; -Details of the offscreen tab. - -#### getAll - -getAll (function callback) -Gets an array of all offscreen tabs. -**Parameters** -***callback (function)*** -The callback parameter should specify a function that looks like this: -function (array of OffscreenTab offscreenTabs) {...}; - -#### remove - -remove (int offscreenTabId, function callback) -Removes an offscreen tab. -**Parameters** -***offscreenTabId (int)*** -ID of the offscreen tab. -***callback (****optional** **function)*** -The callback parameter should specify a function that looks like this: -function () {...}; - -#### sendMouseEvent - -sendMouseEvent (int offscreenTabId, int x, int y, MouseEvent mouseEvent, -function callback) -Dispatches a mouse event in the offscreen tab. -**Parameters** -***offscreenTabId (int)*** -ID of the offscreen tab. -***mouseEvent (MouseEvent)*** -A JavaScript MouseEvent object. Supported event types: *mousedown*, *mouseup*, -*click*, *mousemove*, *mousewheel*. -***x (****optional*** ***int)*** -X position of where the mouse event should be dispatched on the offscreen web -page. Not required in the case of a *mousewheel* event. -***y (****optional*** ***int)*** -Y position of where the mouse event should be dispatched on the offscreen web -page. Not required in the case of a *mousewheel* event. -***callback (****optional** **function)*** -The callback parameter should specify a function that looks like this: -function (OffscreenTab offscreenTab) {...}; -Details of the offscreen tab. - -#### sendKeyboardEvent - -sendKeyboardEvent (int offscreenTabId, KeyboardEvent event, function callback) -Dispatches a keyboard event in the offscreen tab. -**Parameters** -***offscreenTabId (int)*** -ID of the offscreen tab. -***keyboardEvent (KeyboardEvent)*** -A JavaScript KeyboardEvent object. Supported event types: *keydown*, *keyup*, -*keypress*. Only *keypress* produces a visible result on screen. -***callback (****optional** **function)*** -The callback parameter should specify a function that looks like this: -function (OffscreenTab offscreenTab) {...}; -Details of the offscreen tab. - -#### toDataUrl - -toDataUrl (int offscreenTabId, object options, function callback) -Captures the visible area of an offscreen tab. -**Parameters** -***offscreenTabId (int)*** -The ID of the offscreen tab. -***options (****optional** **object)*** -Set parameters of image capture, such as the format of the resulting image. -***format (****optional** **enumerated string \[“jpeg”, “png”\])*** -The format of the resulting image. Default is jpeg. -***quality (****optional** **int)*** -When format is 'jpeg', controls the quality of the resulting image. This value -is ignored for PNG images. As quality is decreased, the resulting image will -have more visual artifacts, and the number of bytes needed to store it will -decrease. -***callback (****function)*** -The callback parameter should specify a function that looks like this: -function (string dataUrl) {...}; -***dataUrl (string)*** -A data URL which encodes an image of the visible area of the captured offscreen -tab. May be assigned to the 'src' property of an HTML Image element for display. - -#### update - -update (int offscreenTabId, object updateProperties, function callback) -Modifies the properties of an offscreen tab. Properties that are not specified -in updateProperties are not modified. -**Parameters** -***offscreenTabId (int)*** -The ID of the offscreen tab. -***updateProperties (object)*** -***url (****optional** **string)*** -The URL the offscreen tab is displaying. -***width (****optional** **int)*** -Width of the window. -***height (****optional** **int)*** -Height of the window. -***callback (****optional** **function)*** -The callback parameter should specify a function that looks like this: -function (OffscreenTab offscreenTab) {...}; -Details of the offscreen tab. - -### Events - -#### onUpdated - -onUpdated.addListener (function (int offscreenTabId, object chnageInfo, -OffscreenTab offscreenTab) {...}) -Fires when an offscreen tab is updated. -**Parameters** -***offscreenTabId (int)*** -ID of the updated offscreen tab -***changeInfo (object)*** -Lists the changes to the state of the offscreen tab that was updated. -***url (****optional** **string)*** -The offscreen tab’s URL if it has changed. -***offscreenTab (OffscreenTab)*** -Details of the offscreen tab
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/screenshot.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/screenshot.png.sha1 deleted file mode 100644 index fbc21430fd5..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/offscreen-tabs/screenshot.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -0f128585f1224f75bfa6e012b01403e4cecf5345
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/omnibox-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/omnibox-api/index.md deleted file mode 100644 index 6b519d3d7f4..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/omnibox-api/index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: omnibox-api -title: Omnibox API ---- - -### Status - -Dream phase. The underlying omnibox API is fairly complex. This is a work in -progress, and likely incomplete / missing key bits. - -### Overview - -There are two goals for the omnibox extension API: - -1. Register a keyword that would allow the extension author to provide - simple command hooks. -2. Be a full omnibox provider, with autocomplete matches. - -### API - -omnibox. - -// The simple way: - -// keyword-based (tab to search?) API. Perhaps usable to implement a basic -command-line interface. - -// Register a keyword for handling in this extension. - -void registerKeyword(string keyword) - -// Called when the user enters text after using this extension's registered -keywords. - -event onKeywordInput(string input) - -// The hard way: - -// Be a full-on omnibox provider. - -// Notifies Omnibox that matches are ready, and provides them for browser-side - -// use when the Omnibox wants them. - -void matchesAvailable(Match\[\] matches) - -// Called by the Omnibox when the text in the box has been changed. - -// TODO: AutocompleteInput has a lot more info than this - -event onInputChanged(string input) - -// The user has requested that this match never show up in results again. - -event onMatchDeleted(Match match) - -struct Match { - -int relevance - -bool deletable - -string fill_into_edit - -int inline_autocomplete_offset - -string destination_url - -string contents - -// missing content class - -string description - -// missing description class - -}
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/panels/Screen shot 2011-10-06 at 3.47.53 PM.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/panels/Screen shot 2011-10-06 at 3.47.53 PM.png.sha1 deleted file mode 100644 index 65b3c359af0..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/panels/Screen shot 2011-10-06 at 3.47.53 PM.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -ace727e5e3a0630ebb1c9273cfa3b96bcf5e21b9
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/panels/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/panels/index.md deleted file mode 100644 index 1834706101c..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/panels/index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: panels -title: Panels ---- - -**Overview** - -Panels are windows that are visible to the user even while the user is -interacting with other applications. The small windows are positioned at the -bottom of the screen, with minimal manual window management by the user. This -API will allow extension developers to create and use panels. - -[<img alt="image" -src="/developers/design-documents/extensions/proposed-changes/apis-under-development/panels/Screen%20shot%202011-10-06%20at%203.47.53%20PM.png">](/developers/design-documents/extensions/proposed-changes/apis-under-development/panels/Screen%20shot%202011-10-06%20at%203.47.53%20PM.png) - -**Use cases** - -An extension opens small "pop up" windows, for example, separate chat sessions, -calculator, media player, stock/sport/news ticker, task list, scratchpad, that -the user wants to keep visible while using a different application or browsing a -different web site. Scattered "pop up" windows are difficult for the user to -keep track of, therefore panels are placed along the bottom of the screen and -are "always on top". - -The user would like easy control of chat windows: finding them, moving them out -of the way, etc. Window management of separate chat "pop ups" is time consuming. -All panels can be minimized/maximized together. - -**Could this API be part of the web platform?** - -Eventually, yes. The current needs are from extension developers. If we figure -out how to make this work in the wider context of web platform, we will propose -it for the web platform at that point. - -**Do you expect this API to be fairly stable?** - -Yes. - -**What UI does this API expose?** - -Panels will be a new type of window with some unique behaviors and UI. - -**How could this API be abused?** - -An extension could open an excessive number of panels, repeatedly open and close -panels, or unnecessarily draw the user's attention to a panel. - -**How would you implement your desired features if this API didn't exist?** - -Extensions could continue to use "pop up" windows and let users manually arrange -them on their screen such that they will not be obscured by other applications. -Users would manage each "pop up" individually. - -**Are you willing and able to develop and maintain this API?** - -Yes. - -**API spec** - -Extend the chrome.windows.\* API to add a new "panel" type, as Panels are simply -another type of window. - -chrome.windows.create with type="panel" will create a new Panel window. Unlike -other window types, Panels do not take focus by default. The focused attribute -can be used to change the default behavior. - -chrome.windows.update has a new drawAttention option to attract the user's -attention to a Panel. This API can be used for all window types. The behavior to -attract the user's attention will vary depending on window type and OS. - -All other actions on the panel can be achieved via manipulations on the -DOMWindow or the window contents, e.g. change the size of the div containing all -window content to resize the panel. - -Panels are regular windows as far as other extensions \[that did not create the -panel\] are concerned and are included in all other windows-related API, e.g. -chrome.windows.getAll, chrome.extensions.getViews.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/power-management-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/power-management-api/index.md deleted file mode 100644 index b23ee188bb7..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/power-management-api/index.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: power-management-api -title: Power Management API ---- - -**Proposal Date** - -2013-03-11 -Who is the primary contact for this API? -derat@ -Who will be responsible for this API? - -The Chrome OS UI team. - -Overview -This API is intended to provide a way for extensions and apps to temporarily -disable aspects of system power management on Chrome OS. It is a modified -version of [an earlier proposed API](/system/errors/NodeNotFound) (see also -[additional implementation -details](https://docs.google.com/a/google.com/document/d/1CrZJRH5Eoh8A_6o8PwERzVSDSwEr2DDOOn14gekVCb0/edit#)). -Use cases -When the user is inactive, Chrome OS dims the screen, turns it off, and -eventually suspends the system. It attempts to avoid some or all of these -actions when the user is watching video or listening to audio. Some apps may -wish to trigger similar behavior on their own; imagine e-book or presentation -apps that need to prevent the screen from being dimmed or turned off, or a -communication app that needs to prevent the system from suspending so that -incoming calls may be received. -Do you know anyone else, internal or external, that is also interested in this -API? -Yes, there is an internal need for this API (<http://crbug.com/178944>). -External users have requested the ability to e.g. disable power management -entirely on desktop machines; this API makes it possible to write a simple -extension that does so. -Could this API be part of the web platform? -Likely, although the level of control over system power management available to -Chrome may vary between different OSes. -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -Yes, it should be stable. I don't foresee any need to add additional levels of -power-management-disabling. - -**If multiple extensions used this API at the same time, could they conflict with each others? If so, how do you propose to mitigate this problem?** -Requests will be tracked per-extension. Since requests are additive, conflicts -should not be possible. -List every UI surface belonging to or potentially affected by your API: -No UI changes are planned. -**Actions taken with extension APIs should be obviously attributable to an -extension. Will users be able to tell when this new API is being used? How?** - -This isn't currently planned. It would be possible to add UI that notifies the -user when an extension creates a request, though. - -How could this API be abused? -Extensions could use this API to disable power management features indefinitely. -Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more): -1) Disable power management features indefinitely while the extension is -running, increasing power consumption, decreasing battery life, and possibly -confusing the user. -2) N/A -3) N/A -What security UI or other mitigations do you propose to limit evilness made -possible by this new API? -Extensions will only be able to override power management while the system's lid -is open; closing the lid will still suspend the system. -**Alright Doctor, one last challenge:** -**Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?** -**No. Any outstanding requests will be abandoned when an extension is stopped. -How would you implement your desired features if this API didn't exist? -An extension could perform actions that trigger Chrome OS's existing automated -power-management-disabling behavior. For example, playing a silent audio file -would prevent the system from suspending. -Draft API spec - -*Manifest changes* - -**power** permission - -> A new permission that is required in order to call this API's methods. - -***Methods*** - -**requestKeepAwake** - -> Registers a request to disable power management. Each extension may hold at -> most one request; when multiple sequential calls are made, only the final one -> will be honored. When an extension is unloaded, its request will be -> automatically released. - -> **Parameter:** - -> *level (enum \["system", "display"\])* - -> > Specifies the degree to which power management should be disabled. - -> > "system": The system will not suspend due to user inactivity, but the screen -> > may still be dimmed or turned off. - -> > "display": The screen will not be dimmed or turned off due to user -> > inactivity. Additionally, the system will not suspend due to user -> > inactivity. If the screen is currently dimmed or turned off due to -> > inactivity, it will be turned on immediately. - -**releaseKeepAwake** - -> Unregisters an outstanding request to disable power management. Does nothing -> if no request exists. Previously-deferred power-management-related actions may -> be performed immediately. - -> **Parameters** - -> *none* - -Open questions - -1. ~~Can the API initially be Chrome-OS-only?~~ This probably won't be - an issue; content::PowerSaveBlocker should provide cross-platform - support. -2. ~~Should a "power" permission be added to the manifest specification - or should extensions be able to use this API unconditionally?~~ Yes; - added. -3. ~~Can the *callback* parameter be omitted from both methods?~~ Yes; - removed. -4. ~~The initial implementation of this API never made it out of - experimental, although [an extension which uses - it](https://chrome.google.com/webstore/detail/keep-awake-extension/bijihlabcfdnabacffofojgmehjdielb/reviews?hl=en) - was published. Can the new version of the API use the same method - names?~~ Yes. I'm updating the existing extension to use the - chrome.power API if it's present and chrome.experimental.power - otherwise.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/preference-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/preference-api/index.md deleted file mode 100644 index 322f075652a..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/preference-api/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: preference-api -title: Preferences API ---- - -### Overview - -The preferences API allows you to manipulate the browser preferences, such as -the accept languages, URLs to restore on startup etc. For the full list of -preferences, please refer to chrome/common/pref_names.cc. (Note: since the first -version will only implement the access of accept languages, this document will -focus on accept languages below.) - -### Use cases - -It allows extensions to read and write the browser preferences. Given accept -languages as an example, page translation extension and dictionary extension -will need to get the accept languages from the browser and use them as the -targeted languages for page or word translation. - -### Could this API be part of the web platform? - -Given accept languages as an example, read accept languages could be part of the -web platform, it could be exposed by window.navigator.acceptLanguages while UI -language is exposed through widow.navigator.language. But we would also like to -be able to modify accept languages preferences as well by extension, for -example, it'd be nice if we could "learn" the accept-languages through -translate, such as if you decline to translate a French page, that would be a -good signal that you want it added to the accept-languages. - -### Do you expect this API to be fairly stable? - -Yes*.* - -### What UI does this API expose? - -None*.* - -### How could this API be abused? - -Read accept languages should be OK. - -### Are you willing and able to develop and maintain this API? - -Yes*.* - -### Draft API spec - -## chrome.preferences. - -## void getAcceptLanguages(void callback(String acceptLanguages)) - -## void setAcceptLanguages(Value newAcceptLanguages) - -## void appendAcceptLanguage(Value acceptLanguage) - -### Notes - -The first version will only implement the access of accept languages. - -### Issues - -* Where should the accept-languages API live: - chrome.preferences.acceptLanguages? or chrome.i18n.acceptLanguages? -* Any issues with modifying the browser's accept languages through - extension API?
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/privacy/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/privacy/index.md deleted file mode 100644 index 6c615aa40dc..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/privacy/index.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: privacy -title: Privacy-relevant Preferences API ---- - -****Overview**** - -**Chromium includes a variety of features that provide valuable services to users either by making requests on their behalf (DNS Prefetching, for example), or by sending non-personal information to third-parties (Omnibox suggestions, for example). While we firmly believe that these services offer a huge net benefit, we also want to fully support users who choose not to take part. Users can opt-out (or opt-in, depending) to each, either via chrome://flags or chrome://settings; extensions should have programmatic access to these preferences to offer choices to users in forms that Chromium chooses not to.** -**Use cases** -**Every feature that’s listed in the[ privacy whitepaper](http://static.googleusercontent.com/external_content/untrusted_dlcp/www.google.com/en/us/intl/en/landing/chrome/google-chrome-privacy-whitepaper.pdf) is relevant to extensions that want to offer privacy protections for users above and beyond what is reasonable for Chromium to offer as a default to everyone. Extensions like Tor have expressed interest in programmatically disabling DNS prefetching (and prerendering, et al.), and it would be valuable for everyone concerned if respected advocates such as the EFF could build “EFF-approved“ default settings that users could choose to install via an extension.** -**Relatedly, but closer to home, reworking the whitepaper itself into an application from which users could directly toggle preferences without digging through preferences pages would be valuable.** -**Could this API be part of the web platform?** -**These preferences don’t relate to anything like the web platform’s storage options, but instead how Chromium interprets, requests, and processes content on the web. These options are clearly Chromium-specific, and not generally applicable to specific websites (nor would we want to offer any website the ability to, for example, toggle UMA settings).** -**Do you expect this API to be fairly stable?** -**These preferences map fairly directly to the services and features the browser offers, which means that the API would only shift in relation to changes in browser-functionality. As it is by necessity browser-specific, that seems reasonable in terms of stability.** -**What UI does this API expose?** -**None. The preferences are already exposed via chrome://settings and chrome://flags, this proposal simply adds a programmatic interface.** -**How could this API be abused?** -**Malicious extensions could send Omnibox keystrokes and other such data to a third-party server by tricking the user into changing her default search engine, and toggling the relevant preferences for Suggest. Likewise, they could force loading of arbitrary sites by doing the same, and enabling Instant.** -**How would you implement your desired features if this API didn't exist?** -**Individual users would be pointed to the various bits of UI where these settings exist (preferences and flags), and asked to toggle settings manually. This is, for example, what the Chrome privacy whitepaper does right now.** -**Are you willing and able to develop and maintain this API?** -**Yes.** -**Draft API spec** -**TODO.** -**This API could be provided in two ways (possibly together).** -**Option 1** -**Chromium already provides APIs related to subsets of the “Clear Browsing Data” form’s functionality. Adding methods to each of those seems like a reasonable way of addressing the request. We call pretty much everything cookies, so adding chrome.cookies.clear might look like the following:** -**{** -**"namespace": "cookies",** -**…** -**"functions": \[** -**…** -**{** -**"name": "clear",** -**"description": "Clears cookies and other site data modified within a time period.",** -**"type": "function",** -**"parameters": \[** -**{** -**"name": "timePeriod",** -**"type": "string",** -**"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\],** -**"optional": "false",** -**"description": "The time period inside which to delete cookies and site data."** -**},** -**{** -**"name": "callback",** -**"type": "function",** -**"description": "Called when deletion has completed.",** -**"optional": "true",** -**"parameters": \[** -**{** -**"name": "result",** -**"type": "boolean",** -**"description": "Was the data deletion successful?"** -**}** -**\]** -**}** -**\]** -**},** -**…** -**\],** -**…** -**}** -**chrome.cookies and chrome.history seem like excellent candidates for these sorts of methods. The history namespace could probably be overloaded to include methods to clear the browser cache, downloaded files, stored passwords, and Autofill data (since it’s all arguably historical in nature).** -**It would be valuable, however, to distinguish the namespace from the permission required to execute the methods. Extensions focused on removing data (see the use-cases above) shouldn’t be required to request read access to cookies on a variety of hosts in order to clear them. Adding an explicit removeBrowsingData permission that would grant access to the relevant methods across namespaces would be valuable (cookies should grant the same access, but only to the cookies-specific chrome.cookies.clear).** -**Option 2** -**A drawback to the option above is that clearing all browsing data requires many (expensive) executions of BrowsingDataRemover::Remove. Providing a single method that encapsulated all the options in a single call would be much more efficient. That might look like the following:** -**{** -**"namespace": "experimental.browsingData",** -**"functions": \[** -**{** -**"name": "clear",** -**"description": "Clears data generated by browsing within a particular timeframe.",** -**"type": "function",** -**"parameters": \[** -**{** -**"name": "timePeriod",** -**"type": "string",** -**"enum": \["last_hour", "last_day", "last_week", "last_month", "everything"\],** -**"optional": "false",** -**"description": "The timeframe inside of which to delete browsing data.”** -**},** -**{** -**"name": "dataToRemove",** -**"type": "object",** -**"optional": "false",** -**"properties": {** -**"cache": {** -**"type": "boolean",** -**"optional": true,** -**"description": "Should the browser cache be cleared?"** -**},** -**"cookies": {** -**"type": "boolean",** -**"optional": true,** -**"description": "Should the browser's cookies be cleared?"** -**},** -**"downloads": {** -**"type": "boolean",** -**"optional": true,** -**"description": "Should the browser's download list be cleared?"** -**},** -**"form_data": {** -**"type": "boolean",** -**"optional": true,** -**"description": "Should stored form data be cleared?"** -**},** -**"history": {** -**"type": "boolean",** -**"optional": true,** -**"description": "Should the browser's history be cleared?"** -**},** -**"lso_data": {** -**"type": "boolean",** -**"optional": true,** -**"description": "Should LSO data be cleared?"** -**},** -**"passwords": {** -**"type": "boolean",** -**"optional": true,** -**"description": "Should the stored passwords be cleared?"** -**}** -**}** -**},** -**{** -**"name": "callback",** -**"type": "function",** -**"description": "Called when deletion has completed.",** -**"optional": "true",** -**"parameters": \[** -**{** -**"name": "result",** -**"type": "boolean",** -**"description": "Was the data deletion successful?"** -**}** -**\]** -**}** -**\]** -**}** -**\]** -**}** -**Open questions** - -1. **BrowsingDataRemover offers the option of clearing browsing - history, download history, clearing the cache, deleting cookies + - site + plug-in data, clearing saved passwords, and clearing Autofill - data. Homes should be found for programmatic methods that clear each - type of data.** -2. **Should we offer a separate namespace for clearing browsing data? - If so, are there other delete-only methods that would make sense to - include in such a namespace?**
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/processes-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/processes-api/index.md deleted file mode 100644 index fa474c3e9e5..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/processes-api/index.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: processes-api -title: Process Model API ---- - -**Proposal Date** -**02/24/2012** -**Who is the primary contact for this API?** -**Nasko Oskov (nasko@chromium.org), Charlie Reis (creis@chromium.org)** -**Who will be responsible for this API? (Team please, not an individual)** - -**Site Isolation** - -Overview** -Add chrome.processes API that lets extensions access data about the Chrome’s -process model, such as process ID and CPU usage.** - -Use cases -Web applications are becoming more complex and resource demanding, and power -users may want a better view of which pages are responsible for resource use. It -may also be useful as a debugging or diagnosis tool, to see which tabs are -currently sharing fate. Here are a few types of extensions that could use this -API: - -* A Browser Action showing all tabs sharing the current process. All - of these tabs would slow down or crash together if something went - wrong.<img alt="image" - src="https://lh5.googleusercontent.com/KnOBPV-gjd9L3rQLK966uNUTnsow-9mikKEj049XGuwTJf6UHxe3NXigKywxKyPuPvXEFoe71Vlxn9gDNE2vGTqpK5ffMjx7YmDCXlmVMqPzwR1TThw" - height=189px; width=500px;> -* A Browser Action showing the current CPU or memory use of the tab's - process with a utilization graph, much like the Windows Task Manager - icon in the system tray. -* An extension that automatically restores all affected tabs if a - process crashes, unless the crash repeats itself (much like IE8). -* An extension that implements a custom task manager, perhaps with - graphs or other visualizations. - -Do you know anyone else, internal or external, that is also interested in this -API? -Chris Bentzel and Erik Kay have expressed interest in using this API to -prototype different policies for process management (such as killing prerender -processes). Patrick Stinson [has expressed -interest](http://groups.google.com/a/chromium.org/group/chromium-dev/browse_thread/thread/e5f0963407ccfb4d/c7bdd506c06646eb) -in creating a custom “Aw-snap” screen to use in kiosk scenarios and reload the -current URL. -Could this API be part of the web platform? -Unlikely, because it is mainly useful in multi-process browser architectures. -While an increasing number of browsers are moving toward such architectures, -it's certainly not a requirement for all web browsers. It also could expose -functionality specific to the Chromium process model in the future. -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -**Yes. The API will expose functionality that is already present in the Task Manager and unlikely to disappear in the future.** -**The initial version of the API will not include memory details other than the -private memory for the process. The reason is the complexity of adding memory -usage information, which needs to be retrieved in asynchronous model (through a -MemoryDetails object). In addition, for getting the overall memory usage of the -browser, we need platform specific logic for calculating the data. The goal is -to release an initial version to allow feedback on the API and its usage, with a -follow up update adding the extra information.** -List every UI surface belonging to or potentially affected by your API: -The API will not affect UI surface. It will expose internal browser data to -extensions, which can author their own UI based on the data. -How could this API be abused? -Like most extension APIs, it could be used to leak information about the user's -browsing habits, such as the number of processes running or CPU usage patterns. -It could also be used to load attack pages in the same process as another page, -but that can already be done without this API using iframes. It could be used as -a DoS tool by crashing particular renderer processes, but extensions can already -do this by visiting "about:crash" in a given tab. -Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more): -1) Kill random or all processes, causing tabs showing “Oh Snap” screens. -2) Use the terminate method to try and kill processes outside of Chromium. -3) -Alright Doctor, one last challenge: -Could a consumer of your API cause any permanent change to the user’s system -using your API that would not be reversed when that consumer is removed from the -system? -No, the API will provide access to the process model only. The only state change -the API will allow is to terminate child processes, which should not lead to any -permanent changes to the system. -How would you implement your desired features if this API didn't exist? -We are not aware of another way to obtain this information. Some of the data -(though not CPU usage) is provided by about:memory, but extensions are not -allowed to load this page to parse its contents. Even if about:memory could be -loaded and parsed by extensions, it would be difficult to match a given tab to a -process simply by its title. -Draft API spec -API reference: chrome.processes -Methods: -**terminate** -**chrome.experimental.processes.terminate(integer processId, optional function callback)** -**Terminates the specified Chrome process. For renderer processes, it is equivalent to visiting about:crash, but without changing the tab's URL.** -**Parameters** - -**processId ( integer )** - -**The ID of the process to be terminated.** - -**Callback function** -**The callback parameter should specify a function that looks like this:** -**function(boolean result) {...}** -**Parameters** - -**result ( boolean )** - -**True if terminating the process was successful, otherwise false.** - -getProcessInfo -**chrome.experimental.processes.getProcessInfo(integer or array of integer -processIds, boolean includeMemory, function callback)** - -Retrieves the process information for each process ID specified. -**Parameters** - -**processIds ( integer or array of integer )** - -**The list of process IDs or single process ID for which to return the process information. An empty list indicates all processes are requested.** - -**includeMemory ( boolean )** - -**True if detailed memory usage is required. Note, collecting memory usage information incurs extra CPU usage and should only be queried for when needed.** - -**callback ( optional function )** - -**Called when the processes information is collected.** - -**Callback function** -**The callback parameter should specify a function that looks like this:** -**function(object processes) {...}** -**Parameters** - -**processes ( object )** - -**A dictionary of Process objects for each requested process that is a live child process of the current browser process, indexed by process ID. Metrics requiring aggregation over time will not be populated in each Process object.** - -Events: -onCreated -chrome.experimental.processes.onCreated.addListener(function(Process process) -{...}); -Fires when a new process is created. -Parameters - -process ( Process ) - -Details of the process that was created. Metrics requiring aggregation over time -will not be populated in the object. - -**onExited** -**chrome.experimental.processes.onExited.addListener(function(integer processId, integer exitType, integer exitCode) {...});** -**Fires when a process is terminated, either cleanly or due to a crash.** -**Parameters** - -**processId ( integer )** - -**The ID of the process that exited.** - -**exitType ( integer )** - -**The type of exit that occurred for the process - normal, abnormal, killed, crashed. Only available for renderer processes.** - -**exitCode ( optional integer )** - -**The exit code if the process exited abnormally. Only available for renderer processes.** - -**onUnresponsive** -**chrome.experimental.processes.onUnresponsive.addListener(function(Process process) {...});** -**Fires when a process becomes unresponsive.** -**Parameters** - -**process ( Process )** - -**Details of the unresponsive process. Metrics requiring aggregation over time will not be populated in the object. Only available for renderer processes.** - -onUpdated -chrome.experimental.processes.onUpdated.addListener(function(object processes) -{...}); -Fires each time the Chrome Task Manager updates its process statistics, -providing a dictionary of updated Process objects, indexed by process ID. -Parameters - -processes ( object ) - -A dictionary of updated Process objects for each live process in the browser, -indexed by process ID. Metrics requiring aggregation over time will be populated -in each Process object. - -**onUpdatedWithMemory** -**chrome.experimental.processes.onUpdatedWithMemory.addListener(function(object processes) {...});** -**Fires each time the Chrome Task Manager updates its process statistics, providing a dictionary of updated Process objects, indexed by process ID. Identical to onUpdate, with the addition of memory usage details included in each Process object. Note, collecting memory usage information incurs extra CPU usage and should only be listened for when needed.** -**Parameters** - -**processes ( object )** - -**A dictionary of updated Process objects for each live process in the browser, indexed by process ID. Memory usage details will be included in each Process object.** - -Types: -**Cache** -**( object )** -**The Cache object contains information about the size and utilization of a cache used by Chrome.** -**size ( integer )** - -**The size of the cache, in bytes.** - -**liveSize ( integer )** - -**The part of the cache that is utilized, in bytes.** - -**Process** -**( object )** -**The Process object contains various types of information about the underlying OS process. Some of the information, such as cpu or sqliteMemory, needs to be collected over time. Such data is present in the object only when it is part of a callback for the onUpdated or onUpdatedWithMemory events and not for getProcessInfo. Also, privateMemory is expensive to measure, so it is only present in the object when it is part of a callback for onUpdatedWithMemory or getProcessInfo with the includeMemory flag.** -**id ( integer )** -**The unique ID of the process provided by Chrome.** -**osProcessId ( integer )** - -**The operating system process ID.** - -**type ( string )** -**The type of process. Either browser, renderer, extension, notification, plugin, worker, nacl,** -**utility, gpu, or other.** -**profile ( string )** - -**The profile which the process is associated with.** - -**tabs ( array of integer )** - -**Array of Tab IDs that have a page rendered by this process. The list will be non-empty for renderer processes only.** - -**cpu ( optional number )** - -**The most recent measurement of the process's CPU usage, between 0 and 100%. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory.** - -**privateMemory ( optional number )** - -**The most recent measurement of the process's private memory usage, in bytes. Only available when receiving the object as part of a callback from onUpdatedWithMemory or getProcessInfo with the includeMemory flag.** - -**network ( optional number )** - -**The most recent measurement of the process's network usage, in bytes per second. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory.** - -**jsMemoryAllocated ( optional number )** - -**The most recent measurement of the process’s JavaScript allocated memory, in bytes. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory.** - -**jsMemoryUsed ( optional number )** - -**The most recent measurement of the process’s JavaScript memory used, in bytes. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory.** - -**sqliteMemory ( optional number )** - -**The most recent measurement of the process’s SQLite memory usage, in bytes. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory.** - -**fps ( optional number )** - -**The most recent measurement of the process’s frames per section. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory.** - -**imageCache ( optional object )** - -**The most recent information about the image cache for the process. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory.** - -**scriptCache ( optional object )** - -**The most recent information about the script cache for the process. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory.** - -**cssCache ( optional object )** - -**The most recent information about the CSS cache for the process. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory.** - -Open questions - -* Does the Tab object need a process ID added to it? - * After discussion with Charlie Reis, it will be best to be a list - or tree structure, to accommodate future out of process IFrame - rendering work. Ideally we can include plugin processes as - Process objects and form a full tree of all processes involved - in rendering a single tab. -* Should Site Instance be exposed through the API? - * At this point in time it is hard to come up with a good example - other than some of our own visualizing/debugging. If any - compelling usage presents itself, we can see if it justifies - including the information. For now I don't think it is - worthwhile information to expose. -* Should we maintain a list of tabs associated with a process, or - should we let developers do that by looping over the current tabs? - * *Aaron: That seems useful.*
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/processes-api/process-extension-screenshot.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/processes-api/process-extension-screenshot.png.sha1 deleted file mode 100644 index 5d4919be9de..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/processes-api/process-extension-screenshot.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -0eb92ca0677d0bb382567067aa85ce3a7d96ae42
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/profile-extension-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/profile-extension-api/index.md deleted file mode 100644 index 62315ea48f2..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/profile-extension-api/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: profile-extension-api -title: Profile Extension API ---- - -**Proposal Date** -**December 27, 2012** -**Who is the primary contact for this API?** -**rlp@** -**Who will be responsible for this API? (Team please, not an individual)** -**Profiles team (sub team of Frontend team)** -**Overview** -**Access to profile information for extensions. This requires adding one method and extending another.** -**The addition would be a method which returns a list of all existing users on a machine. Users would be an object consisting of to two pieces of data: profile name and icon.** -**The second part of this proposal would be adding an optional profile parameter to the chrome.window.create method, allowing extensions to open a window for another user.** -**Use cases** -**An API to open windows in new profiles has been requested by the marketing team. Furthermore, providing access to the list of profiles would allow extensions to open windows in a selected profile. We've had several profile bugs about not being able to open a link or otherwise in the expected and/or desired profile.** -**Do you know anyone else, internal or external, that is also interested in this API?** -**The marketing team has requested access to multiple users for demos. This API would allow for writing an extension to give them the needed access.** -**Could this API be part of the web platform?** -**No, because profiles are specific to Chrome.** -**Do you expect this API to be fairly stable? How might it be extended or changed in the future?** -**Yes, this API should be stable due to its simplicity. Even if the underlying structure of profiles change, this should not affect this API.** -**Additional access to profiles could be added in the future.** -**If multiple extensions used this API at the same time, could they conflict with each others? If so, how do you propose to mitigate this problem?** -**This API is read-only. It cannot change or create new profiles. So there can be no conflict between multiple extensions.** -**List every UI surface belonging to or potentially affected by your API:** -**This would not add any new UI.** -**Actions taken with extension APIs should be obviously attributable to an extension. Will users be able to tell when this new API is being used? How?** -**For the extension to creating a new window, we would be piggybacking on existing methods for indicating a new window was opened by an extension. For getting the list of users, there is no external action which would be visible to users.** -**How could this API be abused?** -**This would provide the extension access to know which users are on a given instance of Chrome. Some may view this as as security concern although this information is already available.** -**By allowing the extension to open new windows, you could potentially switch users on someone.** -**Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):** -**1) Open up a website requiring a password with a different user. The original user doesn't realize the newly opened window is from a different user, enters their password which is then stored for the other user.** -**2) Get a list of the users on a computer and send that information back to a nefarious server (though I don't know what they'd do with that information).** -**3) Share information about one user with another.** -**What security UI or other mitigations do you propose to limit evilness made possible by this new API?** -**User icons from the extension API could be tagged to indicate they are from the extension api.** -**Alright Doctor, one last challenge:** -**Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?** -**No they could not. All information is read-only so they could not make any permanent changes to the state of a user's Chrome.** -**How would you implement your desired features if this API didn't exist?** -**Currently there is no way to get this information or allow someone to open a window with a different profile.** -**Draft Manifest Changes** -**None.** -**Draft API spec** -**Types** -**Profile (object)** -**Properties of Profile** -**name (string)** -**The name of the profile.** -**icon (ImageData)** -**The icon of the profile.** -**Methods** -**getProfileList** -**chrome.users.getProfileList** - -**Returns a list of current users known for this instance of Chrome. If the current user is in managed mode or on ChromeOS, this list will only contain the current user.** - -**result (array of Profile)** -**Additional Parameter for chrome.windows.create** -**profileName (string)** -**The name of the profile which the window should be created for. If the current user is in managed mode or on ChromeOS, this parameter will have no effect as they can only open windows for the current user.** -**Open questions** -**Could this be a function under chrome.windows?**
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/proposal-chrome-extensions-cookies-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/proposal-chrome-extensions-cookies-api/index.md deleted file mode 100644 index 9a124266ddf..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/proposal-chrome-extensions-cookies-api/index.md +++ /dev/null @@ -1,807 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: proposal-chrome-extensions-cookies-api -title: Cookies API ---- - -### Overview - -The proposed API allows Chrome extensions to access the browser's cookies, -without having to send HTTP requests to obtain those cookies. - -### Use Cases - -We are developing a Chrome extension that interacts with known services -requiring authentication. We would like the extension to be able to detect -authentication status changes as they occur in an inexpensive way, by checking -for the existence of known cookies associated with that service. -In general, any Chrome extension wishing to interact with services that set -browser cookies could benefit from this API. The API could also support Chrome -extensions which don't care about specific known cookies, but can for instance -help the user gain more visibility or control into what cookies are being set on -their browser. - -### Could this API be part of the web platform? - -No. The web platform relies on the same origin model, and sites can read their -own cookies. This API is for elevated privilege entities (i.e. extensions) to -read and write cookies across origins. - -### Do you expect this API to be fairly stable? - -Yes. The general mechanism of browser cookies is mature and likely stable, -making this API equally stable. - -### What UI does this API expose? - -None. - -### How could this API be abused? - -A malicious extension could steal cookies from sites the user visits. The API -also exposes HttpOnly cookie data to the extension. However, as documented -above, it is already possible to obtain cookies and to generate HTTP requests -from a Chrome extension by using content scripts, so these new APIs don't expose -any new vulnerabilities. - -### How would you implement your desired features if this API didn't exist? - -One technique is to use content scripts: loading a URL matching a particular -cookie's domain, and inspecting the value of document.cookie in a content -script. Another method could involve sending an XmlHttpRequest to a service that -will return authentication status information for a particular resource. Both of -these techniques require network connectivity and communication, making them -undesirable in a real-world application. Loading extra URLs in new windows or -hidden iframes in order to access cookies via content scripts poses further -potential security, privacy and usability risks. - -### Are you willing and able to develop and maintain this API? - -Yes. - -### ******Draft API spec****** - -### ************Use the chrome.experimental.cookies module to access cookies from your extension.************ - -### ************#### ************Manifest************************ - -### ************You must declare the "cookies" permission in your extension's manifest to use the cookies API. You also must request cross-origin permissions for the domains you wish to access cookies for, using the same match-pattern syntax used for cross-origin XHR permissions. For example:************ - -### ************`{`************ -### ************` "name": "My extension",`************ -### ************` ...`************ -### ************` "permissions": [`************ -### ************` "cookies",`************ -### ************` "http://*.google.com/"`************ -### ************` ],`************ -### ************` ...`************ -### ************`}`************ - -#### ************Methods************ - -### ************get************ - -### ************`chrome.experimental.cookies.get(object details, function callback)`************ - -### ************Retrieves information about a single cookie. If more than one cookie of the same name exists for the given URL, the one with the longest domain property, longest path length, or earliest creation time will be returned.************ - -> ### ************#### ************Parameters************************ - -> ### *************details (object)************* - -> > ### *************************Details to identify the cookie being retrieved.************************* - -> > ### *************url (string)************* - -> > > ### ************The URL with which the cookie to retrieve is associated. This argument may be a full URL, in which case any data following the URL path (e.g. the query string) is simply ignored. If host permissions for this URL are not specified in the manifest file, the API call will fail.************ - -> > *************name (string)************* - -> > > ### **************************************The name of the cookie to retrieve.************************************** - -> > ### *************storeId (optional string)************* - -> > > ### ************The ID of the cookie store in which to look for the cookie. By default, the current execution context's cookie store will be used.************ - -> ### *************************callback (function)************************* - -> #### ************************************Callback Function************************************ - -> > #### ************************************************The callback parameter should specify a function that looks like this:************************************************ - -> > #### ************************************************************`function(Cookie cookie) {...});`************************************************************ - -> > ### *************cookie (optional Cookie)************* - -> > > ### *************************Contains details about the cookie. This parameter is null if no such cookie was found.************************* - -### **************getAll************** - -### ************`chrome.experimental.cookies.getAll(object `************ - -### ************``************``### ************`details`************``************``************ - -### ************``**********`, function callback)`************``************ - -### Retrieves all cookies from a single cookie store that match the given information. - -> #### ************Parameters************ - -> #### *************************details (object)************************* - -> > #### *************************************Information to filter the cookies being retrieved.************************************* - -> > ### *************url (optional string)************* - -> > > ### Restricts the retrieved cookies to those that would match the given URL. - -> > ### *### *************name (optional string)************** - -> > > ### *### Filters the cookies by name.* - -> > ### *### *************domain (optional string)************** - -> > > ### *### Restricts the retrieved cookies to those whose domains match or are subdomains of this one.* - -> > ### *### *************path (optional string)************** - -> > > ### *### Restricts the retrieved cookies to those whose path exactly matches this string.* - -> > ### *### *************secure (optional boolean)************** - -> > > ### *### Filters the cookies by their Secure property.* - -> > ### *### *************session (optional************** - -> > ### *### **************### **************### *************boolean****************************************** - -> > ### *### *************### *************)**************************** - -> > > ### *### Filters out session vs. persistent cookies.* - -> > ### *### *### **************************storeId (optional**************************** - -> > ### *### *### ***************************### *### ***************************### *************string********************************************************************** - -> > ### *### *### **************************### *### **************************)******************************************************** - -> > > ### ### **************************The cookie store to retrieve cookies from. If omitted, the current execution context's cookie store will be used.************************** - -> ### *callback (function)* - -> #### Callback Function - -> > #### The callback parameter should specify a function that looks like this: - -> > #### `function(array of Cookie cookies) {...});` - -> > #### `*cookies (array of Cookie)*` - -> > > #### `*All the existing, unexpired cookies that match the given cookie info.*` - -****### set**** - -****### *******************************`chrome.experimental.cookies.set(object -details)`*********************************** - -****### #### `*********************Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist.*********************`**** - -> ****#### ************Parameters**************** - -> ****#### *details (object)***** - -> > ****#### Details about the cookie being set.**** - -> > ********### *************url (string)********************* - -> > > ********### The request-URI to associate with the setting of the cookie. This value can affect the default domain and path values of the created cookie. If host permissions for this URL are not specified in the manifest file, the API call will fail.******** - -> > *******### *************name (optional string)********************* - -> > > *******### The name of the cookie. Empty by default if omitted.******** - -> > *******### *************value (optional string)********************* - -> > > *******### The value of the cookie. Empty by default if omitted.******** - -> > *******### *************domain (optional string)********************* - -> > > *******### The domain of the cookie. If omitted, the cookie becomes a host-only cookie.******** - -> > *******### *************path (optional string)********************* - -> > > *******### The path of the cookie. Defaults to the path portion of the url parameter.******** - -> > *******### *************secure (optional boolean)********************* - -> > > *******### Whether the cookie should be marked as Secure. Defaults to false.******** - -> > *******### *************httpOnly (optional boolean)********************* - -> > > *******### Whether the cookie should be marked as HttpOnly. Defaults to false.******** - -> > *******### *************expirationDate (optional number)********************* - -> > > *******### The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie.******** - -> > ****### *************storeId (optional string)***************** - -> > > ***### The ID of the cookie store in which to set the cookie. By default, the cookie is set in the current execution context's cookie store.**** - -******remove****** - -****### ****### ****### -*******************************`chrome.experimental.cookies.remove(object -details)`******************************************* - -****### ****### ****### *******************************`****#### *Deletes a cookie by name.*****`******************************************* - -> ****#### **### ### ### `#### #### Parameters`****** - -> ****#### *details (object)***** - -> > ****#### Information to identify the cookie to remove.**** - -> > ****#### ****### *************url (string)********************* - -> > > ****### The URL associated with the cookie. If host permissions for this URL are not specified in the manifest file, the API call will fail.**** - -> > ********### ****name (string)************ - -> > > ****### The name of the cookie to remove.**** - -> > ****### storeId (optional string)**** - -> > > ****The ID of the cookie store to look in for the cookie. If unspecified, -> > > the cookie is looked for by default in the current execution context's -> > > cookie store.**** - -****### ********************### ********************### ****### getAllCookieStores************************************************ - -****### ****### ****### -*******************************`chrome.experimental.cookies.getAllCookieStores(function -callback)`******************************************* - -****### ****### ****### *******************************`****#### *Lists all existing cookie stores.*****`******************************************* - -> ****#### **### ### ### `#### #### Parameters`****** - -> ****#### *callback (function)***** - -> ****#### **#### Callback Function****** - -> > ****#### The callback parameter should specify a function that looks like this:**** - -> > ****#### `function(array of CookieStore cookieStores) {...});`**** - -> > ****#### cookieStores (array of CookieStore)**** - -> > > ****#### All the existing cookie stores.**** - -#### **#### Events** - -#### **#### ****#### onChanged****** - -#### **#### ****#### `chrome.experimental.cookies.onChanged.addListener(function(object changeInfo) {...});`****** - -#### **#### ****#### `Fired when a cookie is set or removed.`****** - -> #### Parameters - -> #### **#### ****#### `changeInfo (object)`****** - -> > #### **#### ****#### `removed (boolean)`****** - -> > > #### **#### ****#### `True if a cookie was removed.`****** - -> > #### **#### ****#### `cookie (Cookie) `****** - -> > > #### **#### ****#### `Information about the cookie that was set or removed.`****** - -#### Types - -#### **#### ****#### ``**#### ****#### `Cookie (object)`******``****** - -#### **#### ``#### **#### `Represents information about an HTTP cookie.`**``** - -> #### **#### ****#### ``**#### ****#### `name (string)`******``****** - -> > #### **#### ****#### ``**#### ****#### `The name of the cookie.`******``****** - -> #### **#### ****#### ``**#### ****#### `value (string)`******``****** - -> > #### **#### ****#### ``**#### ****#### `The value of the cookie.`******``****** - -> #### **#### ****#### ``**#### ****#### `domain (string)`******``****** - -> > #### **#### ****#### ``**#### ****#### `The domain of the cookie.`******``****** - -> #### **#### ****#### ``**#### ****#### `hostOnly (boolean) `******``****** - -> > #### **#### ****#### ``**#### ****#### `True if the cookie is a host-only cookie (i.e. a request's host must exactly match the domain of the cookie).`******``****** - -> #### **#### ****#### ``**#### ****#### `path (string)`******``****** - -> > #### **#### ****#### ``**#### ****#### `The path of the cookie.`******``****** - -> #### **#### ****#### ``**#### ****#### `secure (boolean)`******``****** - -> > #### **#### ****#### ``**#### ****#### `True if the cookie is marked as Secure (i.e. its scope is limited to secure channels, typically HTTPS).`******``****** - -> #### **#### ****#### ``**#### ****#### `httpOnly (boolean)`******``****** - -> > #### **#### ****#### ``**#### ****#### `True if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts).`******``****** - -> *session (boolean)* - -> > #### #### #### ``#### #### `True if the cookie is a session cookie, as opposed to a persistent cookie with an expiration date.` `` - -> #### **#### ****#### ``**#### ****#### `expirationDate (optional number) `******``****** - -> > #### **#### ****#### ``**#### ****#### `The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies. `******``****** - -> #### **#### ****#### ``**#### ****#### `storeId (string)`******``****** - -> > #### **#### ****#### ``**#### ****#### `The ID of the cookie store containing this cookie, as provided in getAllCookieStores().`******``****** - -#### **#### ****#### ``**#### ****#### `CookieStore (object) `******``****** - -#### **#### ****#### ``**#### ****#### `A session cookie store in the browser. An incognito mode window, for instance, has a separate session cookie store from other windows.`******``****** - -> #### **#### ****#### ``**#### ****#### `id (string)`******``****** - -> > #### **#### ****#### ``**#### ****#### `The unique identifier for the cookie store.`******``****** - -> #### **#### ****#### ``**#### ****#### `tabIds (array of integer)`******``****** - -> > #### **#### ****#### ``**#### ****#### `Identifiers of all the browser tabs that share this cookie store.`******``****** - -#### **#### ****#### ``**#### ****#### `A more formal description of the API and some sample code usage:`******``****** - -`[` -` {` - -` "namespace": "experimental.cookies",` - -` "types": \[` - -` {` - -` "id": "Cookie",` - -` "type": "object",` - -` "description": "Represents information about an HTTP cookie.",` - -` "properties": {` - -` "name": {"type": "string", "description": "The name of the cookie."},` - -` "value": {"type": "string", "description": "The value of the cookie."},` - -` "domain": {"type": "string", "description": "The domain of the cookie."},` - -` "hostOnly": {"type": "boolean", "description": "True if the cookie is a -host-only cookie (i.e. a request's host must exactly match the domain of the -cookie)."},` - -` "path": {"type": "string", "description": "The path of the cookie."},` - -` "secure": {"type": "boolean", "description": "True if the cookie is marked as -Secure (i.e. its scope is limited to secure channels, typically HTTPS)."},` - -` "httpOnly": {"type": "boolean", "description": "True if the cookie is marked -as HttpOnly (i.e. the cookie is inaccessible to client-side scripts)."},` - -` "session": {"type": "boolean", "description": "True if the cookie is a session -cookie, as opposed to a persistent cookie with an expiration date."},` - -` "expirationDate": {"type": "number", "optional": true, "description": "The -expiration date of the cookie as the number of seconds since the UNIX epoch. Not -provided for session cookies."},` - -` "storeId": {"type": "string", "description": "The ID of the cookie store -containing this cookie, as provided in getAllCookieStores()."}` - -` }` - -` },` - -` {` - -` "id": "CookieStore",` - -` "type": "object",` - -` "description": "Represents a cookie store in the browser. An incognito mode -window, for instance, uses a separate cookie store from a non-incognito -window.",` - -` "properties": {` - -` "id": {"type": "string", "description": "The unique identifier for the cookie -store."},` - -` "tabIds": {"type": "array", "items": {"type": "integer"}, "description": -"Identifiers of all the browser tabs that share this cookie store."}` - -` }` - -` }` - -` \],` - -` "functions": \[` - -` {` - -` "name": "get",` - -` "type": "function",` - -` "description": "Retrieves information about a single cookie. If more than one -cookie of the same name exists for the given URL, the one with the longest -domain property, longest path length, or earliest creation time will be -returned.",` - -` "parameters": \[` - -` {` - -` "type": "object",` - -` "name": "details",` - -` "description": "Details to identify the cookie being retrieved.",` - -` "properties": {` - -` "url": {"type": "string", "description": "The URL with which the cookie to -retrieve is associated. This argument may be a full URL, in which case any data -following the URL path (e.g. the query string) is simply ignored. If host -permissions for this URL are not specified in the manifest file, the API call -will fail."},` - -` "name": {"type": "string", "description": "The name of the cookie to -retrieve."},` - -` "storeId": {"type": "string", "optional": true, "description": "The ID of the -cookie store in which to look for the cookie. By default, the current execution -context's cookie store will be used."}` - -` }` - -` },` - -` {` - -` "type": "function",` - -` "name": "callback",` - -` "parameters": \[` - -` {` - -` "name": "cookie", "$ref": "Cookie", "optional": true, "description": "Contains -details about the cookie. This parameter is null if no such cookie was found."` - -` }` - -` \]` - -` }` - -` \]` - -` },` - -` {` - -` "name": "getAll",` - -` "type": "function",` - -` "description": "Retrieves all cookies from a single cookie store that match -the given information.",` - -` "parameters": \[` - -` {` - -` "type": "object",` - -` "name": "details",` - -` "description": "Information to filter the cookies being retrieved.",` - -` "properties": {` - -` "url": {"type": "string", "optional": true, "description": "Restricts the -retrieved cookies to those that would match the given URL."},` - -` "name": {"type": "string", "optional": true, "description": "Filters the -cookies by name."},` - -` "domain": {"type": "string", "optional": true, "description": "Restricts the -retrieved cookies to those whose domains match or are subdomains of this -one."},` - -` "path": {"type": "string", "optional": true, "description": "Restricts the -retrieved cookies to those whose path exactly matches this string."},` - -` "secure": {"type": "boolean", "optional": true, "description": "Filters the -cookies by their Secure property."},` - -` "session": {"type": "boolean", "optional": true, "description": "Filters out -session vs. persistent cookies."},` - -` "storeId": {"type": "string", "optional": true, "description": "The cookie -store to retrieve cookies from. If omitted, the current execution context's -cookie store will be used."}` - -` }` - -` },` - -` {` - -` "type": "function",` - -` "name": "callback",` - -` "parameters": \[` - -` {` - -` "name": "cookies", "type": "array", "items": {"$ref": "Cookie"}, -"description": "All the existing, unexpired cookies that match the given cookie -info."` - -` }` - -` \]` - -` }` - -` \]` - -` },` - -` {` - -` "name": "set",` - -` "type": "function",` - -` "description": "Sets a cookie with the given cookie data; may overwrite -equivalent cookies if they exist.",` - -` "parameters": \[` - -` {` - -` "type": "object",` - -` "name": "details",` - -` "description": "Details about the cookie being set.",` - -` "properties": {` - -` "url": {"type": "string", "description": "The request-URI to associate with -the setting of the cookie. This value can affect the default domain and path -values of the created cookie. If host permissions for this URL are not specified -in the manifest file, the API call will fail."},` - -` "name": {"type": "string", "optional": true, "description": "The name of the -cookie. Empty by default if omitted."},` - -` "value": {"type": "string", "optional": true, "description": "The value of the -cookie. Empty by default if omitted."},` - -` "domain": {"type": "string", "optional": true, "description": "The domain of -the cookie. If omitted, the cookie becomes a host-only cookie."},` - -` "path": {"type": "string", "optional": true, "description": "The path of the -cookie. Defaults to the path portion of the url parameter."},` - -` "secure": {"type": "boolean", "optional": true, "description": "Whether the -cookie should be marked as Secure. Defaults to false."},` - -` "httpOnly": {"type": "boolean", "optional": true, "description": "Whether the -cookie should be marked as HttpOnly. Defaults to false."},` - -` "expirationDate": {"type": "number", "optional": true, "description": "The -expiration date of the cookie as the number of seconds since the UNIX epoch. If -omitted, the cookie becomes a session cookie."},` - -` "storeId": {"type": "string", "optional": true, "description": "The ID of the -cookie store in which to set the cookie. By default, the cookie is set in the -current execution context's cookie store."}` - -` }` - -` }` - -` \]` - -` },` - -` {` - -` "name": "remove",` - -` "type": "function",` - -` "description": "Deletes a cookie by name.",` - -` "parameters": \[` - -` {` - -` "type": "object",` - -` "name": "details",` - -` "description": "Information to identify the cookie to remove.",` - -` "properties": {` - -` "url": {"type": "string", "description": "The URL associated with the cookie. -If host permissions for this URL are not specified in the manifest file, the API -call will fail."},` - -` "name": {"type": "string", "description": "The name of the cookie to -remove."},` - -` "storeId": {"type": "string", "optional": true, "description": "The ID of the -cookie store to look in for the cookie. If unspecified, the cookie is looked for -by default in the current execution context's cookie store."}` - -` }` - -` }` - -` \]` - -` },` - -` {` - -` "name": "getAllCookieStores",` - -` "type": "function",` - -` "description": "Lists all existing cookie stores.",` - -` "parameters": \[` - -` {` - -` "type": "function",` - -` "name": "callback",` - -` "parameters": \[` - -` {` - -` "name": "cookieStores", "type": "array", "items": {"$ref": "CookieStore"}, -"description": "All the existing cookie stores."` - -` }` - -` \]` - -` }` - -` \]` - -` }` - -` \],` - -` "events": \[` - -` {` - -` "name": "onChanged",` - -` "type": "function",` - -` "description": "Fired when a cookie is set or removed.",` - -` "parameters": \[` - -` {` - -` "type": "object",` - -` "name": "changeInfo",` - -` "properties": {` - -` "removed": {"type": "boolean", "description": "True if a cookie was -removed."},` - -` "cookie": {"$ref": "Cookie", "description": "Information about the cookie that -was set or removed."}` - -` }` - -` }` - -` \]` - -` }` - -` \]` - -` }` - -`]` - -#### Sample code - -`function updateUserLoginStatusUi() {` -` chrome.experimental.cookies.get({` -` url: "http://www.mysite.com",` -` name: "MY_COOKIE"` -` }, function(cookie) {` -` if (cookie) {` -` displayLoggedInUi();` -` } else {` -` displayLoggedOutUi();` -` }` -` });` -`}` -`chrome.experimental.cookies.onChanged.addListener(function(changeInfo) {` -` updateUserLoginStatusUi();` -`});` - -`// Remove a cookie` - -`chrome.experimental.cookies.remove(` - -` {url: "http://www.mysite.com", name: "MY_COOKIE"});` - -`// Manually expire a cookie` - -`chrome.experimental.cookies.set(` - -` {` - -` url: "http://www.mysite.com",` - -` name: "MY_COOKIE",` - -` expirationDate: 0,` - -` }); ` -`function setSessionCookieForTab(tabId, url, name, value) { ` -` chrome.experimental.cookies.getAllCookieStores(function(cookieStores) { ` -` var i;` - -` for (i = 0; i < cookieStores.length; i++) {` - -` if (cookieStores[i].tabIds.indexOf(tabId) != -1) {` - -` chrome.experimental.cookies.set(` - -` {url: url, name: name, value: value, storeId: cookieStores[i].id});` - -` }` -` }` -` });` -`}`
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/push-messaging/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/push-messaging/index.md deleted file mode 100644 index 608b68ee325..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/push-messaging/index.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: push-messaging -title: Push Messaging ---- - -**You’re about to propose a new extension API, what a marvelous road you have -ahead of you. Before you venture forth, though, we’d like to get a sense for -your new API and offer you some guidance on your way. Fill out this proposal and -post it und**er [For Developers > Design Documents > Extensions > -Proposed & Proposing New Changes > API -Proposals](/developers/design-documents/extensions/proposed-changes/apis-under-development) -**in the list of proposed APIs, then include a link in your Extension Review -request in go/extensionsreview.** - -Proposal Date -2012/07/31 -Who is the primary contact for this API? -dimich@ - -Who will be responsible for this API? (Team please, not an individual) - -dcheng@, dimich@, petewil@ - -Overview -Web apps have the inherent limitation that they're not able to do much when they -aren't running. Today, extensions/apps use persistent background pages to do -interesting work even if they're not in the foreground; for example, they can -use it to poll the server for new emails and download them to a local store when -they're received. From a performance/efficiency standpoint, this is less than -desirable since it requires a mostly idle background page to just hang around -waiting for work. With new Chrome packaged apps and extension APIs that allow -background pages to be unloaded on idle, this will no longer be possible. As a -result, we believe it'd be useful to offer an API that would allow a remote -server to wake up a web app that's not currently running to do useful work. We -plan on implementing this API on top of the cache invalidation service that -Chrome is already using for Sync. -Use cases -Gmail/Google Docs: instead of polling the server for updates, they could -subscribe to push messages for their service. When there's actually an update, -then they can use the event to wake up their background page and update their -local store. -Google Talk: a push message would be triggered for the start of a new chat; this -would allow Google Talk to spawn a new chat window even when it's currently -unloaded. -Do you know anyone else, internal or external, that is also interested in this -API? -Google Talk is the most interested client, though it could be useful for Gmail -and Google Docs as well. -Could this API be part of the web platform? -It would be difficult to standardize this in the web platform because it depends -on many other server-side components such as: - -* Authentication -* The invalidation mechanism used -* The features supported - -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -We expose only a small subset of the cache invalidation service that Chrome uses -internally. The main limitation today is that we have a list of hardcoded -subchannels that we register on behalf of extensions; in the future, it's -possible that we'd allow extensions to specify their own subchannel names. We'd -likely have to keep the hardcoded subchannels around forever though, to avoid -breaking extensions that use those subchannels. - -**If multiple extensions used this API at the same time, could they conflict with each others? If so, how do you propose to mitigate this problem?** -They cannot conflict with each other, since we do not allow extensions to -specify any part of the object IDs registered on their behalf. -List every UI surface belonging to or potentially affected by your API: -No UI elements are involved. -**Actions taken with extension APIs should be obviously attributable to an -extension. Will users be able to tell when this new API is being used? How?** - -Invalidations may trigger actions that result in UI elements being surfaced. -Since we add no new UI elements ourselves, and existing ones should be obviously -attributable, the existing UI should be sufficient. - -How could this API be abused? -See below. -Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more): -1) The server could trigger a lot of invalidations. Presumably this would -eventually cause the app to get throttled on the server though... -2) An extension could claim it will manually acknowledge an invalidation and -never acknowledge it, allowing it to be woken up regularly. -3) An app writer could always add the pushMessaging to his permissions list, -whether or not he used it, causing the extension API to always register object -IDs for that extension even though they are not used. -What security UI or other mitigations do you propose to limit evilness made -possible by this new API? -To prevent extensions from being able to snoop on invalidations for other -users/extensions, we do not allow the extensions to actually specify their own -object IDs--we generate object IDs for an extension based on the signed-in user -+ the extension ID + the subchannel. - -In addition, to reduce server load, we always acknowledge receipt of an -invalidation immediately when we receive it from the cache invalidation server. -We re-dispatch invalidations to the extension ourselves and use a backoff policy -to prevent a faulty/malicious app from causing its background page to be woken -up excessively. -**Alright Doctor, one last challenge:** -**Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?** -**No. We unregister all object IDs registered on behalf of an extension when it is uninstalled. -How would you implement your desired features if this API didn't exist? -The user would have to make sure the app was constantly open for any -"background" functionality to work as expected. In the case of Google Talk, this -would require that the roster window always be opened. -Draft API spec -API reference: chrome.pushMessaging - -Methods: - -*getChannelId* - -*chrome.pushMessaging.getChannelId(function callback)* - -Retrieves the channel ID associated with an extension. This contains the -obfuscated user ID combined with the extension ID; the typical usage is for the -extension to send the channel ID to its app server to allow the app server to -trigger push messages. - -*callback ( function )* - -Called when channel ID has been retrieved. - -*Callback function:* - -The callback parameter should specify a function that looks like this: - -*function(string channelID) {...};* - -*channelID ( string )* - -Contains the channel ID of the extension. - -Events: - -*onMessage* - -*chrome.pushMessaging.onMessage.addListener(function(Message message) { ... });* - -Fired when a push message is received. - -*Listener parameters:* - -*message ( Message )* - -The data associated with the message. - -Types: - -*Message* - -*( object )* - -Stores data about a push message. - -*subchannel ( number )* - -The subchannel the push message was received for. - -*payload ( string)* - -The payload associated with the push message. Delivery of the payload is not -guaranteed; failure to deliver the payload will result in value being set to an -empty string. - -*willAcknowledge ( function )* - -An extension can call this to indicate that it will manually acknowledge the -receipt of the message. This is useful if the extension wants to do something -asynchronous in response to a push message and wants it to be re-delivered if it -isn't successfully handled for some reason. - -*acknowledge ( function )* -Allows an extension which called willAcknowledge() to acknowledge receipt of the -push message. -Open questions -willAcknowledge() and acknowledge() may not be possible to implement.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/rlz-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/rlz-api/index.md deleted file mode 100644 index 056bf308a65..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/rlz-api/index.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: rlz-api -title: RLZ Chrome API Proposal ---- - -## OBSOLETE -- the API has been removed in 2013. - -## **Overview** - -Google client products use a system called [RLZ](http://code.google.com/p/rlz) -to perform cohort tagging to manage promotion analysis. This is accomplished by -having the product record certain events in its life cycle, such as -installation, first Google search performed, home page set to Google, and so on, -and then forwarding that information to Google. - -This document proposes exposing some RLZ function as a Chrome Extension. - -For background documents, please see: - -* Chromium blog post: [In The Open, For - RLZ](https://blog.chromium.org/2010/06/in-open-for-rlz.html) -* Google Chrome Privacy Whitepaper: [Promotional - Tokens](https://www.google.com/intl/en/chrome/browser/privacy/whitepaper.html#tokens) -* [How to read an RLZ - string](https://github.com/rogerta/rlz/blob/wiki/HowToReadAnRlzString.md) -* The [RLZ open source project](https://github.com/rogerta/rlz/) - (since merged into the [main Chromium source - repo](https://chromium.googlesource.com/chromium/src/+/HEAD/rlz/)) - -## **Use Cases** - -This API can be useful to any chrome-internal extension that wants do promotion -analysis. - -## **Could this API be part of the web platform?** - -No. This API is specifically for managing promotions of chrome-internal -extensions. - -## **Do you expect this API to be fairly stable?** - -This API is expected to be very stable. No changes are required to this API to -support new chrome extensions. - -## **What UI does this API expose?** - -This API proposal does not expose any UI elements. - -## **How could this API be abused?** - -An extension could record events for different products or for access points it -does not own. This could result in incorrect assessment of partnership -distribution. This problem could be mitigated by restricting the products and/or -access points made visible through this API. For example, a chrome extension -should not affect Google Desktop or Chrome Omnibox access points. - -DoS attacks on Google are not possible since the underlying RLZ code prevents -more than one financial ping per product per 24 hour period for all RLZ users on -the same machine, not only chrome extensions. - -This API is hidden behind the command line argument used for experimental APIs. - -## **How would you implement your desired features if this API didn't exist?** - -If this API did not exist, we would need to re-implement the existing [RLZ open -source library](http://code.google.com/p/rlz) as a combination of javascript and -NPAPI plugin. - -## **Are you willing and able to develop and maintain this API?** - -Yes. - -**Will the API work on all platforms?** - -The RLZ library is Windows-only at the moment, so this API will only be -supported on Windows until RLZ is adapted to work on other platforms. - -**Draft API spec** - -> Use the chrome.experimental.rlz module to record an RLZ events in your -> extension's life cycle. - -> *Methods* - -> **recordProductEvent** - -> chrome.experimental.rlz.recordProductEvent(string *product*, string -> *accessPoint*, string *event*) - -> Records an RLZ event for a given product's access point. - -> ***Parameters*** - -> *product (string)* - -> A one-letter product name for the chrome-internal extension. This name should -> be unique within the RLZ product name space. Refer to the function -> [GetProductName()](http://code.google.com/p/rlz/source/browse/trunk/win/lib/lib_values.cc) -> in the RLZ code. - -> *accessPoint (string)* - -> A two-letter access point name used within the extension. This name should be -> unique within the RLZ access point name space. Refer to the function -> [GetAccessPointName()](http://code.google.com/p/rlz/source/browse/trunk/win/lib/lib_values.cc) -> in the RLZ code. - -> *event (string)* - -> A string representing the name of the event that occurred on the access point. -> Valid possibilities: - -> <table> -> <tr> -> <td><b>Name</b></td> -> <td><b>Description</b></td> -> </tr> -> <tr> -> <td>`install`</td> -> <td>Access point installed on the system</td> -> </tr> -> <tr> -> <td>`set-to-google`</td> -> <td>Point set from non-Google provider to Google</td> -> </tr> -> <tr> -> <td>`first-search`</td> -> <td>A first search has been performed from this access point since installation </td> -> </tr> -> <tr> -> <td>`activate`</td> -> <td>Product being used for a period of time </td> -> </tr> -> </table> - -> **clearProductState** - -> chrome.experimental.rlz.clearProductState(string *product*, string\[\] -> *accessPoints*) - -> Clears all product-specific RLZ state from the machine, as well as clearing -> all events for the specified access points. This function should be called -> when the extension is uninstalled. - -> *Is there any way for an extension to know it is being uninstalled so that it -> can make this call?* - -> ***Parameters*** - -> *product (string)* - -> *A one-letter product name for the chrome-internal extension. This name should be unique within the RLZ product name space. Refer to the function [GetProductName()](http://code.google.com/p/rlz/source/browse/trunk/win/lib/lib_values.cc) in the RLZ code.* - -> *accessPoints (array of string)* - -> An array of two-letter access point names used within the extension. Each name -> should be unique within the RLZ access point name space. Refer to the function -> [GetAccessPointName()](http://code.google.com/p/rlz/source/browse/trunk/win/lib/lib_values.cc) -> in the RLZ code. - -> ****sendFinancialPing**** - -> **chrome.experimental.rlz.sendFinancialPing(string *product*, string\[\] *accessPoints, signature, brand, id, lang, exclude_machine_id, callback*)** - -> **Sends a ping with promotional RLZ information to Google.** - -> *******Parameters******* - -> ***product (string)*** - -> ***A one-letter product name for the chrome-internal extension. This name should be unique within the RLZ product name space. Refer to the function [GetProductName()](http://code.google.com/p/rlz/source/browse/trunk/win/lib/lib_values.cc) in the RLZ code.*** - -> ***accessPoints (array of string)*** - -> **An array of two-letter access point names used within the extension. Each name should be unique within the RLZ access point name space. Refer to the function [GetAccessPointName()](http://code.google.com/p/rlz/source/browse/trunk/win/lib/lib_values.cc) in the RLZ code.** - -> **signature *(string)*** - -> **A** - -> ******product-specific signature****** - -> **string of the product.**** - -> **brand *(string)*** - -> **A promotional brand code assigned to the product.** - -> **************Can be an empty string.************** - -> **id *(string)*** - -> **A product-specific installation id. Can be an empty string.** - -> **lang *(string)*** - -> **The language of the product. Used to determine cohort.** - -> ********Can be an empty string.******** - -> **exclude_machine_id *(boolean)*** - -> **If true, the machine specific id will be excluded from the ping.** - -> **callback *(function)*** - -> **A function that takes one boolean argument indicating whether the ping was successfully sent or not.** - -> **getAccessPointRlz** - -> chrome.experimental.rlz.getAccessPointRlz(string *accessPoint,* function -> *callback*) - -> Gets the RLZ string to be used when accessing a Google property through the -> given access point. This string should be used in an `rlz=` CGI parameter in -> the Google property URLs. - -> ***Parameters*** - -> **accessPoint (string)** - -> *A two-letter access point name used within the extension. This name should be unique within the RLZ access point name space. Refer to the function [GetAccessPointName()](http://code.google.com/p/rlz/source/browse/trunk/win/lib/lib_values.cc) in the RLZ code.* - -> **callback (function)** - -> *A function that takes one string argument, which is the RLZ string for the given access point.*
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/settings/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/settings/index.md deleted file mode 100644 index bd78407c52a..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/settings/index.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: settings -title: Settings API ---- - -**Overview** - -This page proposes adding methods/events to chrome.settings to let extensions -store settings data (assumed to be small pieces of string-like data) that is -synced across a user's browser instances. Initially, the module would start in -the chrome.experimental.settings namespace. - -**Use cases** - -Ever since extensions/apps sync was implemented, extension settings sync has -been an oft-requested and -[anticipated](http://googlesystem.blogspot.com/2010/12/predictions-for-googles-2011.html) -feature. Syncing an extension's settings greatly enhances the usefulness of -extension sync. - -**Could this API be part of the web platform?** - -No. - -**Do you expect this API to be fairly stable?** - -Yes. This API is based on the HTML5 storage spec which is unlikely to change -much. - -**What UI does this API expose?** - -No additional UI is exposed. However, we may need to add UI to -chrome://extensions for turning off settings sync for particular extensions. On -the other hand, extension developers could do this themselves. - -**How could this API be abused?** - -An ill-behaved extension could create lots of data to sync, bogging down both -the client and the server. This may also cause the user to be throttled, -possibly affecting sync for other data types (e.g., bookmarks, preferences). - -**How would you implement your desired features if this API didn't exist?** - -Currently, extensions sync their settings by stuffing data in bookmarks. This is obviously very hacky and causes problems for sync. - -**Are you willing and able to develop and maintain this API?** - -The sync team can develop and maintain this API. - -**Draft API spec** - -It might be helpful to refer to docs for the HTML5 storage spec: see [this -overview](http://diveintohtml5.org/storage.html) and [the spec -itself](http://dev.w3.org/html5/webstorage/). - -> **API Reference: chrome.experimental.settings (later -> chrome.extension.settings)** - -> **Methods** - -> **getSettings** - -> chrome.experimental.settings.getSettings(function callback) - -> **Parameters** - -> ***callback ( function )*** - -> **Callback function** - -> The callback parameter should specify a function that looks like this: - -> function(Storage settings) {...} - -> **settings ( Storage )** - -> **The settings Storage object. It is guaranteed that nothing else will access this (including sync) for the lifetime of the callback.** - -> **Events** - -> **onSettingsChanged** - -> chrome.experimental.settings.onSettingChanged.addListener(function(StorageEvent -> e) {...}); - -> Fires when a setting has been changed, either locally or from another browser -> instance. - -> **Parameters** - -> **e ( StorageEvent )** - -> Details of the setting that was changed. - -* The Storage object passed to the getSettings callback behaves very - similarly to the localStorage object; it is persisted across browser - restarts and is per-profile. However, any changes made to it may - eventually be synced to other browser instances with synced turned - on. Also, the onSettingsChanged event may be fired when changes from - other browser instances are synced to the local one. -* No guarantees are made as to how long it takes for changes to - propagate, or even if they're propagated at all. Sync may be turned - off, clients may be throttled, and other reasons may prevent or - delay propagation. -* Each top-level key-value pair is guaranteed to be synced atomically. - That is, while settings\["a"\] and settings\["b"\] may be synced - independently, two clients writing separate values to the same key - will cause the final state to be either one or the other. However, - the settings Storage object at worst behaves like another - localStorage. -* The storage limits for the settings Storage object are more - stringent than localStorage; tentatively, it is planned that each - key/value pair can have a maximum of 16kb, and the total storage for - an extension cannot exceed 100kb. It is expected that the most - common use case for this are small pieces of string-like data, e.g. - settings and preferences. -* Extension developers must take care not to modify settings too often - or else they risk being throttled (if they do on the order of - hundreds or thousands of changes in a 24 hour period). -* Sync will only kick in after a call to getSettings to propagate any - changed settings and/or apply any new settings. This means that an - extension developer has some control on how often sync fires. -* Uninstalling an extension currently clears all settings data for it. - (This may be surprising in some cases; we may need to revisit this - in the future.) -* This API will have its own manifest permission ("settings") but - won't trigger a warning. - -> Example usage: - -> // Imagine an extension that retrieves data from a particular URL. - -> chrome.experimental.settings.getSettings(function(settings) { - -> // Do initial frobnigation, setting a default value if necessary. - -> var dataUrl = settings\["dataUrl"\]; - -> if (!dataUrl) { - -> // This will be propagated to other browser instances after this - -> // callback. - -> dataUrl = settings\["dataUrl"\] = "http://www.foo.com/mydata"; - -> } - -> doInitialFrobnigate(dataUrl); - -> }); - -> // Do an update every time the dataUrl setting is changed (either - -> // locally or remotely). - -> chrome.experimental.settings.onSettingChanged.addListener(function(e) { - -> if (e.key == "dataUrl") { - -> console.info("Changing data URL from " + e.oldValue + " to " + e.newValue); - -> doUpdateFrobnigate(e.newValue); - -> } - -> }); - -> Example code demonstrating when it's okay to access the settings object: - -> chrome.extension.settings.getSettings(function(settings) { -> // While this callback is being invoked, the extension has exclusive access to -> the settings. -> // At other times the extension does not have access. We do this to avoid -> raciness between -> // multiple processes manipulating the data concurrently. -> var foo = settings.foo; -> settings.foo = foo + 1; // using settings object here is OK -> window.setTimeout(function() { -> // This is invalid! The extension no longer has access to |settings|. We need -> to make it -> // so that trying to read or write from the settings object after the callback -> is complete -> // throws an error. -> alert(settings.foo); -> }, 1000); -> // Access to the extension's settings goes away at the end of this callback. -> }); - -**Open questions** - -* Is there a need for syncing other types of data, e.g. large pieces - of data or structured data? -* Do we need anything for the enterprise use case? It may be useful to - be able to provide a default settings object and maybe even to mark - some settings non-editable.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/settings_pages/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/settings_pages/index.md deleted file mode 100644 index a69327c065d..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/settings_pages/index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: settings_pages -title: Settings pages ---- - -**Overview** - -We want to enable extensions to provide custom settings UI to extend the (more -and more) minimal settings UI that is build into Chrome. - -**Use cases** - -Similarly to e.g. browser actions, an extension can define a HTML file in its -manifest that it wants to be rendered as part of Chrome's settings UI. We -provide a set of widgets (CSS and JavaScript) that an extension can use to -render its UI using the same theme as Chrome's settings UI, however, extensions -are free to display arbitrary UI. - -**Could this API be part of the web platform?** - -no - -**Do you expect this API to be fairly stable?** - -The API itself will be stable. We might change/extend the JavaScript/CSS -provided to render the settings UI in the future, however, I expect that it will -be possible to do this in a non-breaking way. - -**What UI does this API expose?** - -An extension using this API can display arbitrary HTML as part of Chrome's -settings UI. - -**How could this API be abused?** - -An extension using this API can pretend to e.g. manage your passwords, but -instead send all passwords you enter to a third-party site. A possible way to -mitigate this risk would be to disallow all communication with other extension -pages or network resources from settings page. An extension could also mess up -your settings, but it already can do so from the background page. - -In order to avoid an extension accessing the APIs available to Chrome's settings -UI, the extension settings page would be rendered in an sandboxed iframe. - -**How would you implement your desired features if this API didn't exist?** - -An extension could define a browser action or an options page and allow the user -to configure settings from there. Option pages, however, are meant for settings -for the extension, not settings for the browser. Browser actions aren't where -the user expects browser settings either. - -**Are you willing and able to develop and maintain this API?** - -Yes.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/system-indicator-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/system-indicator-api/index.md deleted file mode 100644 index dc8ff3aa3ae..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/system-indicator-api/index.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: system-indicator-api -title: System Indicator API ---- - -**Proposal Date** -**14 November 2012** -**Who is the primary contact for this API?** -**dewittj@** -**Who will be responsible for this API? (Team please, not an individual)** - -**dimich@, dewittj@** - -**Overview** -**This API would serve two main purposes: first, to provide a system-wide status indication, appearing as an icon in the system tray area. Alongside this API, we would extend the chrome.contextMenus API to also control the system indicator context menu.** -**There is a class of applications that require the ability to let the user know, at a glance, the status of the application, regardless of what else is running on the system. These applications tend to fall into a few classes:** - -1. **Apps that wait for incoming events but do not have their own - windows in the common case - e.g. chat, where a user needs to know - that everything is OK with the application (online, available - status) at a glance even when the app is otherwise idle.** -2. **System status apps - e.g. a WiFi indicator app, which a user will - check the app when she needs to either determine if a connection has - been made, or troubleshoot her system** -3. **Resource usage indicators - e.g. a battery indicator, that inform - a user’s behavior over a long period of time (do I have x enough - battery to write this document before finding an outlet? Is my - battery draining more quickly than usual?)** - -**Many applications can use such an API to make it easier for users to interact with their app. An app that requires frequent short interaction, such as a chat app, can make use of this to both create a visual cue that action needs to be taken (such as reading an incoming chat message), and to allow the user to bring into focus any existing chat conversations, or the contact roster panel.** -**This API exposes an icon whose behavior and support varies across operating systems. Frequently, users are allowed to hide icons; in some cases, such as ChromeOS, there is no appropriate area for such an icon. Accordingly, this API will expose functionality on a best-effort basis. Apps should provide all functionality exposed through this API in other places as well.** -**[Example usage and -images](https://docs.google.com/document/d/1QhhfR33Y28Yqnnoa_Sl3fnZK_mKtwt4dZe6kNyJ_MjU/edit)** - -**Do you know anyone else, internal or external, that is also interested in this API?** -**Currently the “Chat for Google” application installs an NPAPI plugin to achieve this functionality. Already, NPAPI plugins are disabled on some systems and their use going forward is being discouraged. This API would allow them to remove their system indicator binary plugin and rely on Chrome APIs instead.** -**Could this API be part of the web platform?** -**This API is fundamental to long-running offline applications. As such it is not appropriate for the OWP.** -**Do you expect this API to be fairly stable? How might it be extended or changed in the future?** -**This API itself is minimal - only enabling apps to show and hide icons. Because the most complex portions of this feature will be within the chrome.contextMenus API, this API is expected to remain quite stable.** -**If multiple extensions used this API at the same time, could they conflict with each others? If so, how do you propose to mitigate this problem?** -**Multiple apps could indeed use this API at the same time. The system tray has historically been a place that every app wants to have a presence in, despite its extremely limited real estate. This will be mitigated by restricting apps to one indicator icon (or zero).** -**List every UI surface belonging to or potentially affected by your API:** -**This API would affect the system indicator area appropriate to each platform (OSX: the menu bar, Windows and Linux: the system tray), by adding an icon and exposing a menu on click.** -**Actions taken with extension APIs should be obviously attributable to an extension. Will users be able to tell when this new API is being used? How?** -**Icons used for this menu will be distributed with the extension, and there will be hovertext over the icon that shows the app’s name.** -**How could this API be abused?** -**This API could be abused by creating functionality that is only exposed through the menus or click event of the system tray. Since not all platforms support it, this would create a highly inaccessible and inconsistent experience across platforms. Additionally this API could be used to incessantly attract user attention.** -**Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):** -**1) I could pretend to be an application that I’m not** -**2) I could write a bunch of extensions that all take icon space in the indicator area** -**3) I could create distracting icons and constantly draw the user’s attention to my app.** -**What security UI or other mitigations do you propose to limit evilness made possible by this new API?** - -* **We will require that the hovertext of this icon be the app’s name - to prevent spoofing** -* **Other evil acts would best be mitigated by uninstalling an - offending app.** - -**Alright Doctor, one last challenge:** -**Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?** -**This API should not leave anything behind. The indicator icon will only be visible when the app is listening for messages, so removing the app will prevent any indicator from being shown.** -**How would you implement your desired features if this API didn't exist?** -**Currently the way to do this is via NPAPI plugins.** -**Draft Manifest Changes** -**This will require a new ‘systemIndicator’ permission so that users know that they’re volunteering access to the system indicator area.** -**Draft API spec** -*// Manages an app's system indicator icon, an image displayed in the system's -// menubar, system tray, or other visible area provided by the OS. namespace -systemIndicator {* - -*dictionary SetIconDetails {* - -*// Path should be either a string representing an icon loaded with the app -manifest,* - -*// or a dictionary representing multiple resolutions of the same icon that are -to* - -*// be used on systems with different icon sizes, or DPI scaling factors.* - -*any? path;* - -*// ImageData should be either a single ImageData object (typically from a -canvas* - -*// element) or a dictionary representing multiple resolutions of the same icon. -any? imageData; }; callback DoneCallback = void (); interface Functions { // Set -the image to be used as an indicator icon, using a set of ImageData // objects. -These objects should have multiple resolutions so that an // appropriate size -can be selected for the given icon size and DPI scaling // settings. Only square -ImageData objects are accepted. static void setIcon(SetIconDetails details, -optional DoneCallback callback); // Show the icon in the status tray. static -void enable(optional DoneCallback callback); // Hide the icon from the status -tray. static void disable(optional DoneCallback callback); }; interface Events { -// Fired only when a click on the icon does not result in a menu being // shown. -static void onClicked(); }; };* - -Open questions - -* System indicator areas are slowly being removed from each operating - system. Win8 Metro doesn’t have one at all, and ChromeOS’ area is - restricted to a few explicitly allowed native applications. How will - the functionality from this API be exposed if this trend continues? - Currently we are treating this API as providing an optional service - that should not break functionality of the app if the icon and menu - fail to display on a user’s system. -* Different operating systems have different human interface - guidelines for icons appearing in the status area. For example, Mac - OS icons in the title bar area are typically black and white. How - should this difference be exposed to the API consumer?
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/systeminfo/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/systeminfo/index.md deleted file mode 100644 index afb28dccd30..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/systeminfo/index.md +++ /dev/null @@ -1,315 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: systeminfo -title: SystemInfo Extension API ---- - -Intel Open Technology Center - -[hongbo.min@intel.com,](mailto:hongbo.min@intel.com,) -[ningxin.hu@intel.com](mailto:ningxin.hu@intel.com), -[james.p.ketrenos@intel.com](mailto:james.p.ketrenos@intel.com) - -## Overview - -This API is intended to provide extension with a set of interfaces to get -hardware devices information, such as CPU and memory status, OS information, -disk storage and network state etc. - -The followings are some typical usage cases of SystemInfo API but not limited to -these: - -1. An extension or packaged app can query the number of processors to - determine the optimal number of WebWork to be created. -2. An extension or packaged app can decide which binary should be - downloaded and used according to the CPU architecture, e.g. NaCl - module. -3. An extension can check if there is enough storage space to a huge - file before downloading it from Internet. -4. An extension or packaged app can popup a media gallery app if the - new storage attached is a MTP-compatible device. -5. A packaged app is allowed to create app window on the external - display with display information. - -#### SystemInfo in W3C - -The SysApps Working Group is working on defining a set of System-Level API for -web application, including [Device Capabilities -API](http://device-capabilities.sysapps.org/). The purpose is the same as -SystemInfo extension API which allows web app to access system information. - -## Design and Considerations - -### Namespace and Permission - -The namespace for SystemInfo API is `chrome.system`, and currently has the -following categories: - -* chrome.system.cpu -* chrome.system.storage -* chrome.system.memory -* chrome.system.display -* … - -Obviously, the `chrome.system` namespace can be easily extended in future if a -new system level API is introduced. The corresponding permission is also simple -and straightforward: - -* system.cpu -* system.storage -* system.memory -* system.display - -### Implementation Notes - -The design goals of the new SystemInfo extension API introduction are: - -1. No need to pay the additional overhead if an extension or packaged - app won't need to query system information at, e.g. no extra memory - footprint at runtime. -2. Efficiently handle too-frequent querying operation. Although it - seems a corner case since few app will query the same information - repeatly, we take it into consideration to avoid such an exception - and make Chrome much robust. - -A base class `SystemInfoProvider `is abstracted away for every system -information retrieval. It will: - -1. Maintain a callback queue for the incoming query request; -2. Post the query operation to non-UI thread. The logic of how to query - the requested information is implemented in each derived class of - `SystemInfoProvider`; -3. Forward the query result to each callback in the queue once the - query is completed - -In order to satisfy the minimal overhead required by design goal, each app using -the API won't pay for what it don't use, the lifetime of each concrete -`SystemInfoProvider `implementation is - -1. Created on demand. This mean the instance should be only created - when it is needed -2. Singleton instance. All apps using this API can share one - InfoProvider. - -Currently, we have `CpuInfoProvider `for `system.cpu` API set implementation, -`StorageInfoProvider `for `system.display`, `DisplayInfoProvider `for -`system.display`, and `MemoryInfoProvider `for `system.memory`. - -## Extension API IDL - -### CPU Info API - -` dictionary CpuInfo {` -` // The number of logical processors.` -` long numOfProcessors;` -` // The architecture name of the processors.` -` DOMString archName;` -` // The model name of the processors.` -` DOMString modelName;` -` };` -` callback CpuInfoCallback = void (CpuInfo info);` -` interface Functions {` -` // Queries basic CPU information of the system.` -` static void getInfo(CpuInfoCallback callback);` -` };` - -### Storage Info API: - -`enum StorageUnitType {` -` // The storage has fixed media, e.g. hard disk or SSD.` -` fixed,` -` // The storage is removable, e.g. USB flash drive.` -` removable,` -` // The storage type is unknown.` -` unknown` -` };` -` dictionary StorageUnitInfo {` -` // The unique storage id. It will use the transient ID.` -` DOMString id;` -` // The name of the storage unit.` -` DOMString name;` -` // The media type of the storage unit.` -` StorageUnitType type;` -` // The total amount of the storage space, in bytes.` -` // Default value is 0 if query operation fails.` -` double capacity;` -` };` -` enum EjectDeviceResultCode {` -` // The ejection command is successful -- the application can prompt the user` -` // to remove the device.` -` success,` -` // The device is in use by another application. The ejection did not` -` // succeed; the user should not remove the device until the other` -` // application is done with the device.` -` in_use,` -` // There is no such device known.` -` no_such_device,` -` // The ejection command failed.` -` failure` -` };` -` callback StorageInfoCallback = void (StorageUnitInfo[] info);` -` callback EjectDeviceCallback = void (EjectDeviceResultCode result);` - -` callback GetAvailableCapabilityCallback = void (double availableCapability);` - -` interface Functions {` -` // Get the storage information from the system. The argument passed to the` -` // callback is an array of StorageUnitInfo objects.` -` static void getInfo(StorageInfoCallback callback);` -` // Ejects a removable storage device.` -` // Note: We plan to move this function into a namespace that indicates it` -` // that modifies the state of the system rather than just gathering` -` // information.` -` static void ejectDevice(DOMString id, EjectDeviceCallback callback);` -` };` -` interface Events {` -` // Fired when a new removable storage is attached to the system.` -` static void onAttached(StorageUnitInfo info);` -` // Fired when a removable storage is detached from the system.` -` static void onDetached(DOMString id);` - -` // Get the available capability, in bytes` -` static void getAvailableCapacity(DOMString id, GetAvailableCapabilityCallback -callback);` - -` };` - -### Memory Info API - -` dictionary MemoryInfo {` -` // The total amount of physical memory capacity, in bytes.` -` double capacity;` -` // The amount of available capacity, in bytes.` -` double availableCapacity;` -` };` -` callback MemoryInfoCallback = void (MemoryInfo info);` -` interface Functions {` -` // Get physical memory information.` -` static void getInfo(MemoryInfoCallback callback);` -` };` - -### Display Info API - -` dictionary Bounds {` -` // The x-coordinate of the upper-left corner.` -` long left;` -` // The y-coordinate of the upper-left corner.` -` long top;` -` // The width of the display in pixels.` -` long width;` -` // The height of the display in pixels.` -` long height;` -` };` -` dictionary Insets {` -` // The x-axis distance from the left bound.` -` long left;` -` // The y-axis distance from the top bound.` -` long top;` -` // The x-axis distance from the right bound.` -` long right;` -` // The y-axis distance from the bottom bound.` -` long bottom;` -` };` -` dictionary DisplayUnitInfo {` -` // The unique identifier of the display.` -` DOMString id;` -` // The user-friendly name (e.g. "HP LCD monitor").` -` DOMString name;` -` // Identifier of the display that is being mirrored on the display unit.` -` // If mirroring is not in progress, set to an empty string.` -` // Currently exposed only on ChromeOS. Will be empty string on other` -` // platforms.` -` DOMString mirroringSourceId;` -` // True if this is the primary display.` -` boolean isPrimary;` -` // True if this is an internal display.` -` boolean isInternal;` -` // True if this display is enabled.` -` boolean isEnabled;` -` // The number of pixels per inch along the x-axis.` -` double dpiX;` -` // The number of pixels per inch along the y-axis.` -` double dpiY;` -` // The display's clockwise rotation in degrees relative to the vertical` -` // position.` -` // Currently exposed only on ChromeOS. Will be set to 0 on other platforms.` -` long rotation;` -` // The display's logical bounds.` -` Bounds bounds;` -` // The display's insets within its screen's bounds.` -` // Currently exposed only on ChromeOS. Will be set to empty insets on` -` // other platforms.` -` Insets overscan;` -` // The usable work area of the display within the display bounds. The work` -` // area excludes areas of the display reserved for OS, for example taskbar` -` // and launcher.` -` Bounds workArea;` -` };` -` dictionary DisplayProperties {` -` // If set and not empty, starts mirroring between this and the display with` -` // the provided id (the system will determine which of the displays is` -` // actually mirrored).` -` // If set and not empty, stops mirroring between this and the display with` -` // the specified id (if mirroring is in progress).` -` // If set, no other parameter may be set.` -` DOMString? mirroringSourceId;` -` // If set to true, makes the display primary. No-op if set to false.` -` boolean? isPrimary;` -` // If set, sets the display's overscan insets to the provided values. Note` -` // that overscan values may not be negative or larger than a half of the` -` // screen's size. Overscan cannot be changed on the internal monitor.` -` // It's applied after <code>isPrimary</code> parameter.` -` Insets? overscan;` -` // If set, updates the display's rotation.` -` // Legal values are [0, 90, 180, 270]. The rotation is set clockwise,` -` // relative to the display's vertical position.` -` // It's applied after <code>overscan</code> paramter.` -` long? rotation;` -` // If set, updates the display's logical bounds origin along x-axis. Applied` -` // together with <code>boundsOriginY</code>, if <code>boundsOriginY</code>` -` // is set. Note that, when updating the display origin, some constraints` -` // will be applied, so the final bounds origin may be different than the one` -` // set. The final bounds can be retrieved using $ref:getInfo.` -` // The bounds origin is applied after <code>rotation</code>.` -` // The bounds origin cannot be changed on the primary display. Note that is` -` // also invalid to set bounds origin values if <code>isPrimary</code> is` -` // also set (as <code>isPrimary</code> parameter is applied first).` -` long? boundsOriginX;` -` // If set, updates the display's logical bounds origin along y-axis.` -` // See documentation for <code>boundsOriginX</code> parameter.` -` long? boundsOriginY;` -` };` -` callback DisplayInfoCallback = void (DisplayUnitInfo[] displayInfo);` -` callback SetDisplayUnitInfoCallback = void();` -` interface Functions {` -` // Get the information of all attached display devices.` -` static void getInfo(DisplayInfoCallback callback);` -` // Updates the properties for the display specified by |id|, according to` -` // the information provided in |info|. On failure, $ref:runtime.lastError` -` // will be set.` -` // |id|: The display's unique identifier.` -` // |info|: The information about display properties that should be changed.` -` // A property will be changed only if a new value for it is specified in` -` // |info|.` -` // |callback|: Empty function called when the function finishes. To find out` -` // whether the function succeeded, $ref:runtime.lastError should be` -` // queried.` -` static void setDisplayProperties(` -` DOMString id,` -` DisplayProperties info,` -` optional SetDisplayUnitInfoCallback callback);` -` };` -` interface Events {` -` // Fired when anything changes to the display configuration.` -` static void onDisplayChanged();` -` };`
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/text-translate-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/text-translate-api/index.md deleted file mode 100644 index 1ddd0c044af..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/text-translate-api/index.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: text-translate-api -title: Text Translate API ---- - -## Problem - -Extension developers would like to be able to translate the text of pages. -Transforming arbitrary DOM trees into blocks of text of suitable length for -translation is hard, and potentially time consuming if done naively. Noticing -dynamic updates to the page is also difficult to do correctly. Also, modifying -the content of text nodes may confuse some web applications who weren't -expecting mutation events to occur (this is probably a minor problem though). - -## Proposal - -Expose an API that can feed an extension process blocks of text to translate. -Chromium takes care of the hard work of creating nice blocks of text, removing -html tags, noticing dynamic updates, handling races between the extension and -renderer process, and modifying the text of the page in the most compat-friendly -way. - -The extension just has to translate and return the text when requested. - -## API - -chrome.textTranslate - -// Start translating text for the specified tab. The callback gets called - -// repeatedly until stop() is called. Each time it is called it will pass - -// a block of text that needs translating. - -// NOTE: tab.documentId doesn't yet exist and needs to be added. - -void start(int tabId, int documentId, void callback(int blockId, string text)) - -// The extension should call this function when a block of text has been - -// translated. - -void updateBlock(int blockId, string translatedText)) - -// Stop translating text for a tab. - -void stop(int tabId, int documentId) - -## Example Usage - -// Start translating - -chrome.tabs.getCurrent(null, function(tab) { - -chrome.textTranslate.start(tab.id, tab.documentId, translate); - -}); - -function translate(blockId, text) { - -var req = new XMLHttpRequest(); - -req.open("POST", "http://www.google.com/sometranslateservice", false); - -req.onreadystatechange = function() { - -if (req.readyState == 4) { - -chrome.textTranslate.updateBlock(blockId, req.responseText); - -} - -} - -req.send(null); - -} - -## Implementation Details - -TODO: Flesh this area out Here are some ideas: - -* It seems reasonable for a "block" to just be any block-level - element, such as "div", and "p". -* Invalidation should happen on a block level. So if a text node - inside a block changes, the whole block is retranslated. But if a - parent node of a block changes, the block is not retranslated. -* There will have to be code in the renderer tracking outstanding - translate requests so that they can be abandoned if the related - blocks change. -* If possible, we should do the text modification at the CSS layer in - webcore so that it is not visible to the web page (similar to how - text-transform is implemented today).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/usb-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/usb-api/index.md deleted file mode 100644 index 02024fe7ec3..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/usb-api/index.md +++ /dev/null @@ -1,416 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: usb-api -title: USB API ---- - -Proposal Date - -March 7th, 2012 -Who is the primary contact for this API? -gdk@chromium.org -Who will be responsible for this API? (Team please, not an individual) - -Apps Extension API Team - -Overview -The USB API aims to provide access to fundamental low-level USB operations from -within the context of an extension. -Use cases - -- Devices which require third-party drivers to function in ChromeOS are -currently unusable. One of the use cases for this API would be to provide the -ability for a Chrome extension to function as a device driver and allow -previously unusable devices to be used under ChromeOS. - -- Conversely, this would also allow device driver implementors to be able to -quickly deploy new driver versions to applications which are written within -Chrome that make use of USB functionality, instead of depending on writing -platform-dependent code. -Do you know anyone else, internal or external, that is also interested in this -API? -Not yet. -Could this API be part of the web platform? - -Maybe. This API has the potential to be very controversial, and I believe there -are people within the standards organization that would not back it. - -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? - -The API should remain fairly stable, as the fundamental mechanism for -interacting with USB devices is standardized and does not change. This API will -surface the underlying USB mechanisms for communication, and so itself should -not need to change. - -List every UI surface belonging to or potentially affected by your API: - -- The extension installation dialog box (potentially). There should be a -mechanism for informing users about the kinds of USB devices that an extension -wishes to access, and this information should be surfaced. - -How could this API be abused? - -- This API could be used (without per-extension VID/PID lockdown) to map the -devices attached to a computer, thereby gaining knowledge outside of the scope -of the extension. - -- This API could be used to cause physical devices to damage themselves or their -surroundings. I've yet to see a printer catch fire due to software commands, but -I would not rule the possibility out, for example. - -Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you -could commit with your API (if you’ve got good ones, feel free to add more): -1) Use a USB-attached device to cause physical harm. -2) Cause permanent harm to a USB device. -3) TODO. -Alright Doctor, one last challenge: -Could a consumer of your API cause any permanent change to the user’s system -using your API that would not be reversed when that consumer is removed from the -system? - -Yes. There are circumstances where a USB device could be put into a bad state -(or frozen entirely!) that may be impossible to restore to a pristine state -without physically reconnecting the device. The attached devices could also, for -example, themselves leave a physical trace. A printer driver could print a page, -a CD writer could write a disc, a robot karate arm could break a table, etc. - -How would you implement your desired features if this API didn't exist? - -By writing code that used libusb and then surfacing some form of WebSocket -interface that would allow a client to communicate with my device-specific -server. - -Draft API spec - -## API reference: chrome.experimental.usb - -### Methods - -#### bulkTransfer - -chrome.experimental.usb.bulkTransfer(integer device, string direction,integer -endpoint, string data, function callback) - -Performs a USB bulk transfer to the specified device. - -#### Parameters - -device - -*( integer )* - -A device handle on which the transfer is to be made. - -direction - -*( string )* - -The direction of the control transfer. "in" for an inbound transfer, "out" for -an outbound transfer. - -endpoint - -*( integer )* - -The endpoint to which this transfer is being made. - -data - -*( string )* - -(TODO(gdk): ArrayBuffer) The bulk data payload for this transfer. - -callback - -*( optional function )* - -A callback to be invoked with the results of this transfer. - -#### Callback function - -If you specify the *callback* parameter, it should specify a function that looks -like this: - -function(object result) {...}; - -result - -*( object )* - -data - -*( optional string )* - -(TODO(gdk): ArrayBuffer) If the transfer results in inbound data, it is returned -here. - -result - -*( integer )* - -On success, 0 is returned. On failure, -1. - -#### closeDevice - -chrome.experimental.usb.closeDevice(integer device, undefined callback) - -Close a USB device handle. - -#### Parameters - -device - -*( integer )* - -The device handle to be closed. - -callback - -*( optional function )* - -A callback function that is invoked after the device has been closed. - -#### controlTransfer - -chrome.experimental.usb.controlTransfer(integer device, string direction, string -recipient, string type,integer request, integer value, integer index, string -data, function callback) - -Performs a USB control transfer to the specified device. - -#### Parameters - -device - -*( integer )* - -A device handle on which the transfer is to be made. - -direction - -*( string )* - -The direction of the control transfer. "in" for an inbound transfer, "out" for -an outbound transfer. - -recipient - -*( string )* - -The intended recipient of this message. Must be one of "device", "interface", -"endpoint" or "other". - -type - -*( string )* - -The type of this request. Must be one of "standard", "class", "vendor" or -"reserved". - -request - -*( integer )* - -value - -*( integer )* - -index - -*( integer )* - -data - -*( string )* - -(TODO(gdk): ArrayBuffer) The data payload carried by this transfer. - -callback - -*( optional function )* - -An optional callback that is invoked when this transfer completes. - -#### Callback function - -If you specify the *callback* parameter, it should specify a function that looks -like this: - -function(object result) {...}; - -result - -*( object )* - -data - -*( optional string )* - -(TODO(gdk): ArrayBuffer) If the transfer is inbound, then this field is -populated with the data transferred from the device. - -result - -*( integer )* - -On success, 0 is returned. On failure, -1. - -#### createContext - -chrome.experimental.usb.createContext(function callback) - -Creates a USB context by which devices may be found. - -#### Parameters - -callback - -*( function )* - -#### Callback function - -The callback *parameter* should specify a function that looks like this: - -function(integer result) {...}; - -result - -*( integer )* - -The handle to the created context. On failure, -1. - -#### destroyContext - -chrome.experimental.usb.destroyContext(integer context) - -Disposes of a context that is no longer needed. It is not necessary that this -call be made at all, unless you want to explicitly free the resources associated -with a context. - -#### Parameters - -context - -*( integer )* - -#### findDevice - -chrome.experimental.usb.findDevice(integer context, integer vendorId, integer -productId, function callback) - -Locates an instance of the device specified by its vendor and product -identifier. - -#### Parameters - -context - -*( integer )* - -A handle to a USB context. - -vendorId - -*( integer )* - -The vendor ID of the device to search for. - -productId - -*( integer )* - -The product ID of the device to search for. - -callback - -*( function )* - -#### Callback function - -The callback *parameter* should specify a function that looks like this: - -function(integer result) {...}; - -result - -*( integer )* - -On success, the handle to the found USB device. On failure, -1. - -#### interruptTransfer - -chrome.experimental.usb.interruptTransfer(integer device, string direction, -integer endpoint, string data,function callback) - -Performs a USB interrupt transfer to the specified device. - -#### Parameters - -device - -*( integer )* - -A device handle on which the transfer is to be made. - -direction - -*( string )* - -The direction of the control transfer. "in" for an inbound transfer, "out" for -an outbound transfer. - -endpoint - -*( integer )* - -The endpoint to which this transfer is being made. - -data - -*( string )* - -(TODO(gdk): ArrayBuffer) The interrupt data payload for this transfer. - -callback - -*( optional function )* - -A callback to be invoked with the results of this transfer. - -#### Callback function - -If you specify the *callback* parameter, it should specify a function that looks -like this: - -function(object result) {...}; - -result - -*( object )* - -data - -*( optional string )* - -(TODO(gdk): ArrayBuffer) If the transfer results in inbound data, it is returned -here. - -result - -*( integer )* - -On success, 0 is returned. On failure, -1. - -Open questions -Note any unanswered questions that require further discussion.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/webnavigation-v2/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/webnavigation-v2/index.md deleted file mode 100644 index 87a60e678b7..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/webnavigation-v2/index.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: webnavigation-v2 -title: webNavigation v2 ---- - -**Proposal Date** - -*2012-06-14* - -Who is the primary contact for this API? -*jochen@* - -Who will be responsible for this API? (Team please, not an individual) - -*jochen@, mpcomplete@* - -Overview -*Now that the webNavigation API is released for a while, I learned about certain -short-comings I'd like to fix. This proposal captures the required additions / -changes to the current webNavigation API.* - -Use cases - -* Currently, if a page is pre-rendered, and you navigate to that page, - the navigation is aborted, and the page magically is there (without - further visible webNavigation events). The next version of the - webNavigation API should indicate when a prerendered page is swapped - in. -* *If a navigation crosses a process boundary, the tuple (tab ID, - frame ID) is no longer unique, but there might be two frames with - the same ID navigating for the same tab, but in two different - processes. Also, the frame ID of the main frame might change during - a provisional load. It seems that we can't hide these details of our - process model (without considerable effort). The next version should - allow for updating frame IDs during provisional loads, and have a - truly unique identifier for frames.* - -Do you know anyone else, internal or external, that is also interested in this -API? -*There were bug reports filed about this: <http://crbug.com/116643> -<http://crbug.com/117043>* - -Could this API be part of the web platform? -*No, it's just an extension of an existing API* - -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -When we add new fancy navigation features (e.g. similar to prerendering), the -API might need to be extended again. - -**If multiple extensions used this API at the same time, could they conflict with each others? If so, how do you propose to mitigate this problem?** -No* -List every UI surface belonging to or potentially affected by your API: -None -**Actions taken with extension APIs should be obviously attributable to an -extension. Will users be able to tell when this new API is being used? How?** - -*The API is only observing events, there should be no observable impact.* - -**How could this API be abused?** -**The API can be used to monitor each and every navigation, but that's already possible with v1.** -**Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):** -**1) observe each and every navigation, send it to some 3rd-party server** -**2) ...** -**3) profit** -What security UI or other mitigations do you propose to limit evilness made possible by this new API?** -*The webNavigation API already triggers a warning at install time.* -Alright Doctor, one last challenge:** -Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?** -No -How would you implement your desired features if this API didn't exist? -*You could guess that a page is being prerendered, or try to work around -duplicate frame IDs.* -Draft API spec -All existing events and methods that take or return a frame ID will in addition -take a process ID. A frame is then uniquely identified by the tripple (tab id, -process id, frame id). - -The onCommitted signal's documentation is updated to state that the frame ID and -process ID might have changed since the onBeforeNavigate signal. - -Furthermore, this new event is introduced. : - -**onReplacedTab** - -chrome.webNavigation.onReplacedTab.addListener(function (object details) { ... -}); - -Fired when a navigation is aborted, and instead a prerendered tab is swapped in. - -Listener parameters - -details (object) - -sourceTabId (integer) - -The ID of the tab being replaced - -tabId (integer) - -The ID of the tab replacing the sourceTabId - -timeStamp (number) - -The time when the browser was about to replace the tab in milliseconds since the -epoch. - -Open questions -The proposed changes are "breaking changes" as an extension using v1 of the API -will still experience the above referenced bugs. Is that ok?
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/webrtc-tab-content-capture/TabCaptureStates.png.sha1 b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/webrtc-tab-content-capture/TabCaptureStates.png.sha1 deleted file mode 100644 index c27f07d5449..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/webrtc-tab-content-capture/TabCaptureStates.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -d1a2221d9e09a5acdb6de83815ae0154c6b7de61
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/webrtc-tab-content-capture/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/webrtc-tab-content-capture/index.md deleted file mode 100644 index ca0ef8f2016..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/webrtc-tab-content-capture/index.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: webrtc-tab-content-capture -title: Tab Content Capture into MediaStreams ---- - -**\*\* This launched as of Chrome 31. Documentation: -https://developer.chrome.com/extensions/tabCapture \*\*** - -**Proposal Date** -**August 14th, 2012** - -**Who is the primary contact for this API?** -**mfoltz@chromium.org** - -**Who will be responsible for this API? (Team please, not an individual)** - -**[mfoltz@](mailto:mfoltz@google.com)chromium.org, [keiger@google.com](mailto:keiger@google.com), [markdavidscott@google.com](mailto:markdavidscott@google.com)** - -****Overview**** -****The proposed APIs enable tab output to be captured as a media stream, and transmitted using WebRTC. Supporting APIs are also defined to notify and query the capture status for tabs.**** -****Use cases**** -****This API enables a special form of screencasting, but in which users are able to share the contents of a tab rather than sharing their entire desktop. This avoids a number of issues with desktop sharing, such as the presence of icons, taskbars, window chrome, pop-ups, and other elements that it is often not desirable (or in some cases, even embarassing - e.g. when a new mail notification or IM shows up for all to see) to share.**** -****This API also enables the creation of WebRTC-based screencasting approaches, allowing the receiver of such content to run in a standard browser, entirely plug-in (and extension) free.**** -****Versus desktop screencasting, this API enables multitasking use cases, since switching active tabs doesn’t impact the content that’s being transmitted.**** -****Finally, this can later enable multi-screen applications that function by creating multiple tabs with one or more of those tabs being screencast for display on a different surface.**** - -****Do you know anyone else, internal or external, that is also interested in this API?**** -****We are aware of 3 projects at Google that have an interest in this functionality, and believe that it will be externally interesting to many others.**** - -****Could this API be part of the web platform?**** -****We believe that this functionality is useful both for extensions and the open web - but they are independently useful for each.**** -****The extension approach to these APIs, proposed here, allows for the capture of the contents of any tab, without any updates needed to the content displayed in the tab. Thus, any existing content or application can be accommodated.**** -****By contrast, a web platform approach (which we hope to pursue later after proving the approach here) is also useful, but needs significantly more restrictions around security and privacy (e.g. limiting access to elements that are owned by the site calling the API). This lends to a different set of use cases (e.g. the multiscreen cases).**** -****We believe that extension API work and experience will help in making a better proposal for the open web in the relatively near future.**** - -****Do you expect this API to be fairly stable? How might it be extended or changed in the future?**** -****Yes, we believe that this API will be fairly stable, since it is modelled after an existing API (getUserMedia) and has narrowly defined semantics.**** -****Extensions or changes to incorporate other capture scopes - e.g. -window-level or desktop-level - is possible but should not result in significant -changes to the API.**** - -****If multiple extensions used this API at the same time, could they conflict with each others? If so, how do you propose to mitigate this problem?**** -****Nothing inherently prevents multiple tabs from being captured independently, -but there may be implementation limits on how many tabs can be captured -simultaneously (and in our initial implementation, we believe that capturing 1 -tab is sufficient). To address this, the proposed API includes a notification to -indicate when tab capture status changes so we can notify an application if a -tab is no longer being captured due to a newer conflicting action.**** - -****List every UI surface belonging to or potentially affected by your API:**** -****The proposed APIs don’t expose any new UI surfaces to extensions. It is -proposed that we provide a visual indication to the user when a tab is being -captured, though the exact design for this is still under consideration. One -proposed approach is a color or animation on the tab itself or its favicon, -another is use of the existing mechanism used by WebRTC to indicate when camera -capture is active (this may be preferred for consistency).**** - -****Actions taken with extension APIs should be obviously attributable to an extension. Will users be able to tell when this new API is being used? How?**** -****Per the above, we plan to have a visual indicator of the tab(s) being -captured. Hovering over this indicator will indicate which extension is -performing the capture.**** - -****How could this API be abused?**** -****From a security/privacy perspective, since this API enables tab contents to be captured, it could be used to capture user browsing and to send that as a video stream to an external site. However, since we require the tabs permission, this is not substantively different from capturing the HTML/JS content of a tab (in fact, it’s less effective than the latter). It’s also no more sensitive than the tab snapshot API in terms of what it has access to.**** -****From a security perspective, creating a video stream that’s targetted at an arbitrary destination coud be used in DDOS-type attacks, though this is not significantly more effective than sending a large number of HTTP requests or transmitting a large binary file.**** -****From a performance perspective, too many simultaneous tabs being captured could impact performance. To mitigate this, we plan to limit the number of tabs that can be captured simultaneously (starting with a value of 1).**** -****Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):**** -****1) Per prior answer, scrape screen and send it to a malicious site.**** -****2) Per prior answer, create “fake” video stream and use it for DDOS attack.**** -****3) Per prior answer, create a bunch of bogus tab captures and send them somewhere meaningless, in an attempt to waste resources and trigger a crash.**** -****What security UI or other mitigations do you propose to limit evilness made possible by this new API?**** -****Per the above, we’re proposing a visual indicator for tabs that are being captured which identifies the extension performing the capture, and to ensure that the user is aware that capture is ongoing.**** -****Alright Doctor, one last challenge:**** -****Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?**** -****No; no permanent changes are possible as a result of the proposed API.**** -****How would you implement your desired features if this API didn't exist?**** -****Existing alternatives depending on building native applications or using dangerous NPAPI plug-ins with full system access.**** -****Draft Manifest Changes**** -****At this point in time, we believe that the tabs permission is sufficient. -We’re very open to input and advice on this, though!**** - -****Draft API spec**** - -****getTabMedia**** -****chrome.experimental.capture.getTabMedia(integer tabId,**** -****object options, function callback)**** -****Captures the visible area of the tab with the given tabId. Extensions must have the host permission for the given tab as well as the “tabs” permission to use this method.**** -****Parameters:**** -****tabId (optional integer): The tabId of the tab to capture. Defaults to the active tab.**** -****options (optional object): Configures the returned media stream.**** -****video (boolean): Whether to return video (default true)**** -****audio (boolean): Whether to return audio (default true)**** - -****callback (function): Called when the media stream is ready.**** - -****Callback function:**** -****function (stream)**** -****stream (optional LocalMediaStream): The LocalMediaStream that was created, or null if no stream was created. chrome.extension.lastError will be set if the stream could not be created (see below)**** -****Errors:**** - -* ****“Permission Denied” - The user did not grant permission for the - tab to be captured**** -* ****“Busy” - Capture resources are occupied by an existing capture - operation (i.e., we can’t capture two tabs at once)**** -* ****“Closed” - The tab was closed before the media stream could be - created.**** - -****See below for details on the LocalMediaStream structure.**** - -****onTabCaptured**** -****chrome.experimental.capture.onTabCaptured.addListener(**** -****function(object captureInfo) { ... })**** -****Event fired when the capture status of a tab changes. This allows extension authors to keep track of the capture status of tabs, to keep UI elements like page actions and infobars in sync.**** -****Parameters:**** -****captureInfo (object): Details of the change.**** -****tabId (integer): The id of the tab whose status changed.**** -****status (string): The new capture status of the tab, one of “requested”, “cancelled”, “pending”, “active”, “muted”, “stopped”**** -****Status state diagram is attached.**** - -****getCapturedTabs**** -****chrome.experimental.capture.getCapturedTabs(function callback)**** -****Returns a list of tabs that have requested capture or are being captured, i.e. status != stopped and status != cancelled. This allows extensions to inform the user that there is an existing tab capture that would prevent a new tab capture from succeeding (or, to prevent redundant requests for the same tab).**** -****Callback function:**** -****function(<array of CaptureInfo> result) { ... }**** -****CaptureInfo is as specified above.**** -****Open questions**** -****- Confirm permissions approach stated above**** -****- Can a WebKit object be returned through an extension API?**** -****- Control over aspect ratio, clipping, scaling of resulting media?****
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/window-management/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/window-management/index.md deleted file mode 100644 index 8f85bb917ee..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apis-under-development/window-management/index.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/apis-under-development - - API Proposals (New APIs Start Here) -page_name: window-management -title: Window Management ---- - -Proposal Date - -August 3rd, 2012 -Who is the primary contact for this API? -sadrul@google.com -Who will be responsible for this API? (Team please, not an individual) - -sadrul@, reveman@ - -Overview -Using this API, an extension will be able to (1) manage the positioning of the -window (including size, transform etc.), (2) perform window operations (e.g. -close, minimize etc.), (3) handle some input events for window management -purposes (e.g. install custom keyboard/mouse/gesture bindings etc.), and (4) -apply custom window decorations. This is primarily targeted for ChromeOS (to be -more specific, the primary target is the Ash desktop environment used in -ChromeOS. Ash is expected to be used on Windows too at some point, and the -expectation/hope is that this API will work there too). [Design -doc](https://docs.google.com/a/chromium.org/document/d/1szxvr95ymXNbJfpHfVmtcglr-F2bAgokxbZR_quVwY8/edit) - -Use cases - -* **Useful especially for developers**: A lot of the developers use a - window manager that allows managing the finer details of window - management using some scripting language. On ChromeOS, using an app - for doing the same would be very useful. (Specifically if/when ash - is used on linux platforms: see - <https://chromiumcodereview.appspot.com/10789018/>) -* Easier to make and test changes: With JS, it would be a lot easier - to implement and try out new window-management behaviour. - -Do you know anyone else, internal or external, that is also interested in this -API? -There is interest in the ChromeOS test team to use this (since pyauto tests will -be updated to use extension API). There is also interesting among developers and -UX leads to experiment with this API. - -Could this API be part of the web platform? -Unlikely. - -Do you expect this API to be fairly stable? How might it be extended or changed -in the future? -The API can potentially include a lot of features. However, the plan is to start -small, adding support for a limited set of functionality, and then add to the -API. However, it should be fairly easy to keep the API backwards-compatible when -new API is added. - -**If multiple extensions used this API at the same time, could they conflict with each others? If so, how do you propose to mitigate this problem?** -Multiple extensions can use the API at the same time. The reason for allowing -this is because a particular extension might be used for managing window -positioning, while at the same time, another extension might be used for -managing input-handling. However, if multiple active extensions use this API to -manage window positioning, then they can potentially conflict with each other -(although in the end, only one will 'win'). There is no plan to mitigate this -problem at this point. - -List every UI surface belonging to or potentially affected by your API: -Initially all toplevel windows (e.g. browser windows, panels, modal windows). -This can perhaps be extended to also support notification windows, desktop -windows etc. - -**Actions taken with extension APIs should be obviously attributable to an -extension. Will users be able to tell when this new API is being used? How?** - -When the extension is installed/enabled, the user will be required to grant the -extension "wm" permission, so the user will have the knowledge that the -extension manages windows. But there will be no more visual cues in the UI after -that. - -**Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):** -**1) The API allows closing windows. So an extension could potentially close a window/modal window immediately after it is opened. However, it will not be able to trigger the default action on the modal windows.** -**2) The extension could close/hide all notification windows before they are displayed. (if notification windows are exposed through the API. see above)** -**3) Add emacs-like key-bindings for window management (e.g. close window, move/resize window, focus window etc.)** -What security UI or other mitigations do you propose to limit evilness made possible by this new API?** -I do not think it is necessary to have a UI for mitigating the evilness. -However, it might make sense to add the extension icon to the active window's -title-bar.** - -**Alright Doctor, one last challenge:** -**Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?** -**The API does not provide access to the user's preferences, or other such data. -The only preference-data that can get modified by the API is the browser -window-position/size. Once the extension is disabled, the effects of the -extension should be completely reversible, possibly trivially.** - -**How would you implement your desired features if this API didn't exist?** -**There unfortunately is no alternative. If a user wants to have different -window-management behaviour, then the user needs to change source and recompile -chrome.** - -Draft API spec - -**<table>** -**<tr>** -**<td>API Function (chrome.experimental.wm.XXX)</td>** -**<td>Details (asynchronous unless explicitly stated otherwise)</td>** -**</tr>** -**<tr>** -**<td>close</td>** -**<td>Closes a window.</td>** -**</tr>** -**<tr>** -**<td>transform</td>** -**<td>Applies transforms (e.g. rotation, scaling, translation) to a window. These transforms can be applied with an animation, and the app can decide how long the animation lasts.</td>** -**</tr>** -**<tr>** -**<td>opacity</td>** -**<td>Changes the opacity of a window. The opacity can be applied with an animation, and the app can decide how long the animation lasts.</td>** -**</tr>** -**<tr>** -**<td>windows</td>** -**<td>Gets a list of all the windows. (synchronous)</td>** -**</tr>** -**<tr>** -**<td>setWindowBounds</td>** -**<td>Sets the size of a window. (can be animated) This may (or may not?) override the resizability of a window.</td>** -**</tr>** -**<tr>** -**<td>stackWindowAbove(window1, window2)</td>** -**<td>Changes the stack-ordering of windows.</td>** -**</tr>** -**<tr>** -**<td>screenBounds</td>** -**<td>Gets the bounds of the screen (synchronous). The details for dealing with multi-monitor configuration TBD (will likely mirror how ash/aura/views deals with this).</td>** -**</tr>** -**<tr>** -**<td>minimize</td>** -**<td>Minimizes a window.</td>** -**</tr>** -**<tr>** -**<td>maximize</td>** -**<td>Maximizes a window. This may (or may not?) override the resizability of a window.</td>** -**</tr>** -**<tr>** -**<td>fullscreen</td>** -**<td>Makes the window fullscreen. This may (or may not?) override the resizability of a window.</td>** -**</tr>** -**<tr>** -**<td>\[feel free to add more here\]</td>** -**</tr>** -**</table>** - -**<table>** -**<tr>** -**<td>Events</td>** -**<td>Details (synchronous unless explicitly stated otherwise)</td>** -**</tr>** -**<tr>** -**<td>onWindowCreated(AshWindow)</td>** -**<td>Triggered when a new window is created (but before the window is made visible.)</td>** -**</tr>** -**<tr>** -**<td>onWindowClosed(AshWindow)</td>** -**<td>Triggered when a window gets closed. This will be triggered whenever the window is closed (i.e. by the user, by the web-page, or by the WM app from the close API call)</td>** -**</tr>** -**<tr>** -**<td>onWindowShown(AshWindow)</td>** -**<td>Triggered when a window becomes visible.</td>** -**</tr>** -**<tr>** -**<td>onWindowHidden(AshWindow)</td>** -**<td>Triggered when a window is hidden.</td>** -**</tr>** -**<tr>** -**<td>onWindowActivated(AshWindow)</td>** -**<td>Triggered when an inactive window becomes active (e.g. user clicked on the window to make it active, or the previously active window was closed, or by other means).</td>** -**</tr>** -**<tr>** -**<td>onWindowInputEvent(AshWindow, Event, EventModifiers)</td>** -**<td>Triggered when an ‘interesting’ input event happens on the window (e.g. user presses Alt+Ctrl+Key, or does a four-finger swipe gesture, or clicks with Alt down etc.)</td>** -**</tr>** -**<tr>** -**<td>onWindowMoved(AshWindow, OldPosition)</td>** -**<td>Triggered when a window is moved. This will be triggered whenever the window is moved (i.e. by the user, by the web-page, or by the WM app from the setWindowBounds API call)</td>** -**</tr>** -**<tr>** -**<td>onWindowResized(AshWindow, OldSize)</td>** -**<td>\[similar to above\]</td>** -**</tr>** -**<tr>** -**<td>\[feel free to add more here\]</td>** -**</tr>** -**</table>** - -**Some more details: a Window object is represented in the app as a dictionary with the following fields:** - -* **id: A unique id for the window for the duration of the session.** -* **type: Window type (one of \[“modal”, “panel”, “normal”\]).** -* **state: Window state (one of \[“normal”, “minimized”, “maximized”, - “fullscreen”\])** -* **title: The title of the window (this is typically user-visible; - could be empty).** -* **name: The name of the window (this is typically not visible to - user; could be empty).** -* **bounds: The location/size of the window.** -* **active: Whether the window is currently active or not.** -* **visible: Whether the window is currently visible or not.** - -**All the callbacks (event callbacks, and callback to windows function call) -receive these details about the window(s).** - -Open questions
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apiwishlist/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apiwishlist/index.md deleted file mode 100644 index 45eef6de7c9..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/apiwishlist/index.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -page_name: apiwishlist -title: API Wish List ---- - -An early design document containing an unsorted list of things we've want to do -as extension APIs. Some of these ideas have now been implemented. - -<table> - <tr> - <th>Name</th> - <th>Notes</th> - <th>Use cases</th> - <th>Priority</th> - </tr> - <tr> - <td>Launch external programs</td> - <td>Just a simple command line, for more interaction with native code use NPAPI</td> - <td>Download accelerators</td> - <td></td> - </tr> - <tr> - <td>History</td> - <td>APIs to the built-in history and bookmark system. For example, to be notified when the star button is pressed, or to push items into either database.</td> - <td>Synchronization</td> - <td></td> - </tr> - <tr> - <td>Internationalization</td> - <td>This is particularly necessary in cases where UI is declarative. For example, if we have declarative content gleam or tool buttons. It is also useful for internationalizing HTML without having to use JS at runtime.</td> - <td></td> - <td></td> - </tr> - <tr> - <td>Read-write user scripts</td> - <td>Inject javascript into pages.</td> - <td>Like Greasemonkey</td> - <td></td> - </tr> - <tr> - <td>Thumbnail</td> - <td>Generate thumbnails from open tabs. Access read and write to the thumbnail database.</td> - <td>CtrlTab Preview</td> - <td></td> - </tr> - <tr> - <td>Sidebars</td> - <td></td> - <td>Delicious</td> - <td></td> - </tr> - <tr> - <td>Content layers</td> - <td>A separate DOM for use by extensions that renders on top of a content DOM. Extensions (user scripts) can access both, but the top layer's CSS is isolated from the bottom layer.</td> - <td>Drawing selection UI, like FlashGot</td> - <td></td> - </tr> - <tr> - <td>Keyboard and mouse handlers</td> - <td>Extensions should be able to listen to events over the entire browser UI.</td> - <td>CtrlTab Preview, Gestures</td> - <td></td> - </tr> - <tr> - <td>Async DOM</td> - <td>An idea to allow manipulation of the DOM asynchronously from the browser process.</td> - <td>This would allow Greasemonkey-type use cases without having to require authors split apart their code into separate processes. It should also be more efficient.</td> - <td></td> - </tr> - <tr> - <td>Settings</td> - <td>Interact with various Chromium settings, like what pages JavaScript is enabled for, what pages cookies are sent to, user agent settings, proxy settings, etc</td> - <td>NoScript, privacy filters, proxy switchers</td> - <td></td> - </tr> - <tr> - <td>Network</td> - <td>Listen for requests, watch data go by, etc.</td> - <td>Cloud-based history</td> - <td></td> - </tr> - <tr> - <td>Omnibox</td> - <td>Take part in omnibox sessions.</td> - <td>Make cloud-based bookmark and history first-class in Chromium UI</td> - <td></td> - </tr> - <tr> - <td>Read-only user scripts</td> - <td>Read-only javascript access to the DOM.</td> - <td></td> - <td></td> - </tr> - <tr> - <td>Pop-out areas</td> - <td>Ability to render web content outside the viewport</td> - <td>Pull out areas from toolbars, shelves</td> - <td></td> - </tr> - <tr> - <td>Shelves and bottom bars</td> - <td>They may be able to be the same thing. Shelves have a different default presentation than bottom bars (constrained height, like a toolbar, different background and edges).</td> - <td>Download status, Firebug</td> - <td></td> - </tr> - <tr> - <td>Element-specific actions</td> - <td>Tell Chromium to somehow highlight a DOM element and advertise that an action is possible.</td> - <td>Send this image to a friend on Facebook</td> - <td></td> - </tr> - <tr> - <td>Menus</td> - <td>add items to in-page context menus and system menus</td> - <td>bookmarking and recommendation systems, many more</td> - <td></td> - </tr> - <tr> - <td>Downloads</td> - <td>APIs to manipulate the download system.</td> - <td>DownThemAll</td> - <td></td> - </tr> - <tr> - <td>New Tab Page</td> - <td>Replace it entirely, or add modules (iframes?) to it.</td> - <td></td> - <td></td> - </tr> - <tr> - <td>Themes</td> - <td>Customizing the look and feel of the interface. We might surface them to users as different than extensions, but they will use a lot of the underlying infrastructure.</td> - <td>It turns out people like to decorate.</td> - <td></td> - </tr> - <tr> - <td>Storage</td> - <td>Should come for free via HTML5 APIs.</td> - <td></td> - <td></td> - </tr> - <tr> - <td>Navigation Interception</td> - <td>APIs for an extension to intercept a navigation event and modify it.</td> - <td>Automated file format converters, auto-incognito mode on certain website URLs</td> - <td></td> - </tr> -</table> diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/creating-new-apis/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/creating-new-apis/index.md deleted file mode 100644 index d9f53b9064f..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/creating-new-apis/index.md +++ /dev/null @@ -1,407 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -page_name: creating-new-apis -title: Implementing a new extension API ---- - -**Proposal** - -See [API Proposals (New APIs Start -Here)](/developers/design-documents/extensions/proposed-changes/apis-under-development). - -So you want to add the Widgets API. Let's call it **widgets**. - -**Defining the Interface** - -#### How will extensions declare their intent to use widgets? - -### You need to decide this now. In other words, what will a user of widgets need to write in their manifest? - -Typically this will be either via a **permission string** or **manifest entry**. -There is no need for both. By convention it should be called "widgets". - -* Use a **manifest entry** for declarative style APIs, or when you - need to express some sort of rich structure. For example, - [commands](http://developer.chrome.com/extensions/commands.html). - -> > { - -> > "name": "Demo widget extension", - -> > "widgets": { - -> > "foo": "bar", - -> > "baz": "qux" - -> > } - -> > ... - -> > } - -* Use a **permission string** for procedural APIs, typically those - which are just a collection of functions. Most APIs are of this - form. For example, - [storage](http://developer.chrome.com/extensions/storage.html). - -> > { - -> > "name": "Demo widget extension", - -> > "permissions": \[..., "widgets", ...\] - -> > ... - -> > } - -There are exceptions: - -* Some APIs are integral parts of the platform (e.g. - [runtime](http://developer.chrome.com/apps/runtime.html), - [app.window](http://developer.chrome.com/apps/app.window.html), etc) - and require no declaration. -* Some older APIs use object permissions rather than strings, such as - [fileSystem](http://developer.chrome.com/apps/fileSystem.html). This - is deprecated. Use a manifest entry instead. - -#### Tell the extensions platform about widgets - -Firstly decide, *can your API be applied to any platform built on the web, or -does it only make sense for Chrome?* Examples of the former: storage, messaging. -Examples of the latter: browserAction, bookmarks. A good clue is whether you -need to #include anything from chrome. - -* If it applies to any platform, widgets should be implemented in the - extensions module (src/extensions). -* If it's Chrome only, widgets should be implemented in Chrome - (src/chrome/common/extensions and src/chrome/browser/extensions, - etc). -* If in doubt, try to implement it in src/extensions. - -From here, all files here are relative to either extensions/common/api or -chrome/common/extensions/api: - -First, add an entry in _api_features.json. This tells the extensions platform -about when your API should be available (anywhere? only in extension -processes?), and what they need to do to use it (do they need a permission? a -manifest entry?). - -* If you're using a **manifest entry**, use "manifest:widgets" as the - dependency. -* If you're using a **permission string**, use "permission:widgets" as - the dependency. - -Second, add an entry to either _manifest_feature.json or -_permission_features.json. This tells the platform how to interpret "widgets" -when it encounters it as either a manifest entry or a permission. What is it -available to (extensions? apps? both?), and importantly what channel is it -available in (dev? beta? stable?). **New extension APIs MUST start in dev** -(although if they're unimplemented then trunk is advisable). - -*==New extension APIs MUST start in dev==* (just repeating it). - -**Write a schema for widgets** - -Extension APIs can be defined in either IDL (widgets.idl) or JSON Schema -(widgets.json). IDL is much more concise, but doesn't include some of the -advanced features supported by JSON Schema. - -You probably want IDL, though be warned *IDL syntax errors occasionally cause -the compiler to never terminate*. - -Fourth, list the schema in -[//extensions/common/api/schemas.gni](https://source.chromium.org/chromium/chromium/src/+/HEAD:extensions/common/api/schema.gni), -which tells the build system to generate a bunch of boilerplate for you in -<build_dir>/gen/extensions/common/api or -<build_dir>/gen/chrome/common/extensions/api: models for your API, and the -glue to hook into your implementation. - -Finally, add some documentation: - -## **Adding documentation** - -Adding documentation is very simple: - -1. Write a summary for your API and put it in - chrome/common/extensions/docs/templates/intros/myapi.html. -2. Create the publicly accessible template(s) in - chrome/common/extensions/docs/templates/public/{extension,apps}/myapi.html. - Whichever of extensions and/or apps you add an HTML file in depends - on which platform can access your API. - * Each will look something like: - {{ '{{' }}+partials.standard_extensions_api api:apis.extensions.myapi - intro:intros.myapi /{{ '}}' }} (or apps). - -**C++ implementation** - -The actual C++ implementation will typically live in -extensions/browser/api/myapi or chrome/browser/extensions/api/myapi (as -mentioned above, the magic glue is generated for you). - -**Functions** - -Extension APIs are implemented as subclasses of ExtensionFunction from -extensions/browser/extension_function.h. - -* Use DECLARE_EXTENSION_FUNCTION to declare the JavaScript identifier - for the function. -* Implement ExtensionFunction::Run. The comments on that method - explain how to implement it. -* Note: use EXTENSION_FUNCTION_VALIDATE to validate input arguments, - which are placed in args_. Failing this check kills the renderer, so - the idiom for this is catching bugs in the renderer (for example: - schema validation errors). -* Add your implementation files to - [chrome/common/extensions/api/api_sources.gni](https://source.chromium.org/chromium/chromium/src/+/HEAD:chrome/common/extensions/api/api_sources.gni). - -**Model generation** - -Your C++ implementation **must live** in -extensions/browser/api/myapi/myapi_api.h/cc or -chrome/browser/extensions/api/myapi/myapi_api.h/cc (depending on where it was -declared).This is so that the code generator can find the header file defining -your extension function implementations. Remember to add your source files to -[//chrome/common/extensions/api/api_sources.gni](https://source.chromium.org/chromium/chromium/src/+/HEAD:chrome/common/extensions/api/api_sources.gni). - -In your header file, include extensions/common/api/myapi.h or -chrome/common/extensions/api/myapi.h to use the generated model. This comes from -a code-generated file that lives under e.g. -out/Debug/gen/chrome/common/extensions/api. Let's say we have the following IDL -(or equivalent JSON schema): - -// High-level description of your API. This will appear in various places in the -docs. - -**namespace** myapi { - -**dictionary** BazOptions { -// Describes what the id argument means. -**long** id; -// Describes what the s argument means. -**DOMString** s; -}; -**dictionary** BazResult { -**long** x; - -**long** y; -}; -**callback** BazCallback = **void** (BazResult result); -**interface** Functions { - -// An interesting comment describing what the baz operation is. - -// Note that this function can take multiple input arguments, including things -like - -// long and DOMString, but they have been elided for simplicity. -**static void** doBaz(BazOptions options, BazCallback callback); -}; -}; - -A simple C++ implementation might look like this: - -namespace extensions { - -// You must follow a naming convention which is ApiNameFunctionNameFunction, - -// in this case MyapiDoBazFunction. This is so that the generated code - -// can find your implementation. - -**class** MyapiDoBazFunction : **public** AsyncExtensionFunction { - -**public**: - -virtual ~MyapiDoBazFunction () {} - -**private**: - -// The MYAPI_DOBAZ entry is an enum you add right before ENUM_BOUNDARY - -// in chrome/browser/extensions/extension_function_histogram_value.h - -DECLARE_EXTENSION_FUNCTION("myapi.doBaz", MYAPI_DOBAZ); - -**virtual** ResponseAction Run() OVERRIDE { - -// Args are passed in via the args_ member as a base::ListValue. - -// Use the convenience member of the glue class to easily parse it. - -std::unique_ptr<api::myapi::DoBaz::Params> params( - -api::myapi::DoBaz::Params::Create(\*args_)); - -EXTENSION_FUNCTION_VALIDATE(params.get()); - -api::myapi::BazResult result; - -result.x = params->options.id; - -base::StringToInt(params->options.s, &result.y); - -// Responds to the caller right, but see comments on - -// ExtensionFunction::Run() for other ways to respond to messages. - -**return** RespondNow(ArgumentList(result.ToValue())); - -} - -}; - -} // namespace extensions - -ExtensionFunction is refcounted and instantiated once per call to that extension -function, so use base::Bind(this) to ensure it's kept alive (or use -AddRef...Release if that's not possible for some reason). - -**Events** - -Use ExtensionEventRouter (on the UI thread) to dispatch events to extensions. -Prefer the versions that allow you to pass in base::Value rather than a JSON -serialized format. Event names are auto-generated in the API file (e.g. -chrome/common/extensions/api/myapi.h). In the un-common case where an event is -not defined in IDL or json, the corresponding event name should be defined in -chrome/browser/extensions/event_names.h. - -As with extension functions, it generates some C++ glue classes. Let's say we -have the following IDL (or equivalent JSON Schema): - -**namespace** myapi { - -**dictionary** Foo { - -// This comment should describe what the id parameter is for. - -**long** id; - -// This comment should describe what the bar parameter is for. - -**DOMString** bar; - -}; - -**interface** Events { - -// Fired when something interesting has happened. - -// |foo|: The details of the interesting event. - -**static void** onInterestingEvent(Foo foo); - -}; - -}; - -To use the generated glue in C++: - -DCHECK(BrowserThread::CurrentlyOn(BrowserThread::UI)); - -api::myapi::Foo foo; - -foo.id = 5; - -foo.bar = "hello world"; - -ExtensionSystem::Get(profile)->event_router()->DispatchEventToExtension( -extension_id, - -**api::myapi::OnInterestingEvent::kEventName**, - -**\*api::myapi::OnInterestingEvent::Create(foo)**, -profile, -GURL()); - -**Permissions** - -By default, extension APIs should require a permission named the same as the API -namespace. - -New permissions are added in ExtensionAPIPermissions::GetAllPermissions() in -extensions/common/permissions/extensions_api_permissions.cc or in -ChromeAPIPermissions::GetAllPermissions() in -chrome/common/extensions/permissions/chrome_api_permissions.cc. You may also -need to modify api_permission.h and chrome_permission_message_rules.cc in those -directories; see how it's done for other permissions. - -**Advanced Extension Functionality** - -**Custom Bindings** - -Custom JS bindings go in chrome/renderer/resources/extensions/\*.js. - -These are necessary for doing anything special: synchronous API functions, -functions bound to types, anything renderer-side. (If it's a common enough -operation, please send us patches to do it automatically as part of the bindings -generation :). - -**New Manifest Sections** - -If your API requires a new manifest section: - -1. Add a schema for the manifest entry to - chrome/common/extensions/api/manifest_types.json (e.g. Widgets). - * This is the JSON Schema format. See "Write a schema for - widgets". -2. Add the name of the manifest entry to - chrome/common/extensions/api/_manifest_features.json and declare - when it's available. - * See "Tell the extensions platform about widgets". -3. Add a ManifestHandler implementation in - chrome/common/extensions/manifest_handlers (e.g. - chrome/common/extensions/widgets_handler.cc/h). - * Your implementation can use the model that has been generated - from the schema in manifest_types.json - * And of course, test it. -4. If your manifest section requires permission messages and/or custom - permissions, add a ManifestPermission implementation. See - "sockets_manifest_handler" for an example. - -The code which handles the externally_connectable manifest key is a good place -to start. - -**Testing Your Implementation** - -Make sure it has tests. Like all of Chrome, we prefer unit tests to integration -tests. - -* There is a relatively new mini framework for unit tests in - chrome/browser/extensions/extension_function_test_utils.h. Hopefully - it meets your needs. -* If not, there is the older [API - tests](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/test/data/extensions/api_test/README.txt?view=markup) - for integration tests. - -**Iterating** - -1. Create an example extension that uses your API and add it to - chrome/common/extensions/docs/examples -2. Ask someone else (preferably someone in chrome-devrel@ or - chrome-extensions-team@) to make a second example extension -3. Iterate based on how those examples went -4. Make sure that your API is functional on all of Chrome's platforms - that have access to the web store and that all tests are enabled on - all platforms -5. Announce the dev channel API to the community by sending mail to - chromium-extensions@chromium.org and a blog post if appropriate -6. Encourage community feedback (ask chrome-extensions-team@ for ideas - here) -7. Iterate on the API based on community feedback -8. In general, an API should be on dev channel for at least one full - release cycle before moving on to the next phase - -### Going to Stable - -Follow the [Going Live -Phase](/developers/design-documents/extensions/proposed-changes/apis-under-development) -instructions. diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/extension-system-changes/breaking-changes/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/extension-system-changes/breaking-changes/index.md deleted file mode 100644 index 08326215230..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/extension-system-changes/breaking-changes/index.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/extension-system-changes - - Extension System -page_name: breaking-changes -title: Breaking Changes ---- - -Our general philosophy for the Chrome extensions system is to try hard to avoid -breaking (ie backwards-incompatible) changes. Over time we've discussed a number -of ideas for improvements based on actual experience with the extensions system -that would require breaking backwards compatibility. Ideally we'd do them all -together in one big batch to minimize developer pain. - -In no particular order, here's a list of these ideas. Some require changes to -the manifest format, and some change the behavior of existing APIs. - -* We want to reduce the need for background pages to help save memory, - and some ideas for how to do this require breaking changes. See [a - list of related - bugs](http://code.google.com/p/chromium/issues/list?q=TaskForce%3DBackgroundPagesMustDie). -* Split out host permissions and API permissions into separate fields - ([crbug.com/62898](http://crbug.com/62898)) - * We might want to design for extensibility in these fields, for - example to allow things like adding an optional - "why"/"justification" field for each permission. - * Also, for some API's such as spell checking, you want to grant - permissions at the host level to get events on input into text - boxes but don't necessarily want the ability to do cross-origin - XHR or chrome.tabs.executeScript. - * (aa says:) In that case, the permission should be different. - A host permission means authenticated access to the host. We - shouldn't twist the meaning per-API. -* Improve security in content scripts by either forcing the following - behaviors, or making them the default with explicit developer - opt-out: - * forbid eval - * turn on javascript strict mode - (<https://developer.mozilla.org/en/JavaScript/Strict_mode>) - * turn on CSP - (<http://www.w3.org/Security/wiki/Content_Security_Policy>) - * If a content script injects a <script> tag into the DOM, - only allow it if the src is an https url -* Split permissions into read and write (Context: captureVisibleTab - really requires <all_urls> because iframes can have content - from any site, but we don't want to require screenshot extensions to - get write-all permissions when they don't need/want it. There may be - other cases like this.) -* Move tabs.captureVisibleTab into its own top-level permission to - simplify concerns with iframe permissions -* Rationalize naming conventions. Excepting special circumstances, we - probably want to stick to the [Google javascript style - guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml): - * functionNamesLikeThis, variableNamesLikeThis, - ClassNamesLikeThis, EnumNamesLikeThis, methodNamesLikeThis, and - SYMBOLIC_CONSTANTS_LIKE_THIS - * Unify our handling for abbreviations like URL - we have - functions named getURL, setUpdateUrlData, addUrl, etc. We should - standardize on URL or Url. -* Have a "tabs_simple" or "tabs_light" permission for things like - chrome.tabs.{create,update,remove,onRemoved} -* Allow extensions to have opt-in "public" pages that can be loaded in - iframes, window.open, etc. from within other origins, and make pages - private by default. -* Fix the port madness in URLPattern. Can we make all URLPatterns - support ports? I believe right now, most cases of URLPatterns make - ports an error, which means we can make it work without a breaking - change. But in a few cases, ports are silently allowed for backward - compatibility. Fixing this would be the breaking change. -* Change chrome://favicon/ to a new scheme chrome-favicon:// (this was - the root of a security bug, <http://crbug.com/83010>) - * We should just make this a separate top-level API permission. We - don't need or want authenticated access to these origins - we - just want the icons. - * Some work on this is in-progress: crbug.com/172375 -* Allow better URL pattern matching (to differentiate between path, - query and fragments): <http://crbug.com/84024> -* Change the manifest format in any ways needed to let us use [JSON - Schema](http://json-schema.org/) for parsing it. - * Note: we already have an internal C++ implementation of JSON - Schema that is used for other things in the extension system -* Scan extension.cc for DEPRECATED and the like. Remove old stuff like - the support for multiple pageActions.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/extension-system-changes/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/extension-system-changes/index.md deleted file mode 100644 index 32402fa4164..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/extension-system-changes/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -page_name: extension-system-changes -title: Extension System ---- - -{% subpages collections.all %} diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/extension-system-changes/install-dialog-2/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/extension-system-changes/install-dialog-2/index.md deleted file mode 100644 index fcc8c1064c9..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/extension-system-changes/install-dialog-2/index.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -- - /developers/design-documents/extensions/proposed-changes/extension-system-changes - - Extension System -page_name: install-dialog-2 -title: Install Dialog v2 ---- - -### **Problem** - -The current extension install dialog displays a different string of text -depending on the permissions the extension requests. This has a few problems: - -1. It isn't extensible. We keep adding new permissions, but it's hard - to update the text strings to deal with all possible combinations of - permissions. -2. It isn't clear. Users don't realize that the text is telling them - something specific about the extension they're installing. -3. Advanced users have complained that they would like to see the - details of the exact permissions being requested, not the text form. -4. Very advanced users have requested the ability to disable individual - permissions during installation. - -### **Proposal** - -The current set of permissions are: - -* Data on a domain (eg www.google.com) -* tabs system details (urls, titles, etc) -* browsing history -* geolocation -* unlimited storage quota -* desktop notifications - -Some of these permissions are too granular to be useful to most users during -installation, and should be hidden by default. For example, most users won't -want to approve access to desktop notifications during installation. -Installation should grant that privilege automatically. Similar for extra -storage quota. Access to the tab system and to the history system are basically -the same kind of access, so those should be grouped. - -Thus the user-visible permissions for the above would be simplified to: - -* Data on a domain -* Browsing history (tabs, history, etc) -* Geolocation - -The new install dialog should show a list of high-level permissions by default, -but give advanced users a way to see the detailed list if they want. - -So something like: - -+=============================================+ - -| +------+ | - -| | | | - -| | icon | Install Gmail Checker? | - -| | | | - -| +------+ | - -+---------------------------------------------+ - -| This extension will have access to: | - -| | - -| ! Your private data on mail.google.com, | - -| www.google.com, and 3 other web sites. | - -| | - -| ! Your physical location on planet Earth. | - -| | - -| ! Your browsing history. | - -| | - -| \[more details\] | - -| | - -| | - -| \[ ok \] \[cancel\] | - -+=============================================+ - -When the user clicks "more details", the dialog expands and shows all the -permissions requested in as much detail possible. In the future, we might also -make it possible to turn off individual permissions in that area, but the -extension system doesn't support that yet. - -### Text details for high-level permissions - -**Site access** - -Your private data on www.google.com. - -Your private data on www.google.com and foo.com. - -Your private data on www.google.com, foo.com, and 5 other sites. - -Your private data on all web sites. - -**Tabs and History** - -Your browsing history. - -**Geolocation** - -Your physical location on planet Earth. - -**NPAPI** - -Full access to your computer and private data. - -**Camera (future)** - -Your computer's camera - -**Microphone (future)** - -Your computer's microphone - -**Infinite Storage, Notifications** - -<none>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/index.md deleted file mode 100644 index 7bd2a589911..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -page_name: proposed-changes -title: Proposed & Proposing New Changes ---- - -{% subpages collections.all %} diff --git a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/spellcheck-api/index.md b/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/spellcheck-api/index.md deleted file mode 100644 index 4b65f533069..00000000000 --- a/chromium/docs/website/site/developers/design-documents/extensions/proposed-changes/spellcheck-api/index.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -breadcrumbs: -- - /developers - - For Developers -- - /developers/design-documents - - Design Documents -- - /developers/design-documents/extensions - - Extensions -- - /developers/design-documents/extensions/proposed-changes - - Proposed & Proposing New Changes -page_name: spellcheck-api -title: Spellcheck API ---- - -**Proposal Date** -**December 27, 2012** -**Who is the primary contact for this API?** -**rlp@** -**Who will be responsible for this API? (Team please, not an individual)** -**Spelling team** -**Overview** -**The proposed API would allow the user to load a new dictionary.** -**Use cases** -**Currently there are many languages which neither Chrome spellchecking nor our third party library Hunspell support (e.g., Zulu, Klingon, etc.). We routinely see bug reports requesting languages not yet supported (approximately 20-30% of Spellcheck bugs). There are avid users who have put together or would put together dictionaries if they knew they could use them. This API would provide an interface to allow them to write extensions to load the dictionary of their choice making it available for spellchecking.** -**Do you know anyone else, internal or external, that is also interested in this API?** -**We have several bugs that are for languages which we do not support and cannot find libraries. If we provided this API, those users could maintain their own dictionaries.** -**Could this API be part of the web platform?** -**It is unlikely that spellchecking will become part of the web platform.** -**Do you expect this API to be fairly stable? How might it be extended or changed in the future?** -**Yes. We will allow users to specify which format their dictionary is in. If at some point we change the format which we read dictionaries in, we will be able to update the API to keep the current format and simply convert to the new format.** -**If multiple extensions used this API at the same time, could they conflict with each others? If so, how do you propose to mitigate this problem?** -**With this API we'd be adding the ability to have multiple dictionaries. If multiple extensions provided dictionaries, the only problem might be on loading if the user had an excessive number of dictionary-loading extensions as the loading was queued up.** -**List every UI surface belonging to or potentially affected by your API:** -**Settings->Language Settings: We would need to show the new dictionary as a language being used for spellcheck.** -**When spellchecking, red underlines and other spelling features would now be dependent on the dictionary available through this API.** -**Actions taken with extension APIs should be obviously attributable to an extension. Will users be able to tell when this new API is being used? How?** -**In the Settings->Language Settings dialog, we would show an icon or tag to indicate that a given dictionary came from an extension rather than a built in library.** -**How could this API be abused?** -**Dictionaries are just text files which are loaded in to Chrome. Possible abuse -could be adding words which one would normally expect to be spellchecked such -that they are not any more or adding "bad" words such as cursing or swear words. -Someone could also attempt to add a dictionary which is really code to be -executed upon loading.** - -**Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):** -**1) Buffer overflow with a loaded dictionary.** -**2) Killing a normal spellcheck by creating a dictionary of common misspellings.** -**3) Creating a dictionary with code that executes upon loading.** -**What security UI or other mitigations do you propose to limit evilness made possible by this new API?** -**We would not allow binary dictionaries and we would sanitize all dictionaries before loading them, ensuring that they only consisted of words in the format we expect. This would eliminate 1 and 3. 2 is difficult to eliminate because if the user wants to add common misspellings as "correct" words, that's their choice and we would not want to prevent them from doing so.** -**Alright Doctor, one last challenge:** -**Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?** -**No. Once an extension using this API was removed, the dictionary it loads would no longer be loaded and the user would not see the dictionary in their Settings. Thus there would be no trace of this extension.** -**How would you implement your desired features if this API didn't exist?** -**We could provide a command line option for users to load a dictionary from a file on their system. The unfortunate aspect of this method is that users then have to find the file on the web and figure out how to pass it in from the command line which means only power users are likely to do so.** -**Draft Manifest Changes** -**Unknown -- see additional questions at bottom.** -**Draft API spec** -**Methods** -**loadDictionary** -**chrome.spellcheck.loadDictionary** - -**Loads a dictionary based on the format specified by the user. This dictionary is automatically set to be used for spellchecking, but the user can stop using it for spellchecking via the Settings->Language Settings dialog at any time.** - -**Parameters** -**dictionaryFile (string)** -**The path for the dictionary file. This may be either a url or a local file path.** -**dictionaryFormat(enumerated string \["hunspell", "text"\])** -**The user must indicate which format their dictionary is in: hunspell dictionary (concatentation of .aff and .dic files) or plain text.** -**result (int)** -**The result is a int indicating success or an error code in loading the dictionary.** -**Example:** -**function loadMyDictionary(myDictionaryFile) {** -**var result = chrome.experimental.spellcheck.loadDictionary(myDictionaryFile);** -**if (!result) {** -**// Indicate to user that dictionary load failed through dialog/infobar/etc.** -**}** -**}** -**Open questions** -**Is a dictionaryLoaded event necessary?** -**Do we need an optional permission to load the dictionary?**
\ No newline at end of file |
