File API

1. Introduction

This section is informative.

Web applications should have the ability to manipulate as wide as possible a range of user input, including files that a user may wish to upload to a remote server or manipulate inside a rich web application. This specification defines the basic representations for files, lists of files, errors raised by access to files, and programmatic ways to read files. Additionally, this specification also defines an interface that represents "raw data" which can be asynchronously processed on the main thread of conforming user agents. The interfaces and API defined in this specification can be used with other interfaces and APIs exposed to the web platform.

The File interface represents file data typically obtained from the underlying file system, and the Blob interface ("Binary Large Object" - a name originally introduced to web APIs in Google Gears) represents immutable raw data. File or Blob reads should happen asynchronously on the main thread, with an optional synchronous API used within threaded web applications. An asynchronous API for reading files prevents blocking and UI "freezing" on a user agent's main thread. This specification defines an asynchronous API based on an event model to read and access a File or Blob's data. A FileReader object provides asynchronous read methods to access that file's data through event handler attributes and the firing of events. The use of events and event handlers allows separate code blocks the ability to monitor the progress of the read (which is particularly useful for remote drives or mounted drives, where file access performance may vary from local drives) and error conditions that may arise during reading of a file. An example will be illustrative.

Example

In the example below, different code blocks handle progress, error, and success conditions.

ECMAScript


function startRead() {  
  // obtain input element through DOM 
  
  var file = document.getElementById('file').files[0];
  if(file){
    getAsText(file);
  }
}

function getAsText(readFile) {
        
  var reader = new FileReader();
  
  // Read file into memory as UTF-16      
  reader.readAsText(readFile, "UTF-16");
  
  // Handle progress, success, and errors
  reader.onprogress = updateProgress;
  reader.onload = loaded;
  reader.onerror = errorHandler;
}

function updateProgress(evt) {
  if (evt.lengthComputable) {
    // evt.loaded and evt.total are ProgressEvent properties
    var loaded = (evt.loaded / evt.total);
    if (loaded < 1) {
      // Increase the prog bar length
      // style.width = (loaded * 200) + "px";
    }
  }
}

function loaded(evt) {  
  // Obtain the read file data    
  var fileString = evt.target.result;
  // Handle UTF-16 file dump
  if(utils.regexp.isChinese(fileString)) {
    //Chinese Characters + Name validation
  }
  else {
    // run other charset test
  }
  // xhr.send(fileString)     
}

function errorHandler(evt) {
  if(evt.target.error.name == "NotReadableErr") {
    // The file could not be read
  }
}

2. Conformance

Everything in this specification is normative except for examples and sections marked as being informative.

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels [RFC2119].

The following conformance classes are defined by this specification:

conforming user agent

A user agent is considered to be a conforming user agent if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification that apply to implementations. This specification uses both the terms "conforming user agent" and "user agent" to refer to this product class.

User agents may implement algorithms in this specifications in any way desired, so long as the end result is indistinguishable from the result that would be obtained from the specification's algorithms.

User agents that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL] as this specification uses that specification and terminology.

3. Dependencies

This specification relies on underlying specifications.

DOM: A conforming user agent must support at least the subset of the functionality defined in DOM4 that this specification relies upon; in particular, it must support EventTarget. [DOM4]
Progress Events: A conforming user agent must support the Progress Events specification. Data access on read operations is enabled via Progress Events.[ProgressEvents]
HTML: A conforming user agent must support at least the subset of the functionality defined in HTML that this specification relies upon; in particular, it must support event loops and event handler attributes. [HTML]
Web IDL: A conforming user agent must also be a conforming implementation of the IDL fragments in this specification, as described in the Web IDL specification. [WebIDL]
Typed Arrays: A conforming user agent must support the Typed Arrays specification [TypedArrays].

Parts of this specification rely on the Web Workers specification; for those parts of this specification, the Web Workers specification is a normative dependency. [Workers]

4. Terminology and Algorithms

The terms and algorithms <fragment>, <scheme>, document, unloading document cleanup steps, event handler attributes, event handler event type, origin, same origin, event loops, task, task source, URL, provide a stable state, queue a task, neuter, UTF-8, and UTF-16 are as defined by the HTML specification [HTML].

When this specification says to terminate an algorithm the user agent must terminate the algorithm after finishing the step it is on. Asynchronous read methods defined in this specification may return before the algorithm in question is terminated, and can be terminated by an abort() call.

The term throw in this specification, as it pertains to exceptions, is used as defined in the DOM4 specification [DOM4].

The algorithms and steps in this specification use the following mathematical operations:

max(a,b) returns the maximum of a and b, and is always performed on integers as they are defined in WebIDL [WebIDL]; in the case of max(6,4) the result is 6. This operation is also defined in ECMAScript [ECMA-262].
min(a,b) returns the minimum of a and b, and is always performed on integers as they are defined in WebIDL [WebIDL]; in the case of min(6,4) the result is 4. This operation is also defined in ECMAScript [ECMA-262].
Mathematical comparisons such as < (less than), ≤ (less than or equal to) and > (greater than) are as in ECMAScript [ECMA-262].

5. The FileList Interface

This interface is a collection [DOM4] of File objects.

IDL


    interface FileList {
      getter File? item(unsigned long index);
      readonly attribute unsigned long length;
    };

Example

Sample usage typically involves DOM access to the <input type="file"> element within a form, and then accessing selected files.

ECMAScript


    // uploadData is a form element
    // fileChooser is input element of type 'file'
    var file = document.forms['uploadData']['fileChooser'].files[0];
    
    // alternative syntax can be
    // var file = document.forms['uploadData']['fileChooser'].files.item(0);
    
    if(file)
    {
      // Perform file ops
    }

5.1. Attributes

length: must return the number of files in the FileList collection. If there are no files in the collection, this attribute must return 0.

5.2. Methods and Parameters

item(index)

must return the indexth File object in the FileList. If there is no indexth File object in the FileList, then this method must return null.

index must be treated by user agents as value for the position of a File object in the FileList collection, with 0 representing the first file in the collection. Supported property indices [WebIDL] are the numbers in the range zero to one less than the number of File objects represented by the collection [DOM4]. If there are no such File objects, then there are no supported property indices [WebIDL].

Note

The HTMLInputElement interface [HTML] has a readonly attribute of type FileList, which is what is being accessed in the above example. Other interfaces with a readonly attribute of type FileList include the DataTransfer interface [HTML].

6. The Blob Interface

This interface represents immutable 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. The File interface inherits from this interface.

IDL


    [Constructor, Constructor((ArrayBufferView or Blob or DOMString)[] blobParts, optional BlobPropertyBag options)] 
    interface Blob {
      
      readonly attribute unsigned long long size;
      readonly attribute DOMString type;
      
      //slice Blob into byte-ranged chunks
      
      Blob slice(optional long long start,
                 optional long long end,
                 optional DOMString contentType);
      void close(); 
    
    };

    enum EndingTypes{"transparent", "native"};

    dictionary BlobPropertyBag {
		
      DOMString type = "";
      EndingTypes endings = "transparent";
	
    };

6.1. Constructors

The Blob() constructor can be invoked with zero, one, or two parameters. When the Blob() constructor is invoked, user agents must run the following steps:

