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 content 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.

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 == "NotReadableError") {
    // The file could not be read
  }
}

2. Terminology and Algorithms

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 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] .

The term Unix Epoch is used in this specification to refer to the time 00:00:00 UTC on January 1 1970 (or 1970-01-01T00:00:00Z ISO 8601); this is the same time that is conceptually " 0 " in ECMA-262 [ECMA-262] .

3. The Blob Interface and Binary Data

[Exposed=(Window,Worker), Serializable]
interface Blob {
  constructor(optional sequence<BlobPart> blobParts,
              optional BlobPropertyBag options = {});
Blob

  readonly attribute unsigned long long size;
  readonly attribute DOMString type;
object
refers
to
a
byte
sequence,
and
has
a

  // slice Blob into byte-ranged chunks
  Blob slice(optional [Clamp] long long start,            optional [Clamp] long long end,            optional DOMString contentType);
size

  // read from the Blob.
  [NewObject] ReadableStream stream();
  [NewObject] Promise<USVString> text();
  [NewObject] Promise<ArrayBuffer> arrayBuffer();
};

attribute
which
is
the
total
number
of
bytes
in
the
byte
sequence,
and
a

enum EndingType { "transparent", "native" };
dictionary BlobPropertyBag {
  DOMString type = "";
  EndingType endings = "transparent";
};
typedef (BufferSource or Blob or USVString) BlobPart;

A type Blob attribute, which is has an associated [[type]] internal slot, an ASCII-encoded string in lower case representing the media type of the byte sequence.

Each A Blob must have has an associated [[data]] internal snapshot state , which must be initially set to the state of the underlying storage, if any such underlying storage exists. Further normative definition of snapshot state can be found for File s. slot, a blob data description .

The actual storage API serialized was persisted in will need a way of modifying the read algorithms for deserialized blobs. I.e. a Blob that was deserialized from IndexedDB should start throwing in its read steps after clear-site-data clears all IndexedDB data. Somehow let StructuredDeserialize pass along a hook from the storage API to here? <https://github.com/w3c/webappsec-clear-site-data/issues/49>

3.1. Constructors Concepts

If invoked with zero parameters, return The data represented by a new Blob object is described by a blob data description , consisting of 0 bytes, some representation of the data, combined with size a set of algorithms to 0, return the actual data as a series of byte sequences .

A blob data description has an associated size , a number specifying the total number of bytes in the byte sequence represented by the blob.

A blob data description has an associated snapshot state . This is a map that represents the data stored in the blob.

A blob data description has an associated read initialization algorithm . This algorithm takes two arguments: the snapshot state, and with a byte offset. It returns a struct which will be used as input for the read algorithm .

A blob data description has an associated read algorithm . This algorithm takes one argument (the struct returned by the read initialization algorithm ). It returns either a byte sequence or the special end of blob value.

Conceptually a Blob object referring to bytes as its associated byte sequence, with its represents a snapshot of some amount of data, and is frozen in time at the time a size Blob set to the length instance is created. As such for any specific instance of bytes , and its a type Blob set , every invocation of read all bytes should either return the exact same byte sequence , or throw an exception. Additionally the returned byte sequence 's length should be equal to the value of t from blob [[data]] 's size .

Note: This is a non-trivial requirement to implement for user agents, especially when a blob is backed by a file on disk (i.e. was created by the substeps above. create a file backed File object algorithm). User agents can use modification time stamps and other mechanisms to maintain this requirement, but this is left as an implementation detail.

3.1.1. Constructor Parameters Byte Sequence backed blobs

The Blob() snapshot state constructor can be invoked with the parameters below: A for a byte sequence backed blob contains a blobParts "data" member, a byte sequence which takes any number of .

A bytes blob read state is a struct An optional BlobPropertyBag conssting of bytes (a byte sequence which takes these optional members: ).

"transparent" 3.1.2. or Multipart blobs "native" . By default this is set to

Blobs created by the "transparent" Blob . If set to and "native" File , line endings will constructors are made up of multiple parts, where each part could be converted to native in any USVString a blob itself.

The snapshot state for a multipart blob contains a "parts" elements in blobParts member, a list . of blob data descriptions .

A multipart blob read state is a struct consisting of:

parts

A queue of blob data descriptions , representing the not yet read parts of the blob.

offset

A number, representing the byte offset in the remaining blob parts from which to start returning data.

nested blob data

undefined or a blob data description . This is undefined unless otherwise specified.

nested read state

undefined or a struct , representing the read state for a nested read operation. This is undefined unless otherwise specified.

