W3C File API support in Opera Presto 2.8

W3C reference
W3C File API
On this page...
Blob Interface
File Interface
FileReader Interface
FileReaderSync Interface
Errors and Exceptions

This W3C Editor's Draft specification provides an API for representing file objects in web applications, as well as programmatically selecting them and accessing their data. This includes:

Additionally, this specification defines objects to be used within threaded web applications for the synchronous reading of files. The interfaces and API can be used with other interfaces and APIs exposed to the web platform.

Opera Presto provides partial support for the W3C File API as described in the following data tables.

For your guide, the following items are supported:

The following items are not supported:

Blob Interface

This interface represents raw data. It provides a method to slice data objects between ranges of bytes into further chunks of raw data. It also provides an attribute representing the size of the chunk of data.

Attributes

Attribute Description Support
size Represents the size of the Blob object in bytes. Yes
type Represents the ASCII-encoded string in lower case representing the media type of the Blob. Yes

Methods and Parameters

Method Parameter Description Support
slice Returns a new Blob object between the ranges of bytes specified. Yes
start This is a value for the start point of a slice call. Yes
length This is a value for the end point of a slice call as byte offsets from start. Yes
contentType This is optional, and can be used to set a value identical to one that is set with the HTTP/1.1 Content-Type header on the Blob returned by the slice call. Yes

File Interface

This interface describes a single file in a FileList and exposes its name. It inherits from Blob. It is available on objects that expose an attribute of type FileList; these objects are defined in HTML5.

Attribute Description Support
name The name of the file.
  • On getting, this MUST return the name of the file as a string.
  • There are numerous file name variations on different systems; this is merely the name of the file, without path information.
  • On getting, if user agents cannot make this information available, they MUST return the empty string.
 Yes
lastModifiedDate The last modified date of the file.
  • On getting, if user agents can make this information available, this MUST return a new Date object initialized to the last modified date of the file; otherwise, this MUST return null.
  • Important note: For privacy reasons, Opera uses the option in the specification to always return null here.
 Yes

FileReader Interface

This interface provides methods to read Files or Blobs into memory, and to access the data from those Files or Blobs using progress events and event handler attributes. It is desirable to read data from file systems asynchronously in the main thread of user agents. This interface provides such an asynchronous API, and is specified to be used with the global object (Window).

Constructors

Constructor Description Support
FileReader() When the FileReader() constructor is invoked, the user agent MUST return a new FileReader object.
  • In environments where the global object is represented by a Window or a WorkerGlobalScope object, the FileReader constructor MUST be available.
 Yes

Event handler attributes

The following data table describes the event handler attributes (and their corresponding event handler event types) that user agents MUST support on FileReader as DOM attributes.

Attribute Event type Description Support
onloadstart loadstart Dispatched when the read starts. Yes
onprogress progress Dispatched while reading (and decoding) blob, and reporting partial Blob data (progess.loaded/progress.total). Yes
onabort abort Dispatched when the read has been aborted. For instance, by invoking the abort() method. Yes
onerror error Dispatched when the read has failed. Yes
onload load Dispatched when the read has successfully completed. Yes
onloadend loadend Dispatched when the request has completed (either in success or failure). Yes

FileReader States

The FileReader object can be in one of three states. The readyState attribute, on getting, MUST return the current state, which MUST be one of the following values:

State Numeric value Description Support
EMPTY 0 The object has been constructed, and there are no pending reads. Yes
LOADING 1 A File or Blob is being read.
  • One of the read methods is being processed.
 Yes
DONE 2 The entire File or Blob has been read into memory, or a file error occurred during read, or the read was aborted using abort().
  • The FileReader is no longer reading a File or Blob.
 Yes

Reading a File or Blob

Multiple reads

The FileReader interface makes available four asynchronous read methods which read files into memory. If multiple read methods are called on the same FileReader object, user agents MUST only process the last call to a read method, which is the call that occurs last in a script block that has the "already started" flag set.