If invoked with zero parameters, return a new Blob object consisting of 0 bytes, with size set to 0, and with type set to the empty string.
Otherwise, the constructor is invoked with a blobParts array. Let a be that array.
Let bytes be an empty sequence of bytes.
Let length be a's length. For 0 ≤ i < length, repeat the following steps:
1. Let element be the ith element of a.
2. If element is a DOMString, run the following substeps:
  1. Let s be the result of converting element to a sequence of Unicode characters [Unicode] using the algorithm for doing so in WebIDL [WebIDL].
  2. If the endings dictionary member of the options argument is set to "native", transform all newlines in s to the default line-ending representation of the underlying host operating system.
  3. Encode s as UTF-8 and append the resulting bytes to bytes.
  Note
  
  The algorithm from WebIDL [WebIDL] replaces unmatched surrogates in an invalid UTF-16 string with U+FFFD replacement characters. Scenarios exist when the Blob constructor may result in some data loss due to lost or scrambled character sequences.
3. If element is an ArrayBufferView [TypedArrays], convert it to a sequence of byteLength bytes from the underlying ArrayBuffer, starting at the byteOffset of the ArrayBufferView [TypedArrays], and append those bytes to bytes.
4. If element is a Blob, append the bytes it represents to bytes. The type of the Blob array element is ignored.
If the type member of the options argument is not the empty string, run the following substeps:
1. Let s be the type dictionary member. If s contains any non-ASCII characters, throw a SyntaxError (per [RFC2616]) and return from this algorithm.
2. Convert every character in s to lower case.
3. Parse s as an RFC2616 media-type, tokenizing it according to the ABNF for media-type [RFC2616] with the ASCII "/" character separating tokens representing the type and subtype productions. If s cannot be tokenized according to the ABNF for media-type [RFC2616], throw a SyntaxError and return from this algorithm.
4. If the type and subtype tokens consist of any CTLs or separators, throw a SyntaxError and return from this algorithm (per [RFC2616]).
Return a Blob object consisting of bytes, with its size set to the length of bytes, and its type set to the type member of the options argument.

6.1.1. Constructor Parameters

The Blob() constructor can be invoked with the parameters below:

A blobParts Array

which takes any number of the following types of array elements, and in any order:

ArrayBufferView [TypedArrays] array elements
Blob array elements
DOMString [WebIDL] array elements

An optional BlobPropertyBag

which takes two members:

type, a DOMString which corresponds to the Blob object's type attribute.

endings, an enum which can take the values "transparent" which is set by default, or "native". A description of both is given in the table below.

Value	Description
transparent	Code points from the string arguments must remain unchanged.
native	Newlines must be transformed to the default line-ending representation of the underlying host operating system. For example, if the underlying OS is Windows, newlines will be transformed into `\r\n` pairs as the text is appended to the newly minted `Blob` object.

Example

Examples of constructor usage follow.

ECMAScript


// Create a new Blob object

var a = new Blob();

// Create a 1024-byte ArrayBuffer
// buffer could also come from reading a File

var buffer = new ArrayBuffer(1024);

// Create ArrayBufferView objects based on buffer

var shorts = new Uint16Array(buffer, 512, 128);
var bytes = new Uint8Array(buffer, shorts.byteOffset + shorts.byteLength);

// b has line endings of type "transparent" by default

var b = new Blob(["foobarbazetcetc", "birdiebirdieboo"], {type: "text/plain;charset=UTF-8"});

// c appends b and shorts and has line endings of type "transparent"

var c = new Blob([b, shorts]);

// a has native endings depending on platform

var a = new Blob([b, c, bytes], {endings: "native"});

6.2. Attributes

size: Returns the size of the Blob object in bytes. On getting, conforming user agents must return the total number of bytes that can be read by a FileReader or FileReaderSync object, or 0 if the Blob has no bytes to be read. If the Blob has been neutered with close called on it, then size must return 0.
type: The ASCII-encoded string in lower case representing the media type of the Blob, expressed as an RFC2046 MIME type [RFC2046]. On getting, conforming user agents must return the MIME type of the Blob, if it is known. If conforming user agents cannot determine the media type of the Blob, they must return the empty string. A string is a valid MIME type if it matches the media-type token defined in section 3.7 "Media Types" of RFC 2616 [RFC2616].

Note

Use of the type attribute informs the encoding determination and parsing the Content-Type header when dereferencing blob: URIs.

6.3. Methods and Parameters

6.3.1. The slice method

The slice method returns a new Blob object with bytes ranging from the optional start parameter upto but not including the optional end parameter, and with a type attribute that is the value of the optional contentType parameter. It must act as follows :

Let O be the Blob object on which the slice method is being called.
The optional start parameter is a value for the start point of a slice call, and must be treated as a byte-order position, with the zeroth position representing the first byte. User agents must process slice with start normalized according to the following:
1. If the optional start parameter is not used as a parameter when making this call, let relativeStart be 0.
2. If start is negative, let relativeStart be max((size + start), 0)).
3. Else, let relativeStart be min(start, size).
4. This defines the normalization of the start parameter. When processing the slice call, user agents must normalize start to relativeStart.
The optional end parameter is a value for the end point of a slice call. The following requirements are normative for this parameter, and user agents must process slice with end normalized according to the following:
1. If the optional end parameter is not used as a parameter when making this call, let relativeEnd be size.
2. If end is negative, let relativeEnd be max((size + end), 0)
3. Else, let relativeEnd be min(end, size)
4. This defines the normalization of the end parameter. When processing the slice call, user agents must normalize end to relativeEnd.
The optional contentType parameter is used to set a value identical to one that is set with the HTTP/1.1 Content-Type header [RFC2616] on the Blob returned by the slice call. The following requirements are normative for this parameter, and user agents must process the slice with contentType normalized according to the following:
1. If the contentType parameter is not provided, let relativeContentType be set to the empty string .
2. Else let relativeContentType be set to contentType and run the following substeps:
  1. If relativeContentType consists of any non-ASCII characters, throw a SyntaxError (per [RFC2616]) and return from this algorithm.
  2. Convert every character in relativeContentType to lower case.
  3. Parse relativeContentType as an RFC2616 media-type, tokenizing it according to the ABNF for media-type [RFC2616] with the ASCII "/" character separating tokens representing the type and subtype productions. If relativeContentType cannot be tokenized according to the ABNF for media-type [RFC2616], throw a SyntaxError and return from this algorithm.
  4. If the type and subtype tokens consist of any CTLs or separators, throw a SyntaxError and return from this algorithm (per [RFC2616]).
3. This defines the normalization of the contentType parameter. When processing the slice call, user agents must normalize contentType to relativeContentType.
Let span be max((relativeEnd - relativeStart), 0).
Return a new Blob object S with the following characteristics:
1. S consists of span consecutive bytes from O, beginning with the byte at byte-order position relativeStart.
2. S.size = span.
3. S.type = relativeContentType.

Example

The examples below illustrate the different types of slice calls possible. Since the File interface inherits from the Blob interface, examples are based on the use of the File interface.