3.1.3. Sliced blobs

Blobs created by the slice() method are also known as sliced blobs.

The snapshot state for a sliced blob contains a "offset" member (a number), a "span" member (a number), and a "source" member (a blob data description ).

A sliced blob read state is a struct consisting of:

source

A blob data description , representing the blob that was sliced.

bytes remaining

A number, representing the remaining number of bytes to be returned.

nested read state

A struct , representing the read state of the nested read operation.

3.2. Constructors

// 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);
var b = new Blob(["foobarbazetcetc" + "birdiebirdieboo"], {type: "text/plain;charset=utf-8"});
var c = new Blob([b, shorts]);
var a = new Blob([b, c, bytes]);
var d = new Blob([buffer, b, c, bytes]);

3.2. 3.3. Attributes

The size or FileReaderSync getter steps are to return this . [[data]] . size .

The type getter steps are to return this . [[type]] .

3.3. 3.4. Methods and Parameters

3.3.1. 3.4.1. The slice() method

// 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");
}

3.3.2. 3.4.2. The stream() method

The stream() method, when invoked, must return the result of calling get stream on the context object .

3.3.3. 3.4.3. The text() method

The text() method, when invoked, must run these steps:

1. Let stream promise be the result of calling get stream on the context object a new Promise .

2. Run the following steps in parallel :

   1. Let reader bytes be the result of getting a reader reading all bytes from stream . this . If that threw an exception, return a new reject promise rejected with that exception. exception and abort.

   2. Let Resolve promise be with the result of reading all bytes running UTF-8 decode from stream with on reader bytes .

3. Return the result of transforming promise by a fulfillment handler that returns the result of running UTF-8 decode on its first argument. .

Note: This is different from the behavior of readAsText() to align better with the behavior of Fetch’s text() . Specifically this method will always use UTF-8 as encoding, while FileReader can use a different encoding depending on the blob’s type and passed in encoding name.

3.3.4. 3.4.4. The arrayBuffer() method

The arrayBuffer() method, when invoked, must run these steps:

1. Let stream promise be the result of calling get stream on the context object a new Promise .

2. Let reader be Run the result of getting a reader from stream . If that threw an exception, return a new promise rejected with that exception. following steps in parallel :

   1. Let promise bytes be the result of reading all bytes from this . If that threw an exception, reject stream promise with reader . that exception and abort.

   2. Return the result of transforming Resolve promise by a fulfillment handler that returns with a new ArrayBuffer whose contents are its first argument. bytes .

3. Return promise .

4. The File Interface

A File object is a Blob object with a name attribute, which is a string; it can be created within the web application via a constructor, or is a reference to a byte sequence from a file from the underlying (OS) file system.

[Exposed=(Window,Worker), Serializable]
interface File : Blob {
  constructor(sequence<BlobPart> fileBits,
              USVString fileName,
              optional FilePropertyBag options = {});
  readonly attribute DOMString name;
  readonly attribute long long lastModified;
};
dictionary FilePropertyBag : BlobPropertyBag {  long long lastModified;
};

If a A File object is a reference to a byte sequence originating from has an associated [[name]] intenral slot, a file on disk, then its snapshot state should be set to the state of the file on disk at the time the string.

A File object is created. has an associated [[lastModified]] internal slot, something.

Note: This is a non-trivial requirement to implement for user agents, and is thus not a must but a should [RFC2119] . User agents should endeavor to have a File object’s snapshot state objects are serializable objects . Their serialization steps , given value , serialized and forStorage , are:

1. Invoke the blob serialization steps set given value , serialized and forStorage .

2. Set serialized .[[Name]] to value . [[name]] .

3. Set serialized .[[LastModified]] to value . [[lastModified]] .

Their deserialization steps , given value and serialized , are:

1. Invoke the blob deserialization steps given value and serialized .

2. Set value . [[name]] to serialized .[[Name]].

3. Set value . [[lastModified]] to serialized .[[LastModified]].

4.1. Concepts

The snapshot state of the underlying storage on disk at the time the for a file backed blob contains a "file" member (a reference is taken. If the to a native file is modified on disk following the time disk), and a reference has been taken, the "last modified" member (a number).

A file blob read state is a struct consisting of a file handle (a not further defined handle to a file that is open for reading), and a offset (a number).

4.1. 4.2. Constructor

4.1.1. 4.3. Constructor Parameters Attributes The File() constructor can be invoked with the parameters below:

The name object is created using a constructor, further normative conditions for this attribute getter steps are found in § 4.1 Constructor to return this . [[name]] .