Read Method Description Support
readAsArrayBuffer() When the readAsArrayBuffer(blob) method is called, the user agent MUST run the steps below (unless otherwise indicated).
  1. Set readyState to EMPTY and set result to null.
  2. If an error occurs during reading the blob parameter, set readyState to DONE and set result to null. Proceed to the following error steps:
    1. Dispatch a progress event called error. Set the error attribute; on getting, the error attribute MUST be a a FileError object with a valid error code that indicates the kind of file error that has occurred.
    2. Dispatch a progress event called loadend.
    3. Terminate this overall set of steps.
  3. If no error has occurred, set readyState to LOADING.
  4. Queue a task to dispatch a progress event called loadstart.
  5. Make progress notifications. As the bytes from the blob argument are read, user agents SHOULD ensure that on getting, the result attribute returns partial Blob data representing the number of bytes currently loaded (as a fraction of the total) , as an ArrayBuffer; user agents SHOULD return at least one such ArrayBuffer while processing this read method.
  6. When the blob has been fully read into memory, set readyState to DONE.
  7. Set the result attribute to be blob's data content represented as an ArrayBuffer; on getting, the result attribute returns the (complete) data of blob as an ArrayBuffer.
  8. Terminate this overall set of steps.
Note: This method is included in Opera Presto, but not functional. 		No
readAsBinaryString() When the readAsBinaryString(blob) method is called, the user agent MUST run the following steps (unless otherwise indicated):
  1. Set readyState to EMPTY and set result to null.
  2. If an error occurs during reading of the blob parameter, set readyState to DONE and set result to null. Proceed to the following error steps:
    1. Dispatch a progress event called error. Set the error attribute; on getting, the error attribute MUST be a a FileError object with a valid error code that indicates the kind of file error that has occurred.
    2. Dispatch a progress event called loadend.
    3. Terminate this overall set of steps.
  3. If no error has occurred, set readyState to LOADING.
  4. Queue a task to dispatch a progress event called loadstart.
  5. Make progress notifications. As the bytes from the blob argument are read, user agents SHOULD ensure that on getting, the result attribute returns partial Blob data representing the number of bytes currently loaded (as a fraction of the total) , as a binary string.
  6. When the blob has been fully read into memory, set readyState to DONE.
  7. Set the result attribute to be blob's data content represented as a binary string; on getting, the result attribute returns the (complete) data of blob as a binary string.
  8. Terminate this overall set of steps.
 Yes
readAsText() When the readAsText(blob, encoding) method is called (the encoding argument is optional), the user agent MUST run the following steps (unless otherwise indicated):
  1. Set readyState to EMPTY and set result to null.
  2. If an error occurs during reading the blob parameter, set readyState to DONE and set result to null. Proceed to the following error steps:
    1. Dispatch a progress event called error. Set the error attribute; on getting, the error attribute MUST be a a FileError object with a valid error code that indicates the kind of file error that has occurred.
    2. Dispatch a progress event called loadend.
    3. Terminate this overall set of steps.
  3. If no error has occurred, set readyState to LOADING.
  4. Queue a task to dispatch a progress event called loadstart.
  5. Make progress notifications. As the bytes from the blob argument are read, user agents SHOULD ensure that on getting, the result attribute returns partial Blob data representing the number of bytes currently loaded (as a fraction of the total) , decoded into memory according to the encoding determination.
  6. When the blob has been fully read into memory, set readyState to DONE.
  7. Set the result attribute to be blob's data content represented as a string in a format determined by the encoding determination; on getting, the result attribute returns the (complete) data of blob as a string, decoded into memory according to the encoding determination.
  8. Terminate this overall set of steps.
 Yes