ECMAScript


    // obtain input element through DOM
    
    var file = document.getElementById('file').files[0];
    if(file)
    {
      // create an identical copy of file
      // the two calls below are equivalent
      
      var fileClone = file.slice(); 
      var fileClone2 = file.slice(0, file.size);
      
      // slice file into 1/2 chunk starting at middle of file
      // Note the use of negative number
      
      var fileChunkFromEnd = file.slice(-(Math.round(file.size/2)));
      
      // slice file into 1/2 chunk starting at beginning of file
      
      var fileChunkFromStart = file.slice(0, Math.round(file.size/2));
      
      // slice file from beginning till 150 bytes before end
      
      var fileNoMetadata = file.slice(0, -150, "application/experimental");      
    }

6.3.2. The close method

Calling the close method must permanently neuter the original Blob object. This is an irreversible and non-idempotent operation; once a Blob has been neutered, it cannot be used again; dereferencing a Blob URI bound to a Blob object on which close has been called results in a 500 Error. A neutered Blob must have a size of 0.

Note

Calling close must not affect an ongoing read operation via any asynchronous read methods . Calling close must not affect any Blob objects created by a slice call on the Blob object on which close has been called.

7. The File Interface

This interface describes a single file in a FileList and exposes its name. It inherits from Blob.

IDL


interface File : Blob {

  readonly attribute DOMString name;
  readonly attribute Date? lastModifiedDate;

};

7.1. Attributes

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.
lastModifiedDate: The last modified date of the file. On getting, if user agents can make this information available, this must return a new Date[HTML] object initialized to the last modified date of the file; otherwise, this must return null.

The File interface is available on objects that expose an attribute of type FileList; these objects are defined in HTML [HTML]. The File interface, which inherits from Blob, is immutable, and thus represents file data that can be read into memory at the time a read operation is initiated. For synchronous reads on a Web Worker [Workers], if the file has been modified on disk since the File object reference is created, user agents must throw a NotReadableError; for asynchronous reads, user agents must fire an error event with the error attribute returning a NotReadableError DOMError. User agents must process reads on files that no longer exist at the time of read as errors, throwing a NotFoundError exception if using a FileReaderSync on a Web Worker [Workers] or firing an error event with the error attribute returning a NotFoundError DOMError.

8. The FileReader Interface

This interface provides methods to read File objects or Blob objects into memory, and to access the data from those Files or Blobs using progress events and event handler attributes; it inherits from EventTarget [DOM4]. 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 [HTML]).

IDL



	[Constructor]
	interface FileReader: EventTarget {

	  // async read methods
	  void readAsArrayBuffer(Blob blob);
	  void readAsText(Blob blob, optional DOMString encoding);
	  void readAsDataURL(Blob blob);

	  void abort();

	  // states
	  const unsigned short EMPTY = 0;
	  const unsigned short LOADING = 1;
	  const unsigned short DONE = 2;


	  readonly attribute unsigned short readyState;

	  // File or Blob data
	  readonly attribute (DOMString or ArrayBuffer)? result;

	  readonly attribute DOMError error;

	  // event handler attributes
	  [TreatNonCallableAsNull] attribute Function? onloadstart;
	  [TreatNonCallableAsNull] attribute Function? onprogress;
	  [TreatNonCallableAsNull] attribute Function? onload;
	  [TreatNonCallableAsNull] attribute Function? onabort;
	  [TreatNonCallableAsNull] attribute Function? onerror;
	  [TreatNonCallableAsNull] attribute Function? onloadend;

	};

8.1. The FileReader Task Source

The FileReader interface enables asynchronous reads on individual Blob objects by firing progress events as the read occurs. Unless stated otherwise, the task source that is used in this specification is the FileReader. This task source is used for events that are asynchronously fired, and for event tasks that are queued for firing, and for the read methods, which queue tasks to update the result.

8.2. Constructors

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.

8.3. Event Handler Attributes

The following are the event handler attributes (and their corresponding event handler event types) that user agents must support on FileReader as DOM attributes:

event handler attribute	event handler event type
`onloadstart`	`loadstart`
`onprogress`	`progress`
`onabort`	`abort`
`onerror`	`error`
`onload`	`load`
`onloadend`	`loadend`

8.4. FileReader States

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