The File lastModified interface is available on objects that expose an attribute of type FileList ; these objects getter steps are defined in HTML [HTML] to return this . [[lastModified]] . 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. 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 .

var file = document.getElementById("filePicker").files[0];
var date = new Date(file.lastModified);
println("You selected the file " + file.name + " which was modified on " + date.toDateString() + ".");
...
// Generate a file with a specific last modified date
var d = new Date(2013, 12, 5, 16, 23, 45, 600);
var generatedFile = new File(["Rough Draft ...."], "Draft1.txt", {type: "text/plain", lastModified: d})
...

5. The FileList Interface

Note: The FileList interface should be considered "at risk" since the general trend on the Web Platform is to replace such interfaces with the Array platform object in ECMAScript [ECMA-262] . In particular, this means syntax of the sort filelist . item ( 0 ) is at risk; most other programmatic use of FileList is unlikely to be affected by the eventual migration to an Array type.

This interface is a list of File objects.

[Exposed=(Window,Worker), Serializable]
interface FileList {
  );

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

FileList objects are serializable objects . Their serialization steps , given value and serialized , are:

1. Set serialized .[[Files]] to an empty list .

2. For each file in value , append the sub-serialization of file to serialized .[[Files]].

Their deserialization step , given serialized and value , are:

1. For each file of serialized .[[Files]], add the sub-deserialization of file to value .

// 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 , of type unsigned long , readonly

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

5.2. Methods and Parameters

item(index)

must return the index th File object in the FileList . If there is no index th 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 , with 0 representing the first file. Supported property indices are the numbers in the range zero to one less than the number of File objects represented by the FileList object. If there are no such File objects, then there are no supported property indices.

Note: The HTMLInputElement interface 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.

6. Reading Data

6.1. The File Reading Task Source

This specification defines a new generic task source called the file reading task source , which is used for all tasks that are queued in this specification to read byte sequences associated with Blob and File objects. It is to be used for features that trigger in response to asynchronously reading binary data.

6.2. The FileReader API

[Exposed=(Window,Worker)]
interface FileReader: EventTarget {
  constructor();
  // async read methods
  );
  );
  );
  );

  void readAsArrayBuffer(Blob blob);
  void readAsBinaryString(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 DOMException? error;
  // event handler content attributes
  attribute EventHandler onloadstart;
  attribute EventHandler onprogress;
  attribute EventHandler onload;
  attribute EventHandler onabort;
  attribute EventHandler onerror;
  attribute EventHandler onloadend;
};

A FileReader has an associated state , that is "empty" , "loading" , or "done" . It is initially "empty" .

A FileReader has an associated result ( null , a DOMString or an ArrayBuffer ). It is initially null .

A FileReader has an associated error ( null or a DOMException ). It is initially null .

The FileReader() constructor, when invoked, must return a new FileReader object.

The readyState attribute’s getter, when invoked, switches on the context object 's state and runs the associated step:

"empty"

Return EMPTY

"loading"

Return LOADING

"done"

Return DONE

The result attribute’s getter, when invoked, must return the context object 's result .

The error attribute’s getter, when invoked, must return the context object 's error .

6.2.1. Event Handler Content Attributes

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

6.2.2. FileReader States

6.2.3. Reading a File or Blob

The FileReader interface makes available several asynchronous read methods — readAsArrayBuffer() , readAsBinaryString() , readAsText() and readAsDataURL() , which read files into memory.

Note: If multiple concurrent read methods are called on the same FileReader object, user agents throw an InvalidStateError on any of the read methods that occur when readyState = LOADING .

( FileReaderSync makes available several synchronous read methods . Collectively, the sync and async read methods of FileReader and FileReaderSync are referred to as just read methods .)

6.2.3.1. The readAsDataURL() method

The readAsDataURL( blob ) method, when invoked, must initiate a read operation for blob with DataURL .

6.2.3.2. The readAsText() method

The readAsText( blob , encoding ) method, when invoked, must initiate a read operation for blob with Text and encoding .

6.2.3.3. The readAsArrayBuffer()

The readAsArrayBuffer( blob ) method, when invoked, must initiate a read operation for blob with ArrayBuffer .

6.2.3.4. The readAsBinaryString() method

The readAsBinaryString( blob ) method, when invoked, must initiate a read operation for blob with BinaryString .

Note: The use of readAsArrayBuffer() is preferred over readAsBinaryString() , which is provided for backwards compatibility.

6.2.3.5. The abort() method

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

1. If context object 's state is "empty" or if context object 's state is "done" set context object 's result to null and terminate this algorithm .

