Move the `privacy` extension API out of experimental.

BUG=88030
TEST=browser_test (ExtensionAPITest.Preference*)

Review URL: https://chromiumcodereview.appspot.com/9244005

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@119031 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 213 insertions, 0 deletions

diff --git a/chrome/common/extensions/docs/static/privacy.html b/chrome/common/extensions/docs/static/privacy.html
new file mode 100644
index 0000000..bb8f852
--- /dev/null
+++ b/chrome/common/extensions/docs/static/privacy.html
@@ -0,0 +1,213 @@
+<div id="pageData-name" class="pageData">Privacy</div>
+
+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+  Use the <code>chrome.privacy</code> module to control usage of the features in
+  Chrome that can affect a user's privacy. This module relies on the
+  <a href="types.html#ChromeSetting">ChromeSetting prototype of the type API</a>
+  for getting and setting Chrome's configuration.
+</p>
+
+<p class="note">
+  The <a href="http://www.google.com/intl/en/landing/chrome/google-chrome-privacy-whitepaper.pdf">Chrome Privacy Whitepaper</a>
+  gives background detail regarding the features which this API can control.
+</p>
+
+<h2 id="manifest">Manifest</h2>
+<p>
+  You must declare the "privacy" permission in your extension's
+  <a href="manifest.html">manifest</a> to use the API. For example:
+</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "privacy"
+  ]</b>,
+  ...
+}</pre>
+
+<h2 id="usage">Usage</h2>
+
+<p>
+  Reading the current value of a Chrome setting is straightforward. You'll first
+  need to find the property you're interested in, then you'll call
+  <code>get()</code> on that object in order to retrieve it's current value and
+  your extension's level of control. For example, to determine if Chrome's
+  Autofill feature is enabled, you'd write:
+</p>
+
+<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
+  if (details.value)
+    console.log('Autofill is on!');
+  else
+    console.log('Autofill is off!');
+});</pre>
+
+<p>
+  Changing the value of a setting is a little bit more complex, simply because
+  you first must verify that your extension can control the setting. The user
+  won't see any change to her settings if you extension toggles a setting that
+  is either locked to a specific value by enterprise policies
+  (<code>levelOfControl</code> will be set to "not_controllable"), or if another
+  extension is controlling the value (<code>levelOfControl</code> will be set to
+  "controlled_by_other_extensions"). The <code>set()</code> call will succeed,
+  but the setting will be immediately overridden. As this might be confusing, it
+  is advisable to warn the user when the settings they've chosen aren't
+  practically applied.
+</p>
+
+<p class="note">
+  Full details about extensions' ability to control <code>ChromeSetting</code>s
+  can be found under
+  <a href="types.html#ChromeSetting">
+    <code>chrome.types.ChromeSetting</code></a>.
+</p>
+
+<p>
+  This means that you ought to use the <code>get()</code> method to determine
+  your level of access, and then only call <code>set()</code> if your extension
+  can grab control over the setting (in fact if your extension can't control the
+  setting it's probably a good idea to visibly disable the functionality to
+  reduce user confusion):
+</p>
+
+<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
+  if (details.levelOfControl === 'controllable_by_this_extension') {
+    chrome.privacy.services.autofillEnabled.set({ value: true }, function() {
+      if (chrome.extension.lastError === undefined)
+        console.log("Hooray, it worked!");
+      else
+        console.log("Sadness!", chrome.extension.lastError);
+    }
+  }
+});</pre>
+
+<p>
+  If you're interested in changes to a setting's value, add a listener to its
+  <code>onChange</code> event. Among other uses, this will allow you to warn the
+  user if a more recently installed extension grabs control of a setting, or if
+  enterprise policy overrides your control. To listen for changes to Autofill's
+  status, for example, the following code would suffice:
+</p>
+
+<pre>chrome.privacy.services.autofillEnabled.onChange.addListener(
+    function (details) {
+      // The new value is stored in `details.value`, the new level of control
+      // in `details.levelOfControl`, and `details.incognitoSpecific` will be
+      // `true` if the value is specific to Incognito mode.
+    });</pre>
+
+<h2 id="examples">Examples</h2>
+<p>
+  For example code, see the
+  <a href="samples.html#privacy">Privacy API samples</a>.
+</p>
+<!-- END AUTHORED CONTENT --><div id="pageData-name" class="pageData">Privacy</div>
+
+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+  Use the <code>chrome.privacy</code> module to control usage of the features in
+  Chrome that can affect a user's privacy. This module relies on the
+  <a href="types.html#ChromeSetting">ChromeSetting prototype of the type API</a>
+  for getting and setting Chrome's configuration.
+</p>
+
+<p class="note">
+  The <a href="http://www.google.com/intl/en/landing/chrome/google-chrome-privacy-whitepaper.pdf">Chrome Privacy Whitepaper</a>
+  gives background detail regarding the features which this API can control.
+</p>
+
+<h2 id="manifest">Manifest</h2>
+<p>
+  You must declare the "privacy" permission in your extension's
+  <a href="manifest.html">manifest</a> to use the API. For example:
+</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "privacy"
+  ]</b>,
+  ...
+}</pre>
+
+<h2 id="usage">Usage</h2>
+
+<p>
+  Reading the current value of a Chrome setting is straightforward. You'll first
+  need to find the property you're interested in, then you'll call
+  <code>get()</code> on that object in order to retrieve it's current value and
+  your extension's level of control. For example, to determine if Chrome's
+  Autofill feature is enabled, you'd write:
+</p>
+
+<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
+  if (details.value)
+    console.log('Autofill is on!');
+  else
+    console.log('Autofill is off!');
+});</pre>
+
+<p>
+  Changing the value of a setting is a little bit more complex, simply because
+  you first must verify that your extension can control the setting. The user
+  won't see any change to her settings if you extension toggles a setting that
+  is either locked to a specific value by enterprise policies
+  (<code>levelOfControl</code> will be set to "not_controllable"), or if another
+  extension is controlling the value (<code>levelOfControl</code> will be set to
+  "controlled_by_other_extensions"). The <code>set()</code> call will succeed,
+  but the setting will be immediately overridden. As this might be confusing, it
+  is advisable to warn the user when the settings they've chosen aren't
+  practically applied.
+</p>
+
+<p class="note">
+  Full details about extensions' ability to control <code>ChromeSetting</code>s
+  can be found under
+  <a href="types.html#ChromeSetting">
+    <code>chrome.types.ChromeSetting</code></a>.
+</p>
+
+<p>
+  This means that you ought to use the <code>get()</code> method to determine
+  your level of access, and then only call <code>set()</code> if your extension
+  can grab control over the setting (in fact if your extension can't control the
+  setting it's probably a good idea to visibly disable the functionality to
+  reduce user confusion):
+</p>
+
+<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
+  if (details.levelOfControl === 'controllable_by_this_extension') {
+    chrome.privacy.services.autofillEnabled.set({ value: true }, function() {
+      if (chrome.extension.lastError === undefined)
+        console.log("Hooray, it worked!");
+      else
+        console.log("Sadness!", chrome.extension.lastError);
+    }
+  }
+});</pre>
+
+<p>
+  If you're interested in changes to a setting's value, add a listener to its
+  <code>onChange</code> event. Among other uses, this will allow you to warn the
+  user if a more recently installed extension grabs control of a setting, or if
+  enterprise policy overrides your control. To listen for changes to Autofill's
+  status, for example, the following code would suffice:
+</p>
+
+<pre>chrome.privacy.services.autofillEnabled.onChange.addListener(
+    function (details) {
+      // The new value is stored in `details.value`, the new level of control
+      // in `details.levelOfControl`, and `details.incognitoSpecific` will be
+      // `true` if the value is specific to Incognito mode.
+    });</pre>
+
+<h2 id="examples">Examples</h2>
+<p>
+  For example code, see the
+  <a href="samples.html#privacy">Privacy API samples</a>.
+</p>
+<!-- END AUTHORED CONTENT -->