EMPTY (numeric value 0): The FileReader object has been constructed, and there are no pending reads. None of the read methods have been called. This is the default state of a newly minted FileReader object, until one of the read methods have been called on it.
LOADING (numeric value 1): A File or Blob is being read. One of the read methods is being processed, and no error has occurred during the read.
DONE (numeric value 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. If readyState is set to DONE it means at least one of the read methods have been called on this FileReader.

8.5. Reading a File or Blob

8.5.1. Multiple Reads

The FileReader interface makes available three asynchronous read methods - readAsArrayBuffer, readAsText, and readAsDataURL, which read files into memory. If multiple concurrent read methods are called on the same FileReader object, user agents must throw an InvalidStateError [DOM4] on any of the read methods that occur when readyState = LOADING.

8.5.2. The `result` attribute

On getting, the result attribute returns a Blob's data as a DOMString, or as an ArrayBuffer [TypedArrays], 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. Partial Blob data is the part of the File or Blob that has been read into memory currently; when processing the read method readAsText, partial Blob data is a DOMString that is incremented as more bytes are loaded (a portion of the total) [ProgressEvents], and when processing readAsArrayBuffer partial Blob data is an ArrayBuffer [TypedArrays] object consisting of the bytes loaded so far (a portion of the total)[ProgressEvents]. The list below is normative for the result attribute and is the conformance criteria for this attribute:

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 [DataURL] encoding of the File or Blob's data.
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. User agents must return at least one such result, with the final result returned at completion of the read. See the caveat about partial Blob data being valid within a giving encoding.
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 [TypedArrays] object. On getting, while processing the readAsArrayBuffer read method, the result attribute should return partial Blob data as an ArrayBuffer [TypedArrays]. User agents must return at least one such result, with the final result returned at completion of the read.

If a read is successful, the result attribute must return a non-null value only after a progress event (see also [ProgressEvents]) has fired, since all the read methods access Blob data asynchronously. Tasks are queued to update the result attribute as Blob data is made available.

8.5.3. The `readAsDataURL(blob)` method

When the readAsDataURL(blob) method is called, the user agent must run the steps below (unless otherwise indicated).

If readyState = LOADING throw an InvalidStateError exception [DOM4] and terminate this algorithm.

Note: The readAsDataURL() method returns due to the algorithm being terminated.
If the blob has been neutered through the close method, throw an InvalidStateError exception [DOM4] and terminate this algorithm.

Note: The readAsDataURL() method returns due to the algorithm being terminated.
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 [DataURL], set readyState to DONE and set result to null. Proceed to the error steps below.
1. Fire a progress event called error. Set the error attribute; on getting, the error attribute must be a a DOMError object that indicates the kind of file error that has occurred.
2. Fire a progress event called loadend.
3. Terminate this algorithm.
  
  Note: The readAsDataURL() method returns due to the algorithm being terminated.
If no error has occurred, set readyState to LOADING
Fire a progress event called loadstart.
Return the readAsDataURL() method, but continue to process the steps in this algorithm.
Fire a progress event called progress at completion of the read.
Queue a task to update the result attribute with the blob as a DataURL [DataURL] after it has been fully read into memory; on getting, the result attribute returns the (complete) data of blob as a Data URL [DataURL].
- Use the blob's type attribute as part of the Data URL if it is available in keeping with the Data URL specification [DataURL] .
- If the type attribute is not available on the blob return a Data URL without a media-type. [DataURL].
  Data URLs that do not have media-types [RFC2046] must be treated as plain text by conforming user agents. [DataURL].
Set readyState to DONE
Fire a progress event called load.
Fire a progress event called loadend.
Terminate this algorithm.

8.5.4. The `readAsText(blob, encoding)` method

When the readAsText(blob, encoding) method is called (the encoding argument is optional), the user agent must run the steps below (unless otherwise indicated).

If readyState = LOADING throw an InvalidStateError [DOM4] and terminate these steps.

Note: The readAsText() method returns due to the algorithm being terminated.
If the blob has been neutered through the close method, throw an InvalidStateError exception [DOM4] and terminate this algorithm.

Note: The readAsText() method returns due to the algorithm being terminated.
If an error occurs during reading the blob parameter, set readyState to DONE and set result to null. Proceed to the error steps below.
1. Fire a progress event called error. Set the error attribute; on getting, the error attribute must be a a DOMError object that indicates the kind of file error that has occurred.
2. Fire a progress event called loadend.
3. Terminate this algorithm.
  
  Note: The readAsText() method returns due to the algorithm being terminated.
If no error has occurred, set readyState to LOADING
Fire a progress event called loadstart.
Return the readAsText() method, but continue to process the steps in this algorithm
Make progress notifications.
While processing the read, as data from the blob becomes available, user agents should queue tasks to update the result with partial Blob data represented as a string in a format determined by the encoding determination until the read is complete, to accompany the firing of progress events. On getting, the result attribute returns partial Blob data representing the number of bytes currently loaded (as a fraction of the total) [ProgressEvents], decoded into memory according to the encoding determination; user agents must return at least one such result while processing this read method. The last returned value is at completion of the read.

Partial Blob data must be returned such that where possible, the bytes read thus far should be valid code points within the encoding; in particular, when executing the encoding determination for Partial Blob data, user agents must NOT return the U+FFFD character for bytes that are invalid within an encoding till the entire codepoint has been read. The following encoding caveat must be followed:

Suppose a file resource is to be read in UTF-8, and in hexadecimal the bytes in this file are E3 83 91 E3 83 91, which is effectively 0x30D1 0x30D1. Suppose the first 5 bytes have been read. The result returned here must be 0x30D1 and have result.length == 1 , and NOT be 0x30D1 0xFFFD with result.length == 2 . Even though the trailing E3 83 is not a valid code point in UTF-8 at the fifth byte, user agents must NOT return a result with such invalid code points replaced with U+FFFD till it can be determined definitively that the codepoint is invalid.
When the blob has been read into memory fully, set readyState to DONE
Terminate this algorithm.

8.5.5. The `readAsArrayBuffer(blob)` method

When the readAsArrayBuffer(blob) method is called, the user agent must run the steps below (unless otherwise indicated).

If readyState = LOADING throw an InvalidStateError exception [DOM4] and terminate these steps.

Note: The readAsArrayBuffer() method returns due to the algorithm being terminated.
If the blob has been neutered through the close method, throw an InvalidStateError exception [DOM4] and terminate this algorithm.

Note: The readAsArrayBuffer() method returns due to the algorithm being terminated.
If an error occurs during reading the blob parameter, set readyState to DONE and set result to null. Proceed to the error steps below.
1. Fire a progress event called error. Set the error attribute; on getting, the error attribute must be a a DOMError that indicates the kind of file error that has occurred.
2. Fire a progress event called loadend.
3. Terminate this algorithm.
  
  Note: The readAsArrayBuffer() method returns due to the algorithm being terminated.
If no error has occurred, set readyState to LOADING
Fire a progress event called loadstart.
Return the readAsArrayBuffer() method, but continue to process the steps in this algorithm.
Make progress notifications.
While processing the read, as data from the blob becomes available, user agents should queue tasks to update the result with partial Blob data as an ArrayBuffer [TypedArrays] object containing the bytes read until the read is complete, to accompany the firing of progress events. On getting, the result attribute returns partial Blob data representing the number of bytes currently loaded (as a fraction of the total) [ProgressEvents], as an ArrayBuffer [TypedArrays] object; user agents must return at least one such ArrayBuffer [TypedArrays] while processing this read method. The last returned value is at completion of the read.
When the blob has been read into memory fully, set readyState to DONE
Terminate this algorithm.

8.5.6. The abort() method

When the abort() method is called, the user agent must run the steps below:

If readyState = EMPTY or if readyState = DONE set result to null and terminate this overall set of steps without doing anything else.
If readyState = LOADING set readyState to DONE and result to null.
If there are any tasks from the object's FileReader task source in one of the task queues, then remove those tasks.
Terminate the algorithm for the read method being processed.
Fire a progress event called abort
Fire a progress event called loadend

8.5.7. Blob Parameters

The three asynchronous read methods, the three synchronous read methods, and createObjectURL take a mandatory Blob parameter. This section defines this parameter.

blob: This is a Blob argument and must 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.

8.5.8. Determining Encoding

When reading blob objects using the readAsText() read method, the following encoding determination steps must be followed:

Let charset be null
If the encoding argument is present, and is the name or alias of a character set used on the Internet [IANACHARSET], let charset be set to the value of the encoding parameter.

If charset is null, then for each of the rows in the following table, starting with the first one and going down, if the first bytes of blob match the bytes given in the first column, then let charset be the encoding given in the cell in the second column of that row. If there is no match then charset remains null.

Bytes in Hexadecimal	Description
FE FF	UTF-16BE BOM
FF FE	UTF-16LE BOM
EF BB BF	UTF-8 BOM

If charset is null, and the blob argument's type attribute is present, and its Charset Parameter [RFC2046] is the name or alias of a character set used on the Internet [IANACHARSET], let charset be set to its Charset Parameter.

Example

If blob has a type attribute of text/plain;charset=UTF-8 then charset is UTF-8.
If charset is null let charset be UTF-8.
Return the result of decoding the blob using charset; on getting, the result attribute of the FileReader object returns a string in charset format. The synchronous readAsText method of the FileReaderSync object returns a string in charset format. Replace bytes or sequences of bytes that are not valid according to the charset with a single U+FFFD character [Unicode]. When processing Partial Blob Data, use the encoding caveat, if applicable.

8.5.9. Events

When this specification says to make progress notifications for a read method, the following steps must be followed:

While the read method is processing, queue a task to fire a progress event called progress at the FileReader object about every 50ms or for every byte read into memory, whichever is least frequent. At least one event called progress must fire before load is fired, and at 100% completion of the read operation; if 100% of blob can be read into memory in less than 50ms, user agents must fire a progress event called progress at completion.

Example

If a given implementation uses buffers of size 65536 bytes to read files, and thus limits reading operations to that size, and a read method is called on a file that is 65537 bytes, then that implementation must fire one progress event for the 65536 first bytes, one progress event for the 65537th byte (which is at completion of read), one load event and one loadend event.
When the data from the blob has been completely read into memory, queue a task to fire a progress event called load at the FileReader object.
When the data from the blob has been completely read into memory, queue a task to fire a progress event called loadend at the FileReader object.

When this specification says to fire a progress event called e (for some ProgressEvent e at a FileReader reader), the following are normative:

The progress event e does not bubble. e.bubbles must be false [DOM4]
The progress event e is NOT cancelable. e.cancelable must be false [DOM4]
The term "fire an event" is defined in DOM Core [DOM4]. Progress Events are defined in Progress Events [ProgressEvents].

8.5.9.1. Event Summary

The following are the events that are fired at FileReader objects; firing events is defined in DOM Core [DOM4].

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

8.5.9.2. Summary of Event Invariants

This section is informative. The following are invariants applicable to event firing for a given asynchronous read method in this specification:

Once a loadstart has been fired, a corresponding loadend fires at completion of the read, EXCEPT if the read method has been cancelled using abort() and a new read method has been invoked.

Note
The events loadstart and loadend are not coupled in a one-to-one manner.
One progress event will fire when blob has been completely read into memory.
No progress event fires before loadstart.
No progress event fires after any one of abort, load, and error have fired. At most one of abort, load, and error fire for a given read.
No abort, load, or error event fires after loadend.

9. Reading on Threads

Web Workers allow for the use of synchronous File or Blob read APIs, since such reads on threads do not block the main thread. This section defines a synchronous API, which can be used within Workers [Web Workers]. Workers can avail of both the asynchronous API (the FileReader object) and the synchronous API (the FileReaderSync object).

9.1. The `FileReaderSync` Interface

This interface provides methods to synchronously read File or Blob objects into memory.

IDL



	[Constructor]
	interface FileReaderSync {

	  // Synchronously return strings

	  ArrayBuffer readAsArrayBuffer(Blob blob); 
	  DOMString readAsText(Blob blob, optional DOMString encoding);
	  DOMString readAsDataURL(Blob blob);
	};

9.1.1. Constructors

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.

9.1.2. The `readAsText` method

When the readAsText(blob, encoding) method is called (the encoding argument is optional), the following steps must be followed:

If an error occurs during reading of the blob parameter, throw the appropriate exception. Terminate these overall steps.
If no error has occurred, read blob into memory. Return the data contents of blob using the encoding determination algorithm.

9.1.3. The `readAsDataURL` method

When the readAsDataURL(blob) method is called, the following steps must be followed:

If an error occurs during reading of the blob parameter, throw the appropriate exception. Terminate these overall steps.
If no error has occurred, read blob into memory. Return the data contents of blob as a Data URL [DataURL]
- Use the blob's type attribute as part of the Data URL if it is available in keeping with the Data URL specification [DataURL] .
- If the type attribute is not available on the blob return a Data URL without a media-type. [DataURL].
  Data URLs that do not have media-types [RFC2046] must be treated as plain text by conforming user agents. [DataURL].

9.1.4. The `readAsArrayBuffer` method

When the readAsArrayBuffer(blob) method is called, the following steps must be followed:

If an error occurs during reading the blob parameter, throw the appropriate exception. Terminate these overall steps.
If no error has occurred, read blob into memory. Return the data contents of blob as an ArrayBuffer [TypedArrays]

10. Errors and Exceptions

Error conditions can occur when reading files from the underlying filesystem. The list below of potential error conditions is informative.

The File or Blob being accessed may not exist at the time one of the asynchronous read methods or synchronous read methods are called. This may be due to it having been moved or deleted after a reference to it was acquired (e.g. concurrent modification with another application). See NotFoundError
A File or Blob may be unreadable. This may be due to permission problems that occur after a reference to a File or Blob has been acquired (e.g. concurrent lock with another application). See NotReadableError
User agents MAY determine that some files are unsafe for use within Web applications. A file may change on disk since the original file selection, thus resulting in an invalid read. Additionally, some file and directory structures may be considered restricted by the underlying filesystem; attempts to read from them may be considered a security violation. See the security considerations. See SecurityError
Files may be too large to return to the data structures of a Web application. An example might be that URL length limitations imposed by user agents on Data URLs may make obtaining large files encoded as Data URLs impossible to return [DataURL]. See EncodingError

10.1. Throwing an Exception or Returning an Error

This section is normative. Error conditions can arise when reading a file.

Synchronous read methods throw exceptions of the type in the table below if there has been an error with reading.

The error attribute of the FileReader object must return a DOMError object [DOM4] of the most appropriate type from the table below if there has been an error, and otherwise returns null.

Type	Description
`NotFoundError`	If the `File` or `Blob` resource could not be found at the time the read was processed, then for asynchronous read methods the `error` attribute must return a "`NotFoundError`" `DOMError` and synchronous read methods must throw a `NotFoundError` exception.
`SecurityError`	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 then for asynchronous read methods the `error` attribute may return a "`SecurityError`" `DOMError` and synchronous read methods may throw a `SecurityError` exception. This is a security error to be used in situations not covered by any other exception type.
`NotReadableError`	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) then for asynchronous read methods the `error` attribute must return a "`NotFoundError`" `DOMError` and synchronous read methods must throw a `NotFoundError` exception.
`EncodingError`	If the `File` or `Blob` cannot be encoded as Base64 for a Data URL [DataURL] owing to URL length limitations in implementations, then for asynchronous read methods the `error` attribute must return a "`EncodingError`" `DOMError`, and synchronous read methods must throw an `EncodingError` exception.

