chrome/common/extensions/docs/experimental.downloads.html - Issue 9452019: experimental.downloads extension api docs

Unified Diff: chrome/common/extensions/docs/experimental.downloads.html

Issue 9452019: experimental.downloads extension api docs (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src

Patch Set: merge Created 8 years, 9 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

« no previous file with comments | « chrome/common/extensions/docs/experimental.html ('k') | chrome/common/extensions/docs/experimental.managedMode.html » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')

Index: chrome/common/extensions/docs/experimental.downloads.html

diff --git a/chrome/common/extensions/docs/ttsEngine.html b/chrome/common/extensions/docs/experimental.downloads.html

similarity index 63%

copy from chrome/common/extensions/docs/ttsEngine.html

copy to chrome/common/extensions/docs/experimental.downloads.html

index 1c293ea0c4fac6677960feff5c82ead3ef7b75e8..28d7440397db7cbcbe7e28b9483bbe58eb4672ec 100644

--- a/chrome/common/extensions/docs/ttsEngine.html

+++ b/chrome/common/extensions/docs/experimental.downloads.html

@@ -18,7 +18,7 @@

- <meta name="description" content="Documentation for the chrome.ttsEngine module, which is part of the Google Chrome extension APIs."><title>chrome.ttsEngine - Google Chrome Extensions - Google Code</title></head>

+ <meta name="description" content="Documentation for the chrome.experimental.downloads module, which is part of the Google Chrome extension APIs."><title>chrome.experimental.downloads - Google Chrome Extensions - Google Code</title></head>

You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.

</div>

@@ -185,40 +185,49 @@

</script>

- <h1 class="page_title">chrome.ttsEngine</h1>

+ <h1 class="page_title">chrome.experimental.downloads</h1>

</div>

<h2>Contents</h2>

<ol>

<li>

- <a href="#overview">Overview</a>

- <ol>

- </ol>

- </li><li>

<a href="#manifest">Manifest</a>

<ol>

</ol>

</li><li>

- <a href="#handling_speech_events">Handling speech events</a>

+ <a href="#examples"> Examples </a>

<ol>

</ol>

</li>

<li>

- <a href="#apiReference">API reference: chrome.ttsEngine</a>

+ <a href="#apiReference">API reference: chrome.experimental.downloads</a>

<ol>

<li>

+ <a href="#properties">Properties</a>

+ <ol>

+ <li>

+ <a href="#property-ERROR_GENERIC">ERROR_GENERIC</a>

+ </li><li>

+ <a href="#property-ERROR_INVALID_URL">ERROR_INVALID_URL</a>

+ </li>

+ </ol>

+ </li>

+ <li>

<a href="#global-methods">Methods</a>

<ol>

+ <li>

+ <a href="#method-download">download</a>

+ </li>

</ol>

</li>

<li>

- <a href="#global-events">Events</a>

+ <a href="#types">Types</a>

<ol>

<li>

- <a href="#event-onSpeak">onSpeak</a>

- </li><li>

- <a href="#event-onStop">onStop</a>

+ <a href="#type-HttpHeaders">HttpHeaders</a>

+ <ol>

+ </ol>

</li>

</ol>

</li>

@@ -228,191 +237,119 @@

</div>

+ <p id="classSummary">

+ For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page.

+ </p>

- <div id="static"><p id="classSummary">

-Use the <code>chrome.ttsEngine</code> module to

-implement a text-to-speech (TTS) engine using an extension. If your

-extension registers using this API, it will receive events containing

-an utterance to be spoken and other parameters when any extension or packaged

-app uses the

-<a href="tts.html">tts</a>

-module to generate speech. Your extension can then use any available

-web technology to synthesize and output the speech, and send events back

-to the calling function to report the status.

-</p>

-<h2 id="overview">Overview</h2>

-<p>An extension can register itself as a speech engine. By doing so, it

-can intercept some or all calls to functions such as

-<a href="tts.html#method-speak"><code>speak()</code></a> and

-<a href="tts.html#method-stop"><code>stop()</code></a>

-and provide an alternate implementation.

-Extensions are free to use any available web technology

-to provide speech, including streaming audio from a server, HTML5 audio,

-Native Client, or Flash. An extension could even do something different

-with the utterances, like display closed captions in a pop-up window or

-send them as log messages to a remote server.</p>

+ <div id="static"><p>The downloads API allows you to programmatically initiate downloads. In the

+future, you will also be able to monitor and manipulate downloads.</p>

<h2 id="manifest">Manifest</h2>

-<p>To implement a TTS engine, an extension must

-declare the "ttsEngine" permission and then declare all voices

-it provides in the extension manifest, like this:</p>

+<p>The downloads API is currently experimental, so you must declare the

+"experimental" permission to use it. Also, you must specify the hostname of any

+URLs to be downloaded. For example:</p>

<pre>{

- "name": "My TTS Engine",

- "version": "1.0",

- <b>"permissions": ["ttsEngine"],

- "tts_engine": {

- "voices": [

- {

- "voice_name": "Alice",

- "lang": "en-US",

- "gender": "female",

- "event_types": ["start", "marker", "end"]

- },

- {

- "voice_name": "Pat",

- "lang": "en-US",

- "event_types": ["end"]

- }

- ]

- },</b>

- "background_page": "background.html",

+ "name": "Download Selected Links",

+ "description": "Select links on a page and download them.",

+ "version": "0.1",

+ "permissions": [

+ "experimental", "http://*/*", "https://*/*"

+ ]

}</pre>

-<p>An extension can specify any number of voices.</p>

-<p>The <code>voice_name</code> parameter is required. The name should be

-descriptive enough that it identifies the name of the voice and the

-engine used. In the unlikely event that two extensions register voices

-with the same name, a client can specify the ID of the extension that

-should do the synthesis.</p>

-<p>The <code>gender</code> parameter is optional. If your voice corresponds

-to a male or female voice, you can use this parameter to help clients

-choose the most appropriate voice for their application.</p>

-<p>The <code>lang</code> parameter is optional, but highly recommended.

-Almost always, a voice can synthesize speech in just a single language.

-When an engine supports more than one language, it can easily register a

-separate voice for each language. Under rare circumstances where a single

-voice can handle more than one language, it's easiest to just list two

-separate voices and handle them using the same logic internally. However,

-if you want to create a voice that will handle utterances in any language,

-leave out the <code>lang</code> parameter from your extension's manifest.</p>

-<p>Finally, the <code>event_types</code> parameter is required if the engine can

-send events to update the client on the progress of speech synthesis.

-At a minimum, supporting the <code>'end'</code> event type to indicate

-when speech is finished is highly recommended, otherwise Chrome cannot

-schedule queued utterances.</p>

-<p class="note">

-<strong>Note:</strong> If your TTS engine does not support

-the <code>'end'</code> event type, Chrome cannot queue utterances

-because it has no way of knowing when your utterance has finished. To

-help mitigate this, Chrome passes an additional boolean <code>enqueue</code>

-option to your engine's onSpeak handler, giving you the option of

-implementing your own queueing. This is discouraged because then

-clients are unable to queue utterances that should get spoken by different

-speech engines.</p>

-<p>The possible event types that you can send correspond to the event types

-that the <code>speak()</code> method receives:</p>

-<ul>

- <li><code>'start'</code>: The engine has started speaking the utterance.

- </li><li><code>'word'</code>: A word boundary was reached. Use

- <code>event.charIndex</code> to determine the current speech

- position.

- </li><li><code>'sentence'</code>: A sentence boundary was reached. Use

- <code>event.charIndex</code> to determine the current speech

- position.

- </li><li><code>'marker'</code>: An SSML marker was reached. Use

- <code>event.charIndex</code> to determine the current speech

- position.

- </li><li><code>'end'</code>: The engine has finished speaking the utterance.

- </li><li><code>'error'</code>: An engine-specific error occurred and

- this utterance cannot be spoken.

- Pass more information in <code>event.errorMessage</code>.

-</li></ul>

-<p>The <code>'interrupted'</code> and <code>'cancelled'</code> events are

-not sent by the speech engine; they are generated automatically by Chrome.</p>

-<p>Text-to-speech clients can get the voice information from your

-extension's manifest by calling

-<a href="tts.html#method-getVoices">getVoices()</a>,

-assuming you've registered speech event listeners as described below.</p>

-<h2 id="handling_speech_events">Handling speech events</h2>

-<p>To generate speech at the request of clients, your extension must

-register listeners for both <code>onSpeak</code> and <code>onStop</code>,

-like this:</p>

-<pre>var speakListener = function(utterance, options, sendTtsEvent) {

- sendTtsEvent({'event_type': 'start', 'charIndex': 0})

- // (start speaking)

- sendTtsEvent({'event_type': 'end', 'charIndex': utterance.length})

-};

-var stopListener = function() {

- // (stop all speech)

-};

-chrome.ttsEngine.onSpeak.addListener(speakListener);

-chrome.ttsEngine.onStop.addListener(stopListener);</pre>

-<p class="warning">

-<b>Important:</b>

-If your extension does not register listeners for both

-<code>onSpeak</code> and <code>onStop</code>, it will not intercept any

-speech calls, regardless of what is in the manifest.</p>

-<p>The decision of whether or not to send a given speech request to an

-extension is based solely on whether the extension supports the given voice

-parameters in its manifest and has registered listeners

-for <code>onSpeak</code> and <code>onStop</code>. In other words,

-there's no way for an extension to receive a speech request and

-dynamically decide whether to handle it.</p>

+<p>If the URL’s hostname is not specified in the permissions, then the

+chrome.extensions.lastError object will indicate that the extension does not

+have permission to access that hostname.

+<a href="#properties">downloads.ERROR_*</a> are some of the errors that may be

+returned.</p>

+<h2 id="examples"> Examples </h2>

+<p>You can find simple examples of using the downloads module in the

+<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/downloads/">examples/api/downloads</a>

+directory. For other examples and for help in viewing the source code, see

+<a href="samples.html">Samples</a>.</p>

</div>

- <h2>API reference: chrome.ttsEngine</h2>

+ <h2>API reference: chrome.experimental.downloads</h2>

-

-

- <div id="methodsTemplate" class="apiGroup">

- <a name="global-methods"></a>

- <h3>Methods</h3>

-

-

- </div>

-

- <div id="eventsTemplate" class="apiGroup">

- <a name="global-events"></a>

- <h3>Events</h3>

-

- <div class="apiItem">

- <a name="event-onSpeak"></a>

- <h4>onSpeak</h4>

+ <div class="apiGroup">

+ <a name="properties"></a>

+ <h3 id="properties">Properties</h3>

+ <div>

+ <a name="property-ERROR_GENERIC"></a>

+ <h4>ERROR_GENERIC</h4>

- <span class="subdued">chrome.ttsEngine.</span><span>onSpeak</span><span class="subdued">.addListener</span>(function(<span>string utterance, object options, function sendTtsEvent</span>) <span class="subdued">{...}</span><span></span>);

+ <span>chrome.experimental.downloads.</span><span>ERROR_GENERIC</span>

</div>

- <div class="description">

- <p>Called when the user makes a call to tts.speak() and one of the voices from this extension's manifest is the first to match the options object.</p>

-

- <div>

- <h4>Listener parameters</h4>

- <dl>

- <div>

+ <div>

<dt>

- <var>utterance</var>

+ <var>ERROR_GENERIC</var>

<em>

(

- <span>

- <span>string</span>

- </span>

+ <code>"I'm afraid I can't do that."</code>

</span>

)

</div>

</em>

</dt>

- <dd>The text to speak, specified as either plain text or an SSML document. If your engine does not support SSML, you should strip out all XML markup and synthesize only the underlying text content. The value of this parameter is guaranteed to be no more than 32,768 characters. If this engine does not support speaking that many characters at a time, the utterance should be split into smaller chunks and queued internally without returning an error.</dd>

+ <dd>Generic error.</dd>

</div>

- </div><div>

- <div>

+ </div><div>

+ <a name="property-ERROR_INVALID_URL"></a>

+ <h4>ERROR_INVALID_URL</h4>

+ <div class="summary">

+

+ <span>chrome.experimental.downloads.</span><span>ERROR_INVALID_URL</span>

+ </div>

+ <div>

+ <dt>

+ <var>ERROR_INVALID_URL</var>

+ <em>

+

+ <div style="display:inline">

+ (

+ <span id="typeTemplate">

+ <code>"Invalid URL."</code>

+ </span>

+ )

+ </div>

+ </em>

+ </dt>

+ <dd>The URL was invalid.</dd>

+

+

+

+

+ </div>

+ </div>

+

+ <div id="methodsTemplate" class="apiGroup">

+ <a name="global-methods"></a>

+ <h3>Methods</h3>

+

+ <div class="apiItem">

+ <a name="method-download"></a>

+ <h4>download</h4>

+ <div class="summary">

+

+ <span>chrome.experimental.downloads.download</span>(<span class="null"><span>object</span>

+ <var><span>options</span></var></span><span class="optional"><span>, </span><span>function</span>

+ <var><span>callback</span></var></span>)</div>

+ <div class="description">

+ <p>Download a URL. If the URL uses the HTTP[S] protocol, then the request will include all cookies currently set for its hostname. If the download started successfully, <code>callback</code> will be called with the new DownloadItem’s <code>downloadId</code>. If there was an error starting the download, then <code>callback</code> will be called with <code>downloadId=undefined</code> and <code>chrome.extension.lastError</code> will be set. If both <code>filename</code> and <code>saveAs</code> are specified, then the Save As dialog will be displayed, pre-populated with the specified <code>filename</code>.</p>

+

+ <h4>Parameters</h4>

+ <dl>

+ <div>

<dt>

<var>options</var>

<em>

@@ -428,19 +365,20 @@ dynamically decide whether to handle it.</p>

</div>

</em>

</dt>

- <dd>Options specified to the tts.speak() method.</dd>

+ <dd class="todo">

+ Undocumented.

+ </dd>

<dd>

<dl>

<div>

<dt>

- <var>voiceName</var>

+ <var>url</var>

<em>

(

- <span class="optional">optional</span>

<span>

<span>string</span>

@@ -450,7 +388,7 @@ dynamically decide whether to handle it.</p>

</div>

</em>

</dt>

- <dd>The name of the voice to use for synthesis.</dd>

+ <dd>The URL to download.</dd>

@@ -459,7 +397,7 @@ dynamically decide whether to handle it.</p>

</div><div>

<div>

<dt>

- <var>lang</var>

+ <var>filename</var>

<em>

@@ -474,7 +412,7 @@ dynamically decide whether to handle it.</p>

</div>

</em>

</dt>

- <dd>The language to be used for synthesis, in the form <em>language</em>-<em>region</em>. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'.</dd>

+ <dd>A file path relative to the Downloads directory to contain the downloaded file.</dd>

@@ -483,24 +421,22 @@ dynamically decide whether to handle it.</p>

</div><div>

<div>

<dt>

- <var>gender</var>

+ <var>saveAs</var>

<em>

(

<span class="optional">optional</span>

- <span class="enum">enumerated</span>

<span>

- <span>string</span>

- <span>["male", "female"]</span>

+ <span>boolean</span>

</span>

)

</div>

</em>

</dt>

- <dd>Gender of voice for synthesized speech.</dd>

+ <dd>Use a file-chooser to allow the user to select a filename.</dd>

@@ -509,22 +445,24 @@ dynamically decide whether to handle it.</p>

</div><div>

<div>

<dt>

- <var>rate</var>

+ <var>method</var>

<em>

(

<span class="optional">optional</span>

+ <span class="enum">enumerated</span>

<span>

- <span>number</span>

+ <span>string</span>

+ <span>["GET", "POST"]</span>

</span>

)

</div>

</em>

</dt>

- <dd>Speaking rate relative to the default rate for this voice. 1.0 is the default rate, normally around 180 to 220 words per minute. 2.0 is twice as fast, and 0.5 is half as fast. This value is guaranteed to be between 0.1 and 10.0, inclusive. When a voice does not support this full range of rates, don't return an error. Instead, clip the rate to the range the voice supports.</dd>

+ <dd>The HTTP method to use if the URL uses the HTTP[S] protocol.</dd>

@@ -533,7 +471,7 @@ dynamically decide whether to handle it.</p>

</div><div>

<div>

<dt>

- <var>pitch</var>

+ <var>headers</var>

<em>

@@ -541,14 +479,14 @@ dynamically decide whether to handle it.</p>

<span class="optional">optional</span>

<span>

- <span>number</span>

+ <a href="webRequest.html#type-HttpHeaders">HttpHeaders</a>

</span>

)

</div>

</em>

</dt>

- <dd>Speaking pitch between 0 and 2 inclusive, with 0 being lowest and 2 being highest. 1.0 corresponds to this voice's default pitch.</dd>

+ <dd>Extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol, restricted to those allowed by XMLHttpRequest.</dd>

@@ -557,7 +495,7 @@ dynamically decide whether to handle it.</p>

</div><div>

<div>

<dt>

- <var>volume</var>

+ <var>body</var>

<em>

@@ -565,14 +503,14 @@ dynamically decide whether to handle it.</p>

<span class="optional">optional</span>

<span>

- <span>number</span>

+ <span>string</span>

</span>

)