2. If context object 's state is "loading" set context object 's state to "done" and set context object 's result to null .

3. If there are any tasks from the context object on the file reading task source in an affiliated task queue , then remove those tasks from that task queue.

4. Terminate the algorithm for the read method being processed.

5. Fire a progress event called abort at the context object .

6. If context object 's state is not "loading" , fire a progress event called loadend at the context object .

6.3. Packaging data

6.4. Events

The FileReader object must be the event target for all events in this specification.

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

• The progress event e does not bubble. e.bubbles must be false [DOM]

• The progress event e is NOT cancelable. e.cancelable must be false [DOM]

6.4.1. Event Summary

The following are the events that are fired at FileReader objects.

6.4.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:

1. Once a loadstart has been fired, a corresponding loadend fires at completion of the read, UNLESS any of the following are true:

   • the read method has been cancelled using abort() and a new read method has been invoked

   • the event handler function for a load event initiates a new read

   • the event handler function for a error event initiates a new read.

   Note: The events loadstart and loadend are not coupled in a one-to-one manner.

   This example showcases "read-chaining": initiating another read from within an event handler while the "first" read continues processing.

   // In code of the sort...
   reader.readAsText(file);
   reader.onload = function(){reader.readAsText(alternateFile);}
   .....
   //... the loadend event must not fire for the first read
   reader.readAsText(file);
   reader.abort();
   reader.onabort = function(){reader.readAsText(updatedFile);}
   //... the loadend event must not fire for the first read
   

2. One progress event will fire when blob has been completely read into memory.

3. No progress event fires before loadstart .

4. 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.

5. No abort , load , or error event fires after loadend .

6.5. 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).

6.5.1. The FileReaderSync API

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

[Exposed=(DedicatedWorker,SharedWorker)]
interface FileReaderSync {
  constructor();
  // Synchronously return strings
  );
  );
  );
  );

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

6.5.1.1. Constructors

When the FileReaderSync() constructor is invoked, the user agent must return a new FileReaderSync object.

6.5.1.2. The readAsText()

The readAsText( blob , encoding ) method, when invoked, must run these steps:

1. Let stream be the result of calling get stream on blob .

2. Let reader be the result of getting a reader from stream .

3. Let promise be the result of reading all bytes from stream with reader .

4. Wait for promise to be fulfilled or rejected.

5. If promise fulfilled with a byte sequence bytes :

   1. Return the result of package data given bytes , Text , blob ’s type , and encoding .

6. Throw promise ’s rejection reason.

6.5.1.3. The readAsDataURL() method

The readAsDataURL( blob ) method, when invoked, must run these steps:

1. Let stream be the result of calling get stream on blob .

2. Let reader be the result of getting a reader from stream .

3. Let promise be the result of reading all bytes from stream with reader .

4. Wait for promise to be fulfilled or rejected.

5. If promise fulfilled with a byte sequence bytes :

   1. Return the result of package data given bytes , DataURL , and blob ’s type .

6. Throw promise ’s rejection reason.

6.5.1.4. The readAsArrayBuffer() method

The readAsArrayBuffer( blob ) method, when invoked, must run these steps:

1. Let stream be the result of calling get stream on blob .

2. Let reader be the result of getting a reader from stream .

3. Let promise be the result of reading all bytes from stream with reader .

4. Wait for promise to be fulfilled or rejected.

5. If promise fulfilled with a byte sequence bytes :

   1. Return the result of package data given bytes , ArrayBuffer , and blob ’s type .

6. Throw promise ’s rejection reason.

6.5.1.5. The readAsBinaryString() method

The readAsBinaryString( blob ) method, when invoked, must run these steps:

1. Let stream be the result of calling get stream on blob .

2. Let reader be the result of getting a reader from stream .

3. Let promise be the result of reading all bytes from stream with reader .

4. Wait for promise to be fulfilled or rejected.

5. If promise fulfilled with a byte sequence bytes :

   1. Return the result of package data given bytes , BinaryString , and blob ’s type .

6. Throw promise ’s rejection reason.

Note: The use of readAsArrayBuffer() is preferred over readAsBinaryString() , which is provided for backwards compatibility.

7. Errors and Exceptions

File read errors 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). Additionally, the snapshot state may have changed. 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 § 9 Security and Privacy Considerations and SecurityError .

7.1. Throwing an Exception or Returning an Error

This section is normative.

Error conditions can arise when reading a File or a Blob .