11. A URI for Blob and File reference

This section defines a scheme for a URI used to refer to Blob objects (and File objects).

11.1. Requirements for a New Scheme

This specification defines a scheme with URIs of the sort: blob:550e8400-e29b-41d4-a716-446655440000#aboutABBA. This section provides some requirements and is an informative discussion.

This scheme should be able to be used with web APIs such as XMLHttpRequest [XHR2], and with elements that are designed to be used with HTTP URIs, such as the img element [HTML]. In general, this scheme should be designed to be used wherever URIs can be used on the web.

This scheme should have defined response codes, so that web applications can respond to scenarios where the resource is not found, or raises an error, etc.
This scheme should have an origin policy and a lifetime stipulation, to allow safe access to binary data from web applications.

URIs in this scheme should be used as a references to "in-memory" Blobs, and also be re-used elsewhere on the platform to refer to binary resources (e.g. for video-conferencing [Stream API]). URIs in this scheme are designed for impermanence, since they will be typically used to access "in memory" resources.
Developers should have the ability to revoke URIs in this scheme, so that they no longer refer to Blob objects. This includes scenarios where file references are no longer needed by a program, but also other uses of Blob objects. Consider a scenario where a Blob object can be exported from a drawing program which uses the canvas element and API [HTML]. A snapshot of the drawing can be created by exporting a Blob. This scheme can be used with the img [HTML] element to display the snapshot; if the user deletes the snapshot, any reference to the snapshot in memory via a URI should be invalid, and hence the need to be able to revoke such a URI.

11.2. Discussion of Existing Schemes

This section is an informative discussion of existing schemes that may have been repurposed or reused for the use cases for URIs above, and justification for why a new scheme is considered preferable. These schemes include HTTP [RFC2616], file [RFC1630][RFC1738], and a scheme such as urn:uuid [RFC4122]. One broad consideration in determining what scheme to use is providing something with intuitive appeal to web developers.

