mozilla

Revision 35868 of FileReaderSync

  • Revision slug: DOM/FileReaderSync
  • Revision title: FileReaderSync
  • Revision id: 35868
  • Created:
  • Creator: Rob W
  • Is current revision? No
  • Comment 7 words added, 11 words removed

Revision Content

The FileReaderSync interface allows to read File or Blob objects in a synchronous way.

This interface is only available in workers as it enables synchronous I/O that could potentially block.

Method overview

ArrayBuffer readAsArrayBuffer(Blob blob);{{ gecko_minversion_inline("8.0") }}
DOMString readAsBinaryString(Blob blob);{{ gecko_minversion_inline("8.0") }}
DOMString readAsText(Blob blob, optional DOMString encoding);{{ gecko_minversion_inline("8.0") }}
DOMString readAsDataURL(Blob blob);{{ gecko_minversion_inline("8.0") }}

Properties

There aren't any property for this interface.

Methods

readAsArrayBuffer()

This method reads the contents of the specified Blob or File. When the read operation is finished, it returns an ArrayBuffer representing the file's data. If an error happened during the read, the adequate exception is sent.

ArrayBuffer readAsArrayBuffer(
  in Blob blob
);

Parameters

blob
The DOM Blob or File to read into the ArrayBuffer.

Return value

An ArrayBuffer representing the file's data.

Exceptions

The following exceptions can be raised by this method:

NotFoundError
is raised when the resource represented by the DOM Blob or File cannot be found, e. g. because it has been erased.
SecurityError
is raised when one of the following problematic situation is detected:
  • the resource has been modified by a third party;
  • two many read are performed simultaneously;
  • the file pointed by the resource is unsafe for a use from the Web (like it is a system file).
NotReadableError
is raised when the resource cannot be read due to a permission problem, like a concurrent lock.
EncodingError
is raised when the resource is a data URL and exceed the limit length defined by each browser.

readAsBinaryString() {{ deprecated_inline() }}

This method reads the contents of the specified Blob, which may be a File. When the read operation is finished, it returns a DOMString containing the raw binary data from the file. If an error happened during the read, the adequate exception is sent.

Note : This method is deprecated and readAsArrayBuffer() should be used instead.
String readAsBinaryString(
  in Blob blob
);

Parameters

blob
The DOM Blob or File to read into the DOMString.

Return value

A DOMString containing the raw binary data from the resource

Exceptions

The following exceptions can be raised by this method:

NotFoundError
is raised when the resource represented by the DOM Blob or File cannot be found, e. g. because it has been erased.
SecurityError
is raised when one of the following problematic situation is detected:
  • the resource has been modified by a third party;
  • two many read are performed simultaneously;
  • the file pointed by the resource is unsafe for a use from the Web (like it is a system file).
NotReadableError
is raised when the resource cannot be read due to a permission problem, like a concurrent lock.
EncodingError
is raised when the resource is a data URL and exceed the limit length defined by each browser.

readAsText()

This methods reads the specified blob's contents. When the read operation is finished, it returns a DOMString containing the file represented as a text string. The optional encoding parameter indicates the encoding to be used. If not present, the method will apply a detection algorithm for it. If an error happened during the read, the adequate exception is sent.

String readAsText(
  in Blob blob,
  in DOMString encoding {{ optional_inline() }}
);

Parameters

blob
The DOM Blob or File to read into the DOMString.
encoding
Optional. A string representing the encoding to be used, like iso-8859-1 or UTF-8.

Return value

A DOMString containing the raw binary data from the resource

Exceptions

The following exceptions can be raised by this method:

NotFoundError
is raised when the resource represented by the DOM Blob or File cannot be found, e. g. because it has been erased.
SecurityError
is raised when one of the following problematic situation is detected:
  • the resource has been modified by a third party;
  • two many read are performed simultaneously;
  • the file pointed by the resource is unsafe for a use from the Web (like it is a system file).
NotReadableError
is raised when the resource cannot be read due to a permission problem, like a concurrent lock.

readAsDataURL()

This method reads the contents of the specified Blob or File. When the read operation is finished, it returns a data URL representing the file's data. If an error happened during the read, the adequate exception is sent.

String readAsDataURL(
  in Blob file
);

Parameters

blob
The DOM Blob or File to read.

Return value

An DOMString representing the file's data as a data URL.

Exceptions

The following exceptions can be raised by this method:

NotFoundError
is raised when the resource represented by the DOM Blob or File cannot be found, e. g. because it has been erased.
SecurityError
is raised when one of the following problematic situation is detected:
  • the resource has been modified by a third party;
  • too many read are performed simultaneously;
  • the file pointed by the resource is unsafe for a use from the Web (like it is a system file).
NotReadableError
is raised when the resource cannot be read due to a permission problem, like a concurrent lock.
EncodingError
is raised when the resource is a data URL and exceed the limit length defined by each browser.

