- From: poot <cvsmail@w3.org>
- Date: Tue, 01 Feb 2011 03:19:56 -0500
- To: public-html-diffs@w3.org
hixie: Specify window.atob() and .btoa(). (ack Aryeh for the reverse- engineering to do this) (whatwg r5814) http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.4672&r2=1.4673&f=h http://html5.org/tools/web-apps-tracker?from=5813&to=5814 =================================================================== RCS file: /sources/public/html5/spec/Overview.html,v retrieving revision 1.4672 retrieving revision 1.4673 diff -u -d -r1.4672 -r1.4673 --- Overview.html 1 Feb 2011 01:30:12 -0000 1.4672 +++ Overview.html 1 Feb 2011 08:18:35 -0000 1.4673 @@ -240,6 +240,24 @@ .details-example img { vertical-align: top; } + #base64-table { + white-space: nowrap; + font-size: 0.6em; + column-width: 6em; + column-count: 5; + column-gap: 1em; + -moz-column-width: 6em; + -moz-column-count: 5; + -moz-column-gap: 1em; + -webkit-column-width: 6em; + -webkit-column-count: 5; + -webkit-column-gap: 1em; + } + #base64-table thead { display: none; } + #base64-table * { border: none; } + #base64-table tbody td:first-child:after { content: ':'; } + #base64-table tbody td:last-child { text-align: right; } + #named-character-references-table { white-space: nowrap; font-size: 0.6em; @@ -1052,20 +1070,21 @@ <li><a href="#event-firing"><span class="secno">6.1.6.3 </span>Event firing</a></li> <li><a href="#events-and-the-window-object"><span class="secno">6.1.6.4 </span>Events and the <code>Window</code> object</a></li> <li><a href="#runtime-script-errors"><span class="secno">6.1.6.5 </span>Runtime script errors</a></ol></ol></li> - <li><a href="#timers"><span class="secno">6.2 </span>Timers</a></li> - <li><a href="#user-prompts"><span class="secno">6.3 </span>User prompts</a> + <li><a href="#atob"><span class="secno">6.2 </span>Base64 utility methods</a></li> + <li><a href="#timers"><span class="secno">6.3 </span>Timers</a></li> + <li><a href="#user-prompts"><span class="secno">6.4 </span>User prompts</a> <ol> - <li><a href="#simple-dialogs"><span class="secno">6.3.1 </span>Simple dialogs</a></li> - <li><a href="#printing"><span class="secno">6.3.2 </span>Printing</a></li> - <li><a href="#dialogs-implemented-using-separate-documents"><span class="secno">6.3.3 </span>Dialogs implemented using separate documents</a></ol></li> - <li><a href="#system-state-and-capabilities:-the-navigator-object"><span class="secno">6.4 </span>System state and capabilities: the <code>Navigator</code> object</a> + <li><a href="#simple-dialogs"><span class="secno">6.4.1 </span>Simple dialogs</a></li> + <li><a href="#printing"><span class="secno">6.4.2 </span>Printing</a></li> + <li><a href="#dialogs-implemented-using-separate-documents"><span class="secno">6.4.3 </span>Dialogs implemented using separate documents</a></ol></li> + <li><a href="#system-state-and-capabilities:-the-navigator-object"><span class="secno">6.5 </span>System state and capabilities: the <code>Navigator</code> object</a> <ol> - <li><a href="#client-identification"><span class="secno">6.4.1 </span>Client identification</a></li> - <li><a href="#custom-handlers"><span class="secno">6.4.2 </span>Custom scheme and content handlers</a> + <li><a href="#client-identification"><span class="secno">6.5.1 </span>Client identification</a></li> + <li><a href="#custom-handlers"><span class="secno">6.5.2 </span>Custom scheme and content handlers</a> <ol> - <li><a href="#security-and-privacy"><span class="secno">6.4.2.1 </span>Security and privacy</a></li> - <li><a href="#sample-handler-impl"><span class="secno">6.4.2.2 </span>Sample user interface</a></ol></li> - <li><a href="#manually-releasing-the-storage-mutex"><span class="secno">6.4.3 </span>Manually releasing the storage mutex</a></ol></ol></li> + <li><a href="#security-and-privacy"><span class="secno">6.5.2.1 </span>Security and privacy</a></li> + <li><a href="#sample-handler-impl"><span class="secno">6.5.2.2 </span>Sample user interface</a></ol></li> + <li><a href="#manually-releasing-the-storage-mutex"><span class="secno">6.5.3 </span>Manually releasing the storage mutex</a></ol></ol></li> <li><a href="#editing"><span class="secno">7 </span>User interaction</a> <ol> <li><a href="#the-hidden-attribute"><span class="secno">7.1 </span>The <code>hidden</code> attribute</a></li> @@ -2878,6 +2897,11 @@ is passed an Infinity or Not-a-Number (NaN) value, a <code><a href="#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception must be raised.</p> + <p>Except where otherwise specified, if a method has an argument + of type <code>DOMString</code>, the user agent must <span title="dfn-obtain-unicode">convert the <code>DOMString</code> to a + sequence of Unicode characters</span> when the method is invoked, + to obtain the string on which the method is to operate. <a href="#refsWEBIDL">[WEBIDL]</a></p> + </dd> <dt>JavaScript</dt> @@ -48624,7 +48648,228 @@ </dd> - </dl></div><h3 id="timers"><span class="secno">6.2 </span>Timers</h3><p>The <code title="dom-windowtimers-setTimeout"><a href="#dom-windowtimers-settimeout">setTimeout()</a></code> + </dl></div><h3 id="atob"><span class="secno">6.2 </span>Base64 utility methods</h3><p>The <code title="dom-windowbase64-atob"><a href="#dom-windowbase64-atob">atob()</a></code> and <code title="dom-windowbase64-btoa"><a href="#dom-windowbase64-btoa">btoa()</a></code> methods allow authors to + transform content to and from the base64 encoding.</p><!-- v2: actual binary support --><pre class="idl">[Supplemental, NoInterfaceObject] +interface <dfn id="windowbase64">WindowBase64</dfn> { + DOMString <a href="#dom-windowbase64-btoa" title="dom-windowbase64-btoa">btoa</a>(in DOMString btoa); + DOMString <a href="#dom-windowbase64-atob" title="dom-windowbase64-atob">atob</a>(in DOMString atob); +}; +<a href="#window">Window</a> implements <a href="#windowbase64">WindowBase64</a>;</pre><p class="note">In these APIs, for mnemonic purposes, the "b" can be + considered to stand for "binary", and the "a" for "ASCII". In + practice, though, for primarily historical reasons, both the input + and output of these functions are Unicode strings.<dl class="domintro"><dt><var title="">result</var> = <var title="">window</var> . <code title="dom-windowbase64-btoa"><a href="#dom-windowbase64-btoa">btoa</a></code>( <var title="">data</var> )</dt> + + <dd> + + <p>Takes the input data, in the form of a Unicode string + containing only characters in the range U+0000 to U+00FF, each + representing a binary byte with values 0x00 to 0xFF respectively, + and converts it to its base64 representation, which it returns.</p> + + <p>Throws an <code><a href="#invalid_character_err">INVALID_CHARACTER_ERR</a></code> exception if the + input string contains any out-of-range characters.</p> + + </dd> + + <dt><var title="">result</var> = <var title="">window</var> . <code title="dom-windowbase64-atob"><a href="#dom-windowbase64-atob">atob</a></code>( <var title="">data</var> )</dt> + + <dd> + + <p>Takes the input data, in the form of a Unicode string + containing base64-encoded binary data, decodes it, and returns a + string consisting of characters in the range U+0000 to U+00FF, + each representing a binary byte with values 0x00 to 0xFF + respectively, corresponding to that binary data.</p> + + <p>Throws an <code><a href="#invalid_character_err">INVALID_CHARACTER_ERR</a></code> exception if the + input string is not valid base64 data.</p> + + </dd> + + </dl><div class="impl"> + + <p class="note">The <code><a href="#windowbase64">WindowBase64</a></code> interface adds to the + <code><a href="#window">Window</a></code> interface and the <code>WorkerUtils</code> + interface (part of Web Workers).</p> + + <p>The <dfn id="dom-windowbase64-btoa" title="dom-windowbase64-btoa"><code>btoa()</code></dfn> + method must throw an <code><a href="#invalid_character_err">INVALID_CHARACTER_ERR</a></code> exeption if + the method's first argument contains any character whose code point + is greater than U+00FF. Otherwise, the user agent must convert that + argument to a sequence of octets whose <var title="">n</var>th octet + is the eight-bit representation of the code point of the <var title="">n</var>th character of the argument, and then must apply + the base64 algorithm to that sequence of octets, and return the + result. <a href="#refsRFC4648">[RFC4648]</a><!--base64--></p> + <!-- Aryeh says: This seems to be what all browsers do as of January + 2011 (except IE, which doesn't support these functions at all). --> + + + <p>The <dfn id="dom-windowbase64-atob" title="dom-windowbase64-atob"><code>atob()</code></dfn> + method must run the following steps to parse the string passed in + the method's first argument:</p> + + <ol><!-- Aryeh says: Copies Firefox behavior as of January 2011 + (4.0b8). WebKit is somewhat laxer, and Opera throws no exceptions + at all. gsnedders reports Opera's behavior causes site-compat + problems, and I figure most sites depend on Firefox if on anything, + so go with that. --><li><p>Let <var title="">input</var> be the string being + parsed.</li> + + <li><p>Let <var title="">position</var> be a pointer into <var title="">input</var>, initially pointing at the start of the + string.</li> + + <li><p>If the length of <var title="">input</var> divides by 4 + leaving no remainder, then: if <var title="">input</var> ends with + one or two U+003D EQUALS SIGN (=) characters, remove them from <var title="">input</var>.</li> + + <li><p>If the length of <var title="">input</var> divides by 4 + leaving a remainder of 1, throw an + <code><a href="#invalid_character_err">INVALID_CHARACTER_ERR</a></code> exception and abort these + steps.</p> + + <li> + + <p>If <var title="">input</var> contains a character that is not + in the following list of characters and character ranges, throw an + <code><a href="#invalid_character_err">INVALID_CHARACTER_ERR</a></code> exception and abort these + steps:</p> + + <ul class="brief"><li>U+002B PLUS SIGN (+) + <li>U+002F SOLIDUS (/) + <li>U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) + <li>U+0041 LATIN CAPITAL LETTER A to U+005A LATIN CAPITAL LETTER Z + <li>U+0061 LATIN SMALL LETTER A to U+007A LATIN SMALL LETTER Z + </ul></li> + + <li><p>Let <var title="">output</var> be a string, initially + empty.</li> + + <li><p>Let <var title="">buffer</var> be a buffer that can have + bits appended to it, initially empty.</li> + + <li> + + <p>While <var title="">position</var> does not point past the end + of <var title="">input</var>, run these substeps:</p> + + <ol><li> + + <p>Find the character pointed to by <var title="">position</var> + in the first column of the following table. Let <var title="">n</var> be the number given in the second cell of the + same row.</p> + + <div id="base64-table"> + <table><thead><tr><th>Character + <th>Number + <tbody><tr><td>A<td>0 + <tr><td>B<td>1 + <tr><td>C<td>2 + <tr><td>D<td>3 + <tr><td>E<td>4 + <tr><td>F<td>5 + <tr><td>G<td>6 + <tr><td>H<td>7 + <tr><td>I<td>8 + <tr><td>J<td>9 + <tr><td>K<td>10 + <tr><td>L<td>11 + <tr><td>M<td>12 + <tr><td>N<td>13 + <tr><td>O<td>14 + <tr><td>P<td>15 + <tr><td>Q<td>16 + <tr><td>R<td>17 + <tr><td>S<td>18 + <tr><td>T<td>19 + <tr><td>U<td>20 + <tr><td>V<td>21 + <tr><td>W<td>22 + <tr><td>X<td>23 + <tr><td>Y<td>24 + <tr><td>Z<td>25 + <tr><td>a<td>26 + <tr><td>b<td>27 + <tr><td>c<td>28 + <tr><td>d<td>29 + <tr><td>e<td>30 + <tr><td>f<td>31 + <tr><td>g<td>32 + <tr><td>h<td>33 + <tr><td>i<td>34 + <tr><td>j<td>35 + <tr><td>k<td>36 + <tr><td>l<td>37 + <tr><td>m<td>38 + <tr><td>n<td>39 + <tr><td>o<td>40 + <tr><td>p<td>41 + <tr><td>q<td>42 + <tr><td>r<td>43 + <tr><td>s<td>44 + <tr><td>t<td>45 + <tr><td>u<td>46 + <tr><td>v<td>47 + <tr><td>w<td>48 + <tr><td>x<td>49 + <tr><td>y<td>50 + <tr><td>z<td>51 + <tr><td>0<td>52 + <tr><td>1<td>53 + <tr><td>2<td>54 + <tr><td>3<td>55 + <tr><td>4<td>56 + <tr><td>5<td>57 + <tr><td>6<td>58 + <tr><td>7<td>59 + <tr><td>8<td>60 + <tr><td>9<td>61 + <tr><td>+<td>62 + <tr><td>/<td>63 + </table></div> + + </li> + + <li><p>Append to <var title="">buffer</var> the six bits + corresponding to <var title="">number</var>, most significant bit + first.</li> + + <li><p>If <var title="">buffer</var> has accumulated 24 bits, + interpret them as three 8-bit big-endian numbers. Append the + three characters with code points equal to those numbers to <var title="">output</var>, in the same order, and then empty <var title="">buffer</var>.</li> + + <li><p>Advance <var title="">position</var> by one + character.</li> + + </ol></li> + + <li> + + <p>If <var title="">buffer</var> is not empty, it contains either + 12 or 18 bits. If it contains 12 bits, discard the last four and + interpret the remaining eight as an 8-bit big-endian number. If it + contains 18 bits, discard the last two and interpret the remaining + 16 as two 8-bit big-endian numbers. Append the one or two + characters with code points equal to those one or two numbers to + <var title="">output</var>, in the same order.</p> + + <p>The discarded bits mean that, for instance, <code title="">atob("YQ")</code> and <code title="">atob("YR")</code> + both return "<code title="">a</code>".</p> + + </li> + + <li><p>Return <var title="">output</var>.</li> + + </ol><!-- Note: this function is defined explicitly here because RFC4648 + does not specify how to handle erroneous input, and no preexisting + browser implementation simply throws an exception on all erroneous + input. --><p class="note">Some base64 encoders add newlines or other + whitespace to their output. The <code title="dom-windowbase64-atob"><a href="#dom-windowbase64-atob">atob()</a></code> method throws an + exception if its input contains characters other than those + described by the regular expression bracket expression <code title="">[+/=0-9A-Za-z]</code>, so other characters need to be + removed before <code title="dom-windowbase64-atob"><a href="#dom-windowbase64-atob">atob()</a></code> is + used for decoding.</p> + + </div><h3 id="timers"><span class="secno">6.3 </span>Timers</h3><p>The <code title="dom-windowtimers-setTimeout"><a href="#dom-windowtimers-settimeout">setTimeout()</a></code> and <code title="dom-windowtimers-setInterval"><a href="#dom-windowtimers-setinterval">setInterval()</a></code> methods allow authors to schedule timer-based callbacks.<pre class="idl">[Supplemental, NoInterfaceObject] interface <dfn id="windowtimers">WindowTimers</dfn> { @@ -48932,14 +49177,14 @@ </ol><hr><p>The <a href="#task-source">task source</a> for these <a href="#concept-task" title="concept-task">tasks</a> is the <dfn id="timer-task-source">timer task source</dfn>.</p> - </div><h3 id="user-prompts"><span class="secno">6.3 </span>User prompts</h3><!-- + </div><h3 id="user-prompts"><span class="secno">6.4 </span>User prompts</h3><!-- v2 ideas: * in-window modal dialogs - escape/enter handling - dragging the window out of the tab * in-window non-modal palettes - with a solution for the mobile space - --><h4 id="simple-dialogs"><span class="secno">6.3.1 </span>Simple dialogs</h4><dl class="domintro"><dt><var title="">window</var> . <code title="dom-alert"><a href="#dom-alert">alert</a></code>(<var title="">message</var>)</dt> + --><h4 id="simple-dialogs"><span class="secno">6.4.1 </span>Simple dialogs</h4><dl class="domintro"><dt><var title="">window</var> . <code title="dom-alert"><a href="#dom-alert">alert</a></code>(<var title="">message</var>)</dt> <dd> <p>Displays a modal alert with the given message, and waits for the user to dismiss it.</p> @@ -49001,7 +49246,7 @@ user aborts, then the method must return null; otherwise, the method must return the string that the user responded with.</p> - </div><h4 id="printing"><span class="secno">6.3.2 </span>Printing</h4><dl class="domintro"><dt><var title="">window</var> . <code title="dom-print"><a href="#dom-print">print</a></code>()</dt> + </div><h4 id="printing"><span class="secno">6.4.2 </span>Printing</h4><dl class="domintro"><dt><var title="">window</var> . <code title="dom-print"><a href="#dom-print">print</a></code>()</dt> <dd> @@ -49090,7 +49335,7 @@ </li> - </ol></div><h4 id="dialogs-implemented-using-separate-documents"><span class="secno">6.3.3 </span>Dialogs implemented using separate documents</h4><dl class="domintro"><dt><var title="">result</var> = <var title="">window</var> . <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog</a></code>(<var title="">url</var> [, <var title="">argument</var>] )</dt> + </ol></div><h4 id="dialogs-implemented-using-separate-documents"><span class="secno">6.4.3 </span>Dialogs implemented using separate documents</h4><dl class="domintro"><dt><var title="">result</var> = <var title="">window</var> . <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog</a></code>(<var title="">url</var> [, <var title="">argument</var>] )</dt> <dd> @@ -49296,7 +49541,7 @@ value</a> to the given new value.</p> </div><p class="note">The <code title="dom-window-close"><a href="#dom-window-close">window.close()</a></code> method can be used to - close the browsing context.<h3 id="system-state-and-capabilities:-the-navigator-object"><span class="secno">6.4 </span>System state and capabilities: the <code><a href="#navigator">Navigator</a></code> object</h3><div class="impl"> + close the browsing context.<h3 id="system-state-and-capabilities:-the-navigator-object"><span class="secno">6.5 </span>System state and capabilities: the <code><a href="#navigator">Navigator</a></code> object</h3><div class="impl"> <p>The <dfn id="dom-navigator" title="dom-navigator"><code>navigator</code></dfn> attribute of the <code><a href="#window">Window</a></code> interface must return an @@ -49352,7 +49597,7 @@ <dd><p>Must return either null or a language tag representing the user's preferred language.</p></dd> --> - </div><h4 id="client-identification"><span class="secno">6.4.1 </span>Client identification</h4><p>In certain cases, despite the best efforts of the entire + </div><h4 id="client-identification"><span class="secno">6.5.1 </span>Client identification</h4><p>In certain cases, despite the best efforts of the entire industry, Web browsers have bugs and limitations that Web authors are forced to work around.<p>This section defines a collection of attributes that can be used to determine, from script, the kind of user agent in use, in order @@ -49417,7 +49662,7 @@ identified. For this reason, user agent implementors are strongly urged to include as little information in this API as possible.</p> - </div><h4 id="custom-handlers"><span class="secno">6.4.2 </span>Custom scheme and content handlers</h4><p>The <dfn id="dom-navigator-registerprotocolhandler" title="dom-navigator-registerProtocolHandler"><code>registerProtocolHandler()</code></dfn> + </div><h4 id="custom-handlers"><span class="secno">6.5.2 </span>Custom scheme and content handlers</h4><p>The <dfn id="dom-navigator-registerprotocolhandler" title="dom-navigator-registerProtocolHandler"><code>registerProtocolHandler()</code></dfn> method allows Web sites to register themselves as possible handlers for particular schemes. For example, an online telephone messaging service could register itself as a handler of the <code>sms:</code> @@ -49605,7 +49850,7 @@ </div><div class="impl"> - <h5 id="security-and-privacy"><span class="secno">6.4.2.1 </span>Security and privacy</h5> + <h5 id="security-and-privacy"><span class="secno">6.5.2.1 </span>Security and privacy</h5> <p>These mechanisms can introduce a number of concerns, in particular privacy concerns.</p> @@ -49686,7 +49931,7 @@ </div><div class="impl"> - <h5 id="sample-handler-impl"><span class="secno">6.4.2.2 </span>Sample user interface</h5> + <h5 id="sample-handler-impl"><span class="secno">6.5.2.2 </span>Sample user interface</h5> <p><i>This section is non-normative.</i></p> @@ -49728,7 +49973,7 @@ method would work equivalently, but for schemes instead of unknown content types.</p> - </div><h4 id="manually-releasing-the-storage-mutex"><span class="secno">6.4.3 </span>Manually releasing the storage mutex</h4><dl class="domintro"><dt><var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-yieldForStorageUpdates"><a href="#dom-navigator-yieldforstorageupdates">yieldForStorageUpdates</a></code>()</dt> + </div><h4 id="manually-releasing-the-storage-mutex"><span class="secno">6.5.3 </span>Manually releasing the storage mutex</h4><dl class="domintro"><dt><var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-yieldForStorageUpdates"><a href="#dom-navigator-yieldforstorageupdates">yieldForStorageUpdates</a></code>()</dt> <dd>
Received on Tuesday, 1 February 2011 08:19:59 UTC