The read operation can terminate due to error conditions when reading a File or a Blob ; the particular error condition that causes the get stream algorithm to fail is called a failure reason . A failure reason is one of NotFound , UnsafeFile , TooManyReads , SnapshotState , or FileLock .

Synchronous read methods throw exceptions of the type in the table below if there has been an error owing to a particular failure reason .

Asynchronous read methods use the error attribute of the FileReader object, which must return a DOMException object of the most appropriate type from the table below if there has been an error owing to a particular failure reason , or otherwise return null.

8. A URL for Blob and MediaSource reference

This section defines a scheme for a URL used to refer to Blob and MediaSource objects.

8.1. Introduction

This section is informative.

Blob (or object) URLs are URLs like blob:http://example.com/550e8400-e29b-41d4-a716-446655440000 . This enables integration of Blob s and MediaSource s with other APIs that are only designed to be used with URLs, such as the img element. Blob URLs can also be used to navigate to as well as to trigger downloads of locally generated data.

For this purpose two static methods are exposed on the URL interface, createObjectURL(obj) and revokeObjectURL(url) . The first method creates a mapping from a URL to a Blob , and the second method revokes said mapping. As long as the mapping exist the Blob can’t be garbage collected, so some care must be taken to revoke the URL as soon as the reference is no longer needed. All URLs are revoked when the global that created the URL itself goes away.

8.2. Model

Each user agent must maintain a blob URL store . A blob URL store is a map where keys are valid URL strings and values are blob URL Entries .

A blob URL entry consists of an object (of type Blob or MediaSource ), and an environment (an environment settings object ).

Keys in the blob URL store (also known as blob URLs ) are valid URL strings that when parsed result in a URL with a scheme equal to " blob ", an empty host , and a path consisting of one element itself also a valid URL string .

8.3. Dereferencing Model for blob URLs

Futher requirements for the parsing and fetching model for blob URLs are defined in the [URL] and [Fetch] specifications.

8.3.1. Origin of blob URLs

This section is informative.

The origin of a blob URL is always the same as that of the environment that created the URL, as long as the URL hasn’t been revoked yet. This is achieved by the [URL] spec looking up the URL in the blob URL store when parsing a URL, and using that entry to return the correct origin.

If the URL was revoked the serialization of the origin will still remain the same as the serialization of the origin of the environment that created the blob URL, but for opaque origins the origin itself might be distinct. This difference isn’t observable though, since a revoked blob URL can’t be resolved/fetched anymore anyway.

8.3.2. Lifetime of blob URLs

This specification extends the unloading document cleanup steps with the following steps:

1. Let environment be the Document 's relevant settings object .

2. Let store be the user agent’s blob URL store ;

3. Remove from store any entries for which the value 's environment is equal to environment .

This needs a similar hook when a worker is unloaded.

8.4. Creating and Revoking a blob URL

Blob URLs are created and revoked using static methods exposed on the URL object. Revocation of a blob URL decouples the blob URL from the resource it refers to, and if it is dereferenced after it is revoked, user agents must act as if a network error has occurred. This section describes a supplemental interface to the URL specification [URL] and presents methods for blob URL creation and revocation.

[Exposed=(Window,DedicatedWorker,SharedWorker)]
partial interface URL {
  );
  );

  static DOMString createObjectURL((Blob or MediaSource) obj);
  static void revokeObjectURL(DOMString url);
};

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

8.4.1. Examples of blob URL Creation and Revocation

Blob URL s are strings that are used to fetch Blob objects, and can persist for as long as the document from which they were minted using URL. createObjectURL() — see § 8.3.2 Lifetime of blob URLs .

This section gives sample usage of creation and revocation of blob URL s with explanations.

url = URL.createObjectURL(blob);
img1.src = url;
img2.src = url;

var blobURLref = URL.createObjectURL(file);
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 throw an exception
  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 URL , and the web developer then revokes the blob URL string after both image objects have been loaded. While not restricting number of uses of the blob URL offers more flexibility, it increases the likelihood of leaks; developers should pair it with a corresponding call to URL. revokeObjectURL() .

9. Security and Privacy 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 URLs . User agents may throw a SecurityError exception for synchronous read methods, or return a SecurityError exception for asynchronous reads.

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

10. 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.

  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.

  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.

  Note: While this specification doesn’t provide an explicit API call to trigger downloads, the HTML5 specification has addressed this. The download attribute of the a element initiates a download, saving a File with the name specified. The combination of this API and the download attribute on a elements allows for the creation of files within web applications, and the ability to save them locally.

  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.

  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.

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, Jonas Sicking and Vsevolod Shmyroff 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