readAsDataURL() When the readAsDataURL(blob) method is called, the user agent MUST run the following steps (unless otherwise indicated):
  1. Set readyState to EMPTY and set result to null.
  2. If an error occurs during reading of the blob parameter, OR if a user agent's URL length limitations prevent returning data as a Data URL, set readyState to DONE and set result to null. Proceed to the following error steps:
    1. Dispatch a progress event called error. Set the error attribute; on getting, the error attribute MUST be a a FileError object with a valid error code that indicates the kind of file error that has occurred.
    2. Dispatch a progress event called loadend.
    3. Terminate this overall set of steps.
  3. If no error has occurred, set readyState to LOADING.
  4. Queue a task to dispatch a progress event called loadstart.
  5. Make progress notifications.
  6. When the blob has been fully read into memory, set readyState to DONE.
  7. Set the result attribute to be blob's data content represented as a Data URL; on getting, the result attribute returns the (complete) data of blob as a Data URL.
    • Use the blob's type attribute as part of the Data URL if it is available in keeping with the Data URL specification.
    • If the type attribute is not available on the blob return a Data URL without a media type.
    • Note: Data URLs that do not have media types MUST be treated as plain text by conforming user agents.
  8. Terminate this overall set of steps.
 Yes

The result attribute

On getting, the result attribute returns a Blob's data as a DOMString, or as an ArrayBuffer, or null, depending on the read method that has been called on the FileReader, and any errors that may have occurred. It can also return partial Blob data.

Attribute Description Support
result
  • On getting, if the readyState is EMPTY (no read method has been called) then the result attribute MUST return null.
  • On getting, if an error in reading the File or Blob has occurred (using any read method), then the result attribute MUST return null.
  • On getting, if the readAsDataURL read method is used, the result attribute MUST return a DOMString that is a Data URL encoding of the File or Blob's data.
  • On getting, if the readAsBinaryString read method is called (and no error in reading the File or Blob has occurred), then the result attribute MUST return a DOMString representing the File or Blob's data as a binary string, in which every byte is represented by an integer in the range [0..255]. On getting, while processing the readAsBinaryString read method, the result attribute SHOULD return partial Blob data in binary string format as a DOMString that is incremented as more data is read.
  • On getting, if the readAsText read method is called (and no error in reading the File or Blob has occurred), then the result attribute MUST return a string representing the File or Blob's data as a text string, and SHOULD decode the string into memory in the format specified by the encoding determination. On getting, while processing the readAsText read method, this attibute SHOULD return partial Blob data in the format specified by the encoding determination as a DOMString that is incremented as more data is read.
  • On getting, if the readAsArrayBuffer read method is called (and no error in reading the File or Blob has occurred), then the result attribute MUST return an ArrayBuffer object. On getting, while processing the readAsArrayBuffer read method, the result attribute SHOULD return partial Blob data as an ArrayBuffer; at least one ArrayBuffer object is returned till the Blob is fully loaded.
 Yes

The abort() method

Method Description Support
abort When the abort() method is called, the user agent MUST run the following steps:
  1. Set readyState to DONE and result to null.
  2. Terminate any steps while processing a read method.
  3. Dispatch a progress event called abort.
  4. Dispatch a progress event called loadend.
  5. Stop dispatching any further progress events.
 Yes

Blob Parameters

Many methods in this specification take mandatory Blob parameters. The Blob argument is used to call all four asynchronous read methods on FileReader and all four synchronous read methods on FileReaderSync; it is also used to call the createObjectURL method. For the purposes of this specification, it will typically be a reference to a single File in a FileList or a Blob object not obtained from the file system that is in scope of the global object from which the method call was made.

Creating and Revoking a Blob URI

Blob URIs are created and revoked using methods exposed on the URL object, supported by global objects Window (in HTML5) and WorkerGlobalScope (in Web Workers). Opera Presto does not yet support this.

Method Description Support
createObjectURL() Returns a unique Blob URI each time it is called on a valid blob argument, which is a non-null Blob in scope of the global object's URL property from which this static method is called. No
revokeObjectURL() Revokes the Blob URI provided in the string url argument. No

Events

Event name Interface Description Support
loadstart ProgressEvent Dispatched when the read starts. Yes
progress ProgressEvent Dispatched while reading (and decoding) blob, and reporting partial Blob data (progess.loaded/progress.total) Yes
abort ProgressEvent Dispatched when the read has been aborted. For instance, by invoking the abort() method. Yes
error ProgressEvent Dispatched when the read has failed (see errors). Yes
load ProgressEvent Dispatched when the read has successfully completed. Yes
loadend ProgressEvent Dispatched when the request has completed (either in success or failure). Yes

FileReaderSync Interface

This interface provides methods to read files or Blobs into memory, and to access the data of these files or Blobs.

Constructors

Constructor Description Support
FileReaderSync() When the FileReaderSync() constructor is invoked, the user agent MUST return a new FileReaderSync object. In environments where the global object is represented by a WorkerGlobalScope object, the FileReaderSync constructor MUST be available. Yes

Methods

Method Description Support
readAsBinaryString() When the readAsBinaryString(blob) method is called, the following steps MUST be followed:
  1. If an error occurs during reading the blob parameter, throw a FileException with the appropriate error code. Terminate these overall steps.
  2. If no error has occurred, read blob into memory. Return the data contents of blob as a binary string.
 Yes
readAsText() When the readAsText(blob, encoding) method is called (the encoding argument is optional), the following steps MUST be followed:
  1. If an error occurs during reading of the blob parameter, throw a FileException with the appropriate error code. Terminate these overall steps.
  2. If no error has occurred, read blob into memory. Return the data contents of blob using the encoding determination algorithm.
 Yes
readAsDataURL() When the readAsDataURL(blob) method is called, the following steps MUST be followed:
  1. If an error occurs during reading of the blob parameter, throw a FileException with the appropriate error code. Terminate these overall steps.
  2. If no error has occurred, read blob into memory. Return the data contents of blob as a Data URL.
    • Use the blob's type attribute as part of the Data URL if it is available in keeping with the Data URL specification.
    • If the type attribute is not available on the blob, return a Data URL without a media type.
 Yes
readAsArrayBuffer() When the readAsArrayBuffer(blob) method is called, the following steps MUST be followed:
  1. If an error occurs during reading the blob parameter, throw a FileException with the appropriate error code. Terminate these overall steps.
  2. If no error has occurred, read blob into memory. Return the data contents of blob as an ArrayBuffer.
Note: This method is waitng for WebGL support. It is included in Opera Presto, but not functional. 		No

Errors and Exceptions

FileError Interface

This interface is used to report errors asynchronously. The FileReader object's error attribute is a FileError object, and is accessed asynchronously through the onerror event handler when error events are generated. Conforming user agents that make available the FileReader() constructor on their global objects MUST also make available the FileError interface object.

The code attribute MUST return one of the constants of the FileError error, which MUST be the most appropriate code from the following "Error code descriptions" table.

FileException exception

Errors in the synchronous read methods for Web Workers are reported using the FileException exception. Conforming user agents that make available the FileReaderSync() constructor on WorkerGlobalScope MUST also make available the FileException interface object.

The code attribute MUST return one of the constants of the FileException exception, which MUST be the most appropriate code from the following "Error code descriptions" table.

Error code descriptions

Constant Code Situation Support
NOT_FOUND_ERR 1 User agents MUST use this code if the File or Blob resource could not be found at the time the read was processed. Yes
SECURITY_ERR 2 This is a security error code to be used in situations not covered by any other error codes. User agents MAY use this code if:
  • It is determined that certain files are unsafe for access within a Web application.
  • It is determined that too many read calls are being made on File or Blob resources.
  • It is determined that the file has changed on disk since the user selected it.
 Yes
ABORT_ERR 3 User agents MUST use this code if the read operation was aborted, typically with a call to abort(). Yes
NOT_READABLE_ERR 4 User agents MUST use this code if the File or Blob cannot be read, typically due due to permission problems that occur after a reference to a File or Blob has been acquired (e.g. concurrent lock with another application). Yes
ENCODING_ERR 5 User agents MAY use this code if URL length limitations for Data URLs in their implementations place limits on the File or Blob data that can be represented as a Data URL. User agents MUST NOT use this code for the asynchronous readAsText() call and MUST NOT use this code for the synchronous readAsText() call, since encoding is determined by the encoding determination algorithm. Yes

Documentation

Opera Help

Need help? Hit F1 anytime while using Opera to access our online help files, or go here.