HTTP could be repurposed for the use cases mentioned above; it already comes with well-defined request-response semantics that are already used by web applications. But Blob resources are typically "in-memory" resident (e.g. after a file has been read into memory), and are thus unlike "traditional" HTTP resources that are dereferenced via DNS. While some user agents automatically "proxy" the underlying file system on the local machine via an HTTP server (e.g. with URLs of the sort http://localhost), HTTP is not traditionally used with local resources. Moreover, an important use case for these URIs are that they can be revoked with an API call. HTTP URIs have traditionally been used for resources that may be more permanent (and that are certainly not chiefly memory-resident, such as files that a web application can read). Reusing the HTTP scheme might be confusing for web developers owing to well-established practice.
The reuse of file URIs would involve changes to file URI use today, such as adding response codes. While they are used inconsistently in web applications, the structure of the URIs would change, and request-response behavior would have to be superimposed on what already works in a more-or-less ad-hoc manner. Modifying this for the use cases cited above is imprudent, given legacy usage. Additionally, the use cases for a Blob URI scheme call for uses beyond the file system.
A scheme of the sort urn:uuid could be used, though use of this scheme is unprecedented in HTML and JavaScript web applications. The urn:uuid scheme is very generic. URIs in the scheme urn:uuid have the disadvantage of unfamiliarity and inconsistency across the web platform. A new scheme has the advantage of being explicit about what is being referenced. In theory, URIs make no guarantee about what sort of resource is obtained when they are dereferenced; that is left to content labeling and media type. But in practice, the name of the scheme creates an expectation about both the resource and the protocol of the request-response transaction. Choosing a name that clarifies the primary use case - namely, access to memory-resident Blob resources - is a worthwhile compromise, and favors clarity, familiarity, and consistency across the web platform.

11.3. Definition of blob URI Scheme

This section defines a blob: URI scheme using a formal grammar. A blob: URI consists of the blob: scheme and an opaque string, along with an optional fragment identifier. In this specification an opaque string is a unique string which can be heuristically generated upon demand such that the probability that two are alike is small, and which is hard to guess (e.g. the Universally Unique IDentifier (UUID) as defined in [RFC4122] is an opaque string). A fragment identifier is optional, and if used, has a distinct interpretation depending on the media type of the Blob or File resource in question [RFC2046].

This section uses the Augmented Backus-Naur Form (ABNF), defined in [RFC5234]. All blob: URLs must follow this ABNF.

ABNF


	blob = scheme ":" opaqueString [fragIdentifier]

	scheme = "blob"

	; scheme is always "blob"

	; opaqueString tokens must be globally unique
	; opaqueString could be a UUID in its canonical form

11.3.1. The Opaque String

Opaque strings must NOT include any reserved characters from [RFC3986] without percent-encoding them. Opaque strings must be globally unique. Such strings should only use characters in the ranges U+002A to U+002B, U+002D to U+002E, U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E [Unicode], and should be at least 36 characters long. UUID is one potential option available to user agents for use with Blob URIs as opaque strings, and their use is strongly encouraged. UUIDs are defined in [RFC4122]. For an ABNF of UUID, see Appendix A.

11.4. Discussion of Fragment Identifier

The fragment's format, resolution and processing directives depend on the media type [RFC2046] of a potentially retrieved representation, even though such a retrieval is only performed if the blob: URI is dereferenced. For example, in an HTML file [HTML] the fragment identifier could be used to refer to an anchor within the file. If the user agent does not recognize the media type of the resource, OR if a fragment identifer is not meaningful within the resource, it must ignore the fragment identifier. Additionally, user agents must honor additional fragment processing directives given in the relevant media format specifications; in particular, this includes any modifications to the fragment production given in HTML [HTML]. The following section is normative for fragment identifers in general, though it should be noted that affiliated specifications may extend this definition.

ABNF


	fragIdentifier = "#" fragment

	; Fragment Identifiers depend on the media type of the Blob
	; fragment is defined in [RFC3986]
	; fragment processing for HTML is defined in [HTML]

	fragment    = *( pchar / "/" / "?" )

	pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"

	unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"

	pct-encoded   = "%" HEXDIG HEXDIG

	sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
	                 / "*" / "+" / "," / ";" / "="

A valid Blob URI reference could look like: blob:550e8400-e29b-41d4-a716-446655440000#aboutABBA where "#aboutABBA" might be an HTML fragment identifier referring to an element with an id attribute of "aboutABBA".

11.5. Origin of Blob URIs

The origin of a Blob URI must be the origin of the script that called URL.createObjectURL. Blob URIs must only be valid within this origin.

11.6. Lifetime of Blob URIs

This specification defines the following lifetime conditions on Blob URIs:

This specification adds an additional unloading document cleanup step: user agents must revoke any Blob URIs created with URL.createObjectURL from within that document. If these Blob URIs are dereferenced, user agents must respond with 500 Error Condition.
A Blob URI created with URL.createObjectURL using the optional options parameter with autoRevoke set to true must be revoked after the user agent provides a stable state; subsequent attempts to dereference that Blob URI must return a 500 Error Condition.
User agents must ensure that any Blob URIs are revoked after URL.revokeObjectURL is called with that Blob URI as an argument. User agents must respond with a 500 Error Condition if a Blob URI is dereferenced after URL.revokeObjectURL is called on that particular Blob URI.
User agents must ensure that any Blob URIs used to dereference Blob objects that have been neutered with the close method return a 500 Error Condition.

11.7. Dereferencing Model for Blob URIs

User agents must only support requests with GET [RFC2616]. If the Blob has a type attribute, or if the Blob has been created with a slice call which uses a contentType argument, responses to dereferencing the Blob URI must include the Content-Type header from HTTP [RFC2616] with the value of the type attribute or contentType argument. Specifically, responses must only support a subset of responses that are equivalent to the following from HTTP [RFC2616]:

11.7.1. 200 OK

This response [RFC2616] must be used if the request has succeeded, namely the blob: URI has been requested with a GET, satisfies the origin requirement, and satisfies the lifetime requirement. If this response code is used, the user agent must also use a Content-Type header [RFC2616] with a value equal to the Blob object's type attribute. See blob: protocol examples.

11.7.2. 500 Error Condition

This response [RFC2616] must be used if:

Any request method other than GET is used to dereference the URL.
The request violates the origin requirement. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Origin Violation."
The request does not satisfy the lifetime requirement. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Expired URI."
The underlying resource has changed, moved, been deleted or has become invalid. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Invalid Resource."
The permissions surrounding the underlying resource do not permit access. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Access Violation."
A security error has occurred. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Security Violation."

This response may be accompanied by additional messages in the response indicating why the Blob resource could not be served. See blob: protocol examples.

The 500 Error Condition provides a response code, but not a fixed status. User agents MAY leave it as simply "500 Error Condition" or supply additional status information (e.g. "500 Origin Violation"). Implementers are strongly encouraged to provide messages to developers along with the response code.

11.7.3. Request and Response Headers

This section provides sample exchanges between web applications and user agents using the blob: protocol. A request can be triggered using HTML markup of the sort <img src="blob:550e8400-e29b-41d4-a716-446655440000">, after a web application calls URL.createObjectURL on a given blob, which returns blob:550e8400-e29b-41d4-a716-446655440000 to dereference that blob. These examples merely illustrate the protocol; web developers are not likely to interact with all the headers, but the getAllResponseHeaders() method of XMLHttpRequest, if used, will show relevant response headers [XHR2].

Example

Requests could look like this:

HEADERS


	GET 550e8400-e29b-41d4-a716-446655440000

If the blob has an affiliated media type [RFC2046] represented by its type attribute, then the response message should include the Content-Type header from RFC2616 [RFC2616]. See processing media types.

HEADERS


	200 OK
	Content-Type: image/jpeg

	....

If there is a file error or any other kind of error associated with the blob, then a user agent can respond with a 500 Error Condition as the response message. This should also be used if any method other than GET is used to make the request.

HEADERS


	500 Error Condition

	This file cannot be read.

11.7.3.1. Processing Media Types

If a Content-Type header [RFC2616] is provided (e.g. if the blob has an affiliated type attribute), then user agents should obtain and process that media type in a manner consistent with the Media Type Sniffing specification [MIMESNIFF].

11.8. Creating and Revoking a Blob URI

Blob URIs are created and revoked using methods exposed on the URL object, supported by global objects Window [HTML] and WorkerGlobalScope [Web Workers]. Revocation of a Blob URI decouples the Blob URI from the resource it refers to, and if it is dereferenced after it is revoked, user agents must return a 500 response. This section describes a supplemental interface to the URL specification [URL API] and presents methods for Blob URI creation and revocation.

IDL


	partial interface URL {

	    static DOMString createObjectURL(Blob blob, optional objectURLOptions options);
	    static void revokeObjectURL(DOMString url);
	};
	
	dictionary objectURLOptions
	{
		boolean autoRevoke = true;

	};

ECMAScript user agents of this specification must ensure that they do not expose a prototype property on the URL interface object unless the user agent also implements the URL [URL API] specification. In other words, URL.prototype must evaluate to true if the user agent implements the URL [URL API] specification, and must NOT evaluate to true otherwise.

11.8.1. Methods and Parameters

The createObjectURL static method

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.

If this method is called with a Blob argument that is NOT valid, then user agents must return null.
If this method is called with a valid Blob argument, user agents must run the following steps:
1. The optional objectURLOptions dictionary argument called options has a boolean member autoRevoke that defaults to true; if called without using the optional dictionary, or if called with autoRevoke set to true, execute the following sub-steps:
  1. Return a unique Blob URI that can be used to dereference the blob argument, and run the rest of this algorithm asynchronously.
  2. Provide a stable state
  3. Revoke the Blob URI by calling revokeObjectURL on it and terminate this algorithm.
2. If this method is called with the autoRevoke dictionary member set to false, return a unique Blob URI that can be used to dereference the blob argument.
  
  Note
  This Blob URI must persist till a call to revokeObjectURL is made, or till the unloading document cleanup steps are executed.

Example

In the example below, after obtaining a reference to a Blob object (in this case, a user-selected File from the underlying file system), the static method URL.createObjectURL() is called on that Blob object.

ECMAScript


	var file = document.getElementById('file').files[0];
	if(file){
	  blobURLref = window.URL.createObjectURL(file);
	  myimg.src = blobURLref;

	}

The revokeObjectURL static method

Revokes the Blob URI provided in the string url argument.

If the url refers to a Blob that is both valid and in the same origin of the global object's URL property on which this static method was called, user agents must return a 500 response code when the url is dereferenced.
If the url refers to a Blob that is NOT valid OR if the value provided for the url argument is not a Blob URI OR if the url argument refers to a Blob that is NOT in the same origin as the global object's URL property, this method call does nothing. User agents may display a message on the error console.

The url argument to the revokeObjectURL method is a Blob URI string.

Example

In the example below, window1 and window2 are separate, but in the same origin; window2 could be an iframe [HTML] inside window1.

ECMAScript


	myurl = window1.URL.createObjectURL(myblob);
	window2.URL.revokeObjectURL(myurl);

Since window1 and window2 are in the same origin, the URL.revokeObjectURL call ensures that subsequent dereferencing of myurl results in a 500 Error Condition response.

11.9. Examples of Blob URI Creation and Revocation

Blob URIs are strings that dereference Blob objects, and can persist for as long as the document from which they were minted using URL.createObjectURL() - see Lifetime of Blob URIs.

This section gives sample usage of creation and revocation of Blob URIs with explanations.

Example

In the example below, two img elements [HTML] refer to the same Blob URI, which was minted for one-time use only using the boolean key in the optional dictionary argument:

ECMAScript


<script>url = URL.createObjectURL(blob); </script><script> img2.src=url;</script>

In the example above, the assignment in the second script element fails, since autoRevoke is true by default.

In the example below, URL.revokeObjectURL() is explicitly called.

ECMAScript


var blobURLref = URL.createObjectURL(file, {autoRevoke:false});
img1 = new Image();
img2 = new Image();

// Both assignments below work as expected

img1.src = blobURLref;
img2.src = blobURLref;

// ... Following body load
// Check if both images have loaded


if(img1.complete && img2.complete)
{
	// Ensure that subsequent refs return a 500
	
	URL.revokeObjectURL(blobURLref);
}
else {

	msg("Images cannot be previewed!");
	
	// revoke the string-based reference
	
	URL.revokeObjectURL(blobURLref);

}

The example above allows multiple references to a single Blob URI, but revokes the Blob URI string after both image objects have been loaded. While not restricting number of uses of the Blob URI offers more flexibility, it creates the potential for strings that linger after they are useful, especially in web applications where the document may persist for a while. Developers must explicitly set the autoRevoke dictionary member to false in order to enable this usage.

12. Security Considerations

This section is informative.

This specification allows web content to read files from the underlying file system, as well as provides a means for files to be accessed by unique identifiers, and as such is subject to some security considerations. This specification also assumes that the primary user interaction is with the <input type="file"/> element of HTML forms [HTML], and that all files that are being read by FileReader objects have first been selected by the user. Important security considerations include preventing malicious file selection attacks (selection looping), preventing access to system-sensitive files, and guarding against modifications of files on disk after a selection has taken place.

Preventing selection looping. During file selection, a user may be bombarded with the file picker associated with <input type="file"/> (in a "must choose" loop that forces selection before the file picker is dismissed) and a user agent may prevent file access to any selections by making the FileList object returned be of size 0.
System-sensitive files (e.g. files in /usr/bin, password files, and other native operating system executables) typically should not be exposed to web content, and should not be accessed via Blob URIs. User agents may throw a SecurityError exception for synchronous read methods, or return a SecurityError DOMError for asynchronous reads.
Cross-origin requests on Blob URIs occur when a Blob URI is accessed across origins. User agents should ensure that the 500 Error Condition response is used in cross-origin request contexts.

Editorial note

This section is provisional; more security data may supplement this in subsequent drafts.

13. Requirements and Use Cases

This section covers what the requirements are for this API, as well as illustrates some use cases. This version of the API does not satisfy all use cases; subsequent versions may elect to address these.

Once a user has given permission, user agents should provide the ability to read and parse data directly from a local file programmatically.
- Example: A lyrics viewer. User wants to read song lyrics from songs in his plist file. User browses for plist file. File is opened, read, parsed, and presented to the user as a sortable, actionable list within a web application. User can select songs to fetch lyrics. User uses the "browse for file" dialog.
Data should be able to be stored locally so that it is available for later use, which is useful for offline data access for web applications.
- Example: A Calendar App. User's company has a calendar. User wants to sync local events to company calendar, marked as "busy" slots (without leaking personal info). User browses for file and selects it. The text/calendar file is parsed in the browser, allowing the user to merge the files to one calendar view. The user wants to then save the file back to his local calendar file. (using "Save As" ?). The user can also send the integrated calendar file back to the server calendar store asynchronously.
User agents should provide the ability to save a local file programmatically given an amount of data and a file name.
- Example: A Spreadsheet App. User interacts with a form, and generates some input. The form then generates a CSV (Comma Separated Variables) output for the user to import into a spreadsheet, and uses "Save...". The generated output can also be directly integrated into a web-based spreadsheet, and uploaded asynchronously.
User agents should provide a streamlined programmatic ability to send data from a file to a remote server that works more efficiently than form-based uploads today
- Example: A Video/Photo Upload App. User is able to select large files for upload, which can then be "chunk-transfered" to the server.
User agents should provide an API exposed to script that exposes the features above. The user is notified by UI anytime interaction with the file system takes place, giving the user full ability to cancel or abort the transaction. The user is notified of any file selections, and can cancel these. No invocations to these APIs occur silently without user intervention.

14. Appendix A

This section is informative and not normative.

14.1. An ABNF for UUID

The following is an informative ABNF [ABNF] for UUID, which is a strongly encouraged choice for the opaqueString production of Blob URIs.

ABNF


	UUID                   = time-low "-" time-mid "-"
	                         time-high-and-version "-"
	                         clock-seq-and-reserved
	                         clock-seq-low "-" node
	time-low               = 4hexOctet
	time-mid               = 2hexOctet
	time-high-and-version  = 2hexOctet
	clock-seq-and-reserved = hexOctet
	clock-seq-low          = hexOctet
	node                   = 6hexOctet
	hexOctet               = hexDigit hexDigit
	hexDigit =
	         "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" /
	         "a" / "b" / "c" / "d" / "e" / "f" /
	         "A" / "B" / "C" / "D" / "E" / "F"

15. Acknowledgements

This specification was originally developed by the SVG Working Group. Many thanks to Mark Baker and Anne van Kesteren for their feedback.

Thanks to Robin Berjon for editing the original specification.

Special thanks to Olli Pettay, Nikunj Mehta, Garrett Smith, Aaron Boodman, Michael Nordman, Jian Li, Dmitry Titov, Ian Hickson, Darin Fisher, Sam Weinig, Adrian Bateman and Julian Reschke.

Thanks to the W3C WebApps WG, and to participants on the public-webapps@w3.org listserv

16. References

16.1. Normative references

RFC2119: Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF.
HTML: HTML5: A vocabulary and associated APIs for HTML and XHTML (work in progress), I. Hickson. W3C.
ProgressEvents: Progress Events, A. van Kesteren. W3C.
RFC2397: The "data" URL Scheme, L. Masinter. IETF.
Web Workers: Web Workers (work in progress), I. Hickson. W3C.
DOM4: DOM4 (work in progress), A. Gregor, A. van Kesteren, Ms2ger. W3C.
Unicode: The Unicode Standard, Version 5.2.0., J. D. Allen, D. Anderson, et al. Unicode Consortium.
RFC2616: Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee. IETF.
RFC2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Extensions, N. Freed, N. Borenstein. IETF.
IANA Charsets: Official Names for Character Sets on the Internet, K. Simonsen, W.Choi, et al. IANA.
Typed Arrays: Typed Arrays (work in progress), V. Vukicevic, K. Russell. Khronos Group.
RFC5234: Augmented BNF for Syntax Specifications: ABNF, D. Crocker, P. Overell. IETF.
URL API Specification: URL API (work in progress), A. Barth. W3C.
WebIDL Specification: WebIDL (work in progress), C. McCormack.
ECMAScript: ECMAScript 5th Edition, A. Wirfs-Brock, P. Lakshman et al.
MIME Sniffing: MIME Sniffing (work in progress), A. Barth and I. Hickson.

16.2. Informative References

XMLHttpRequest: XMLHttpRequest Level 2 (work in progress), A. van Kesteren. W3C.
Google Gears Blob API: Google Gears Blob API (deprecated)
RFC4122: A Universally Unique IDentifier (UUID) URN Namespace, P. Leach, M. Mealling, R. Salz. IETF.
RFC3986: Uniform Resource Identifier (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter. IETF.
RFC1630: Universal Resource Identifiers in WWW, T. Berners-Lee. IETF.
RFC1738: Uniform Resource Locators (URL), T. Berners-Lee, L. Masinter, M. McCahill. IETF.
Stream API: The Stream API, A. Bergkvist, D. Burnett, C. Jennings, A. Narayanan. W3C.

File API

W3C Working Draft 12 July 2012

Abstract

Status of this Document

Table of Contents

1. Introduction

2. Conformance

3. Dependencies

4. Terminology and Algorithms

5. The FileList Interface

5.1. Attributes

5.2. Methods and Parameters

6. The Blob Interface

6.1. Constructors

6.1.1. Constructor Parameters

6.2. Attributes

6.3. Methods and Parameters

6.3.1. The slice method

6.3.2. The close method

7. The File Interface

7.1. Attributes

8. The FileReader Interface

8.1. The FileReader Task Source

8.2. Constructors

8.3. Event Handler Attributes

8.4. FileReader States

8.5. Reading a File or Blob

8.5.1. Multiple Reads

8.5.2. The result attribute

8.5.3. The readAsDataURL(blob) method

8.5.4. The readAsText(blob, encoding) method

8.5.5. The readAsArrayBuffer(blob) method

8.5.6. The abort() method

8.5.7. Blob Parameters

8.5.8. Determining Encoding

8.5.9. Events

8.5.9.1. Event Summary

8.5.9.2. Summary of Event Invariants

9. Reading on Threads

9.1. The FileReaderSync Interface

9.1.1. Constructors

9.1.2. The readAsText method

9.1.3. The readAsDataURL method

9.1.4. The readAsArrayBuffer method

10. Errors and Exceptions

10.1. Throwing an Exception or Returning an Error

11. A URI for Blob and File reference

11.1. Requirements for a New Scheme

11.2. Discussion of Existing Schemes

11.3. Definition of blob URI Scheme

11.3.1. The Opaque String

11.4. Discussion of Fragment Identifier

11.5. Origin of Blob URIs

11.6. Lifetime of Blob URIs

11.7. Dereferencing Model for Blob URIs

11.7.1. 200 OK

11.7.2. 500 Error Condition

11.7.3. Request and Response Headers

11.7.3.1. Processing Media Types

11.8. Creating and Revoking a Blob URI

11.8.1. Methods and Parameters

11.9. Examples of Blob URI Creation and Revocation

12. Security Considerations

13. Requirements and Use Cases

14. Appendix A

14.1. An ABNF for UUID

15. Acknowledgements

16. References

16.1. Normative references

16.2. Informative References

8.5.2. The `result` attribute

8.5.3. The `readAsDataURL(blob)` method

8.5.4. The `readAsText(blob, encoding)` method

8.5.5. The `readAsArrayBuffer(blob)` method

9.1. The `FileReaderSync` Interface

9.1.2. The `readAsText` method

9.1.3. The `readAsDataURL` method

9.1.4. The `readAsArrayBuffer` method