</div>

</em>

</dt>

- <dd>Speaking volume between 0 and 1 inclusive, with 0 being lowest and 1 being highest, with a default of 1.0.</dd>

+ <dd>post body</dd>

@@ -585,14 +523,15 @@ dynamically decide whether to handle it.</p>

</div>

- </div><div>

- <div>

+ </div><div>

+ <div>

<dt>

- <var>sendTtsEvent</var>

+ <var>callback</var>

<em>

(

+ <span class="optional">optional</span>

<span>

<span>function</span>

@@ -602,70 +541,182 @@ dynamically decide whether to handle it.</p>

</div>

</em>

</dt>

- <dd>Call this function with events that occur in the process of speaking the utterance.</dd>

+ <dd class="todo">

+ Undocumented.

+ </dd>

- <dd>

- <div>

- <h5>Parameters</h5>

- <dl>

- <div>

+ </div>

+ </dl>

+

+ <dl>

+ </dl>

+

+ <div>

+ <h4>Callback function</h4>

+ <p>

+ If you specify the <em>callback</em> parameter, it should

+ specify a function that looks like this:

+ </p>

+

+ <pre>function(<span>integer downloadId</span>) <span class="subdued">{...}</span>;</pre>

+ <dl>

+ <div>

<dt>

- <var>event</var>

+ <var>downloadId</var>

<em>

(

<span>

- <a href="tts.html#type-TtsEvent">TtsEvent</a>

+ <span>integer</span>

</span>

)

</div>

</em>

</dt>

- <dd>The event from the text-to-speech engine indicating the status of this utterance.</dd>

+ <dd>If not null, the identifier of the resulting Download Item.</dd>

</div>

- </div>

- </dl>

- </div>

- </dd>

- </div>

</div>

</dl>

+ </div>

</div>

-

-

- <dl>

- </dl>

+

</div>

- </div><div class="apiItem">

- <a name="event-onStop"></a>

- <h4>onStop</h4>

- <div class="summary">

-

- <span class="subdued">chrome.ttsEngine.</span><span>onStop</span><span class="subdued">.addListener</span>(function(<span></span>) <span class="subdued">{...}</span><span></span>);

+ </div>

+ </div>

+

+

+

+ <div class="apiGroup">

+ <a name="types"></a>

+ <h3 id="types">Types</h3>

+

+ <div class="apiItem">

+ <a name="type-HttpHeaders"></a>

+ <h4>HttpHeaders</h4>

+ <div>

+ <dt>

+ <em>

+

+ <div style="display:inline">

+ (

+ <span id="typeTemplate">

+ <span>

+ array of <span><span>

+ <span>

+ <span>object</span>

+ </span>

+ </span></span>

+ </span>

+ )

+ </div>

+ </em>

+ </dt>

+ <dd>An array of HTTP headers. Each header is represented as a dictionary containing the keys <code>name</code> and either <code>value</code> or <code>binaryValue</code>.</dd>

+

+ <dd>

+ <dl>

+ <div>

+ <dt>

+ <var>name</var>

+ <em>

+

+ <div style="display:inline">

+ (

+ <span id="typeTemplate">

+ <span>

+ <span>string</span>

+ </span>

+ )

+ </div>

+ </em>

+ </dt>

+ <dd>Name of the HTTP header.</dd>

+

+

+

+

+ </div>

+ </div><div>

+ <div>

+ <dt>

+ <var>value</var>

+ <em>

+

+ <div style="display:inline">

+ (

+ <span class="optional">optional</span>

+ <span id="typeTemplate">

+ <span>

+ <span>string</span>

+ </span>

+ )

+ </div>

+ </em>

+ </dt>

+ <dd>Value of the HTTP header if it can be represented by UTF-8.</dd>

+

+

+

+

+ </div>

+ </div><div>

+ <div>

+ <dt>

+ <var>binaryValue</var>

+ <em>

+

+ <div style="display:inline">

+ (

+ <span class="optional">optional</span>

+ <span id="typeTemplate">

+ <span>

+ array of <span><span>

+ <span>

+ <span>integer</span>

+ </span>

+ </span></span>

+ </span>

+ )

+ </div>

+ </em>

+ </dt>

+ <dd>Value of the HTTP header if it cannot be represented by UTF-8, stored as individual byte values (0..255).</dd>

+

+

+

+

+ </div>

</div>

- <div class="description">

- <p>Fired when a call is made to tts.stop and this extension may be in the middle of speaking. If an extension receives a call to onStop and speech is already stopped, it should do nothing (not raise an error).</p>

-

-

-

- <dl>

- </dl>

- </div>

+ </dl>

+ </dd>

+

+

+

+ </div>

</div>

</div>

-

-

</div>

</div>

</div>

« no previous file with comments | « chrome/common/extensions/docs/experimental.html ('k') | chrome/common/extensions/docs/experimental.managedMode.html » ('j') | no next file with comments »