See also

  • {{ spec("http://www.w3.org/TR/FileAPI/#FileReaderSync", "File API Specification: FileReaderSync", "WD") }}
  • Related interfaces: {{ domxref("FileReader") }}, {{ domxref("BlobBuilder") }}, {{ domxref("File") }}, {{ domxref("Blob") }}

Revision Source

<p>The <code>FileReaderSync</code> interface allows to read <code>File</code> or <code>Blob</code> objects in a synchronous way.</p>
<p>This interface is <a href="/en/DOM/Worker/Functions_available_to_workers" title="https://developer.mozilla.org/En/DOM/Worker/Functions_available_to_workers">only available</a> in <a href="/en/DOM/Worker" title="Worker">workers</a> as it enables synchronous I/O that could potentially block.</p>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>ArrayBuffer <a href="/en/DOM/FileReaderSync#readAsArrayBuffer()" title="en/DOM/FileReaderSync#readAsArrayBuffer()">readAsArrayBuffer</a>(Blob blob);</code>{{ gecko_minversion_inline("8.0") }}</td> </tr> <tr> <td><code>DOMString <a href="/en/DOM/FileReaderSync#readAsBinaryString()" title="en/DOM/FileReaderSync#readAsBinaryString()">readAsBinaryString</a>(Blob blob);</code>{{ gecko_minversion_inline("8.0") }}</td> </tr> <tr> <td><code>DOMString</code><code> </code><code><a href="/en/DOM/FileReaderSync#readAsText()" title="en/DOM/FileReaderSync#readAsText()">readAsText</a></code><code>(Blob blob, optional DOMString encoding);</code>{{ gecko_minversion_inline("8.0") }}</td> </tr> <tr> <td><code>DOMString <a href="/en/DOM/FileReaderSync#readAsDataURL()" title="en/DOM/FileReaderSync#readAsDataURL()">readAsDataURL</a>(Blob blob);</code>{{ gecko_minversion_inline("8.0") }}</td> </tr> </tbody>
</table>
<h2>Properties</h2>
<p>There aren't any property for this interface.</p>
<h2>Methods</h2>
<h3>readAsArrayBuffer()</h3>
<p>This method reads the contents of the specified <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code>. When the read operation is finished, it returns an <code><a href="../JavaScript_typed_arrays/ArrayBuffer" rel="internal" title="/en/JavaScript_typed_arrays/ArrayBuffer">ArrayBuffer</a></code> representing the file's data. If an error happened during the read, the adequate exception is sent.</p>
<pre class="eval">ArrayBuffer readAsArrayBuffer(
  in Blob blob
);
</pre>
<h4>Parameters</h4>
<dl> <dt><code>blob</code></dt> <dd>The DOM <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code> to read into the <code><a href="../JavaScript_typed_arrays/ArrayBuffer" rel="internal" title="/en/JavaScript_typed_arrays/ArrayBuffer">ArrayBuffer</a></code>.</dd>
</dl>
<h4>Return value</h4>
<p>An <code><a href="../JavaScript_typed_arrays/ArrayBuffer" rel="internal" title="/en/JavaScript_typed_arrays/ArrayBuffer">ArrayBuffer</a></code> representing the file's data.</p>
<h4>Exceptions</h4>
<p>The following exceptions can be raised by this method:</p>
<dl> <dt><code>NotFoundError</code></dt> <dd>is raised when the resource represented by the DOM <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code> cannot be found, e. g. because it has been erased.</dd> <dt><code>SecurityError</code></dt> <dd>is raised when one of the following problematic situation is detected: <ul style="margin-left: 40px;"> <li>the resource has been modified by a third party;</li> <li>two many read are performed simultaneously;</li> <li>the file pointed by the resource is unsafe for a use from the Web (like it is a system file).</li> </ul> </dd> <dt><code>NotReadableError</code></dt> <dd>is raised when the resource cannot be read due to a permission problem, like a concurrent lock.</dd> <dt><code>EncodingError</code></dt> <dd>is raised when the resource is a data URL and exceed the limit length defined by each browser.</dd>
</dl>
<h3>readAsBinaryString() {{ deprecated_inline() }}</h3>
<p>This method reads the contents of the specified <code><a href="Blob" rel="custom">Blob</a></code>, which may be a <code><a href="File" rel="custom">File</a></code>. When the read operation is finished, it returns a <a href="/en/DOM/DOMString" title="DOMString"><code>DOMString</code></a> containing the raw binary data from the file. If an error happened during the read, the adequate exception is sent.</p>
<div class="note"><strong>Note</strong> <strong>: </strong>This method is deprecated and <code>readAsArrayBuffer()</code> should be used instead.</div>
<pre class="eval">String readAsBinaryString(
  in Blob blob
);
</pre>
<h4>Parameters</h4>
<dl> <dt><code>blob</code></dt> <dd>The DOM <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code> to read into the <a href="/en/DOM/DOMString" title="DOMString"><code>DOMString</code></a>.</dd>
</dl>
<h4>Return value</h4>
<p><code>A </code><a href="/en/DOM/DOMString" title="DOMString"><code>DOMString</code></a> containing the raw binary data from the resource</p>
<h4 class="editable">Exceptions</h4>
<p>The following exceptions can be raised by this method:</p>
<dl> <dt><code>NotFoundError</code></dt> <dd>is raised when the resource represented by the DOM <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code> cannot be found, e. g. because it has been erased.</dd> <dt><code>SecurityError</code></dt> <dd>is raised when one of the following problematic situation is detected: <ul style="margin-left: 40px;"> <li>the resource has been modified by a third party;</li> <li>two many read are performed simultaneously;</li> <li>the file pointed by the resource is unsafe for a use from the Web (like it is a system file).</li> </ul> </dd> <dt><code>NotReadableError</code></dt> <dd>is raised when the resource cannot be read due to a permission problem, like a concurrent lock.</dd> <dt><code>EncodingError</code></dt> <dd>is raised when the resource is a data URL and exceed the limit length defined by each browser.</dd>
</dl>
<h3>readAsText()</h3>
<p>This methods reads the specified blob's contents. When the read operation is finished, it returns a <a href="/en/DOM/DOMString" title="DOMString"><code>DOMString</code></a> containing the file represented as a text string. The optional <strong><code>encoding</code></strong> parameter indicates the encoding to be used. If not present, the method will apply a detection algorithm for it. If an error happened during the read, the adequate exception is sent.</p>
<pre class="eval">String readAsText(
  in Blob blob,
  in DOMString encoding {{ optional_inline() }}
);
</pre>
<h4>Parameters</h4>
<dl> <dt><code>blob</code></dt> <dd>The DOM <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code> to read into the <a href="/en/DOM/DOMString" title="DOMString"><code>DOMString</code></a>.</dd> <dt><code>encoding</code></dt> <dd>Optional. A string representing the encoding to be used, like <strong>iso-8859-1</strong> or <strong>UTF-8</strong>.</dd>
</dl>
<h4>Return value</h4>
<p>A <a href="../../En/DOM/DOMString" rel="internal" title="DOMString"><code>DOMString</code></a> containing the raw binary data from the resource</p>
<h4>Exceptions</h4>
<p>The following exceptions can be raised by this method:</p>
<dl> <dt><code>NotFoundError</code></dt> <dd>is raised when the resource represented by the DOM <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code> cannot be found, e. g. because it has been erased.</dd> <dt><code>SecurityError</code></dt> <dd>is raised when one of the following problematic situation is detected: <ul style="margin-left: 40px;"> <li>the resource has been modified by a third party;</li> <li>two many read are performed simultaneously;</li> <li>the file pointed by the resource is unsafe for a use from the Web (like it is a system file).</li> </ul> </dd> <dt><code>NotReadableError</code></dt> <dd>is raised when the resource cannot be read due to a permission problem, like a concurrent lock.</dd>
</dl>
<h3 class="editable"><span>readAsDataURL()</span></h3>
<p>This method reads the contents of the specified <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code>. When the read operation is finished, it returns a data URL representing the file's data. If an error happened during the read, the adequate exception is sent.</p>
<pre class="eval">String readAsDataURL(
  in Blob file
);
</pre>
<div id="section_5"> <h4 class="editable"><span>Parameters</span></h4> <dl> <dt><code>blob</code></dt> <dd>The DOM <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code> to read.</dd> </dl>
</div>
<div id="section_6"> <h4 class="editable"><span>Return value</span></h4> <p>An <a href="/en/DOM/DOMString" title="DOMString"><code>DOMString</code></a> representing the file's data as a data URL.</p>
</div>
<h4 class="editable"><span>Exceptions</span></h4>
<p>The following exceptions can be raised by this method:</p>
<dl> <dt><code>NotFoundError</code></dt> <dd>is raised when the resource represented by the DOM <code><a href="Blob" rel="custom">Blob</a></code> or <code><a href="File" rel="custom">File</a></code> cannot be found, e. g. because it has been erased.</dd> <dt><code>SecurityError</code></dt> <dd>is raised when one of the following problematic situation is detected: <ul style="margin-left: 40px;"> <li>the resource has been modified by a third party;</li> <li>too many read are performed simultaneously;</li> <li>the file pointed by the resource is unsafe for a use from the Web (like it is a system file).</li> </ul> </dd> <dt><code>NotReadableError</code></dt> <dd>is raised when the resource cannot be read due to a permission problem, like a concurrent lock.</dd> <dt><code>EncodingError</code></dt> <dd>is raised when the resource is a data URL and exceed the limit length defined by each browser.</dd>
</dl>
<dl> <dt>
</dt></dl>
<h2>See also</h2>
<ul> <li>{{ spec("http://www.w3.org/TR/FileAPI/#FileReaderSync", "File API Specification: FileReaderSync", "WD") }}</li> <li>Related interfaces: {{ domxref("FileReader") }}, {{ domxref("BlobBuilder") }}, {{ domxref("File") }}, {{ domxref("Blob") }}</li>
</ul>
Revert to this revision