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
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android14+iOS Safari6+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile11+
[Exposed =(Window ,Worker ),Serializable ]interface {
Blob constructor (optional sequence <BlobPart >,
blobParts optional BlobPropertyBag = {});
options readonly attribute unsigned long long size ;readonly attribute DOMString type ; // slice Blob into byte-ranged chunksBlob slice (optional [Clamp ]long long ,
start optional [Clamp ]long long ,
end optional DOMString ); // read from the Blob. [
contentType NewObject ]ReadableStream stream (); [NewObject ]Promise <USVString >text (); [NewObject ]Promise <ArrayBuffer >arrayBuffer (); };enum {
EndingType ,
"transparent" };
"native" dictionary {
BlobPropertyBag DOMString = "";
type EndingType = "transparent"; };
endings typedef (BufferSource or Blob or USVString );
BlobPart
A Blob
has an associated [[type]] internal slot,
an ASCII-encoded string in lower case representing the media type of the byte sequence.
A Blob
has an associated [[data]] internal slot,
a blob data description.
Blob
objects are serializable objects. Their serialization steps (the blob serialization steps),
given value, serialized and forStorage, are:
-
If forStorage is true:
-
Let bytes be the result of reading all bytes from value.
-
Set serialized.[[BlobData]] to the result of creating blob data from bytes given bytes.
In at least Chrome’s IndexedDB implementation, this copying of the data of blobs is only done when a transaction is committed (and failure to read the blob will cause the commit to fail).
-
-
Otherwise:
-
Set serialized.[[BlobData]] to value.[[data]].
-
-
Set serialized.[[Type]] to value.[[type]].
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>
Blob
blob has an associated get stream algorithm,
which runs these steps:
-
Let stream be the result of constructing a
ReadableStream
object. -
Run the following steps in parallel:
-
Let blob data be blob.[[data]].
-
Let read state be the result of calling blob data’s read initialization algorithm given blob data’s snapshot state and 0. If that threw an exception, error stream with that exception and abort these steps.
-
While true:
-
Let read result be the result of calling blob data’s read algorithm given read state.
-
If that threw an exception (a file read error), error stream with that failure reason and abort these steps.
-
If read result is end of blob, break.
-
Enqueue a
Uint8Array
object wrapping anArrayBuffer
containing read result into stream. If that threw an exception, error stream with that exception and abort these steps.
We need to specify more concretely what reading from a Blob actually does, what possible errors can happen, perhaps something about chunk sizes, etc. <https://github.com/w3c/FileAPI/issues/144>
-
-
-
Return stream.
3.1. Concepts
The data represented by a Blob
is described by a blob data description,
consisting of some representation of the data, combined with a set of algorithms to
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 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.
Blob
blob, run these steps:
-
Let bytes be an empty byte sequence.
-
Let blob data be blob.[[data]].
-
Let read state be the result of calling blob data’s read initialization algorithm given blob data’s snapshot state and 0.
-
While true:
-
Let read result be the result of calling blob data’s read algorithm given read state.
-
If read result is end of blob, break.
-
Append read result to bytes.
-
-
Return bytes.
Conceptually a Blob
represents a snapshot of some amount of data, and
is frozen in time at the time a Blob
instance is created.
As such for any specific instance of a Blob
, 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 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 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. Byte Sequence backed blobs
The snapshot state for a byte sequence backed blob contains a "data"
member, a byte sequence.
-
Let blob data be a new blob data description.
-
Set blob data.snapshot state[
"data"
] to bytes. -
Set blob data.read initialization algorithm to the bytes blob read initialization steps.
-
Set blob data.read algorithm to the bytes blob read steps.
-
Return blob data.
A bytes blob read state is a struct conssting of bytes (a byte sequence).
-
Let read state be a new bytes blob read state.
-
If offset is larger than snapshot state[
"data"
]'s length, set read state.bytes to an empty byte sequence. -
Otherwise, set read state.bytes to a copy of snapshot state[
"data"
] with the first offset bytes removed. -
Return read state.
-
Let result be read state.bytes.
-
Set read state.bytes to an empty byte sequence.
-
If result is empty, return end of blob.
-
Return result.
3.1.2. Multipart blobs
Blobs created by the Blob
and File
constructors are made up of multiple parts,
where each part could be a blob itself.
The snapshot state for a multipart blob contains a "parts"
member,
a list of blob data descriptions.
BlobPart
's blobParts and BlobPropertyBag
options,
run the following steps:
-
Let size be 0.
-
Let parts be an empty list.
-
Let bytes be an empty byte sequence.
-
For each element in blobParts:
-
If element is a
USVString
, run the following substeps:-
Let s be element.
-
If the
endings
member of options is"native"
, set s to the result of converting line endings to native of element. -
Append the result of UTF-8 encoding s 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.
-
-
If element is a
BufferSource
, get a copy of the bytes held by the buffer source, and append those bytes to bytes. -
If element is a
Blob
:-
If bytes is not empty:
-
Let part be the result of creating blob data from bytes given bytes.
-
Append part to parts.
-
Set size to size + part.size.
-
Set bytes to an empty byte sequence.
-
-
Let part be element.[[data]].
-
Append part to parts.
-
Set size to size + part.size.
Note: The
type
of theBlob
array element is ignored and will not affecttype
of returnedBlob
object. -
-
-
If bytes is not empty:
-
Let part be the result of creating blob data from bytes given bytes.
-
Append part to parts.
-
Set size to size + part.size.
-
-
Let result be a blob data description.
-
Set result.size to size.
-
Set result.snapshot state[
"parts"
] to parts. -
Set result.read initialization algorithm to the multipart blob read initialization steps.
-
Set result.read algorithm to the multipart blob read steps.
-
Return result.
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 isundefined
unless otherwise specified. - nested read state
-
undefined
or a struct, representing the read state for a nested read operation. This isundefined
unless otherwise specified.
-
Let read state be a new multipart blob read state.
-
Set read state.offset to offset.
-
Return read state.
-
Let result be end of blob.
-
While result is end of blob:
-
If read state.nested read state is not
undefined
:-
Set result to the result of calling read state.nested blob data's read algorithm given read state.nested read state.
-
If result is end of blob:
-
Set read state.nested read state to
undefined
. -
Set read state.nested blob data to
undefined
.
-
-
Otherwise:
-
If read state.parts is empty:
-
Return end of blob.
-
-
Let current part be the result of dequeueing from read state.parts.
-
Set read state.nested blob data to current part.
-
Set read state.nested read state to the result of calling current part’s read initialization algorithm given current part’s snapshot state and read state.offset.
-
Set read state.offset to 0.
-
-
-
Return result.
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.
-
Let read state be a new sliced blob read state.
-
Set read state.bytes remaining to snapshot state[
"span"
] - offset. -
Let read offset be snapshot state[
"offset"
] + offset. -
Set read state.nested read state to the result of calling read state.source's read initialization algorithm given read state.source's snapshot state and read offset.
-
Return read state.
-
If read state.bytes remaining <= 0:
-
Return end of blob.
-
-
Let result be the result of calling read state.source's read algorithm given read state.nested read state.
-
If result is not end of blob:
-
If result’s length is larger than read state.bytes remaining:
-
Truncate result to be read state.bytes remaining bytes long.
-
-
Set read state.bytes remaining to read state.bytes remaining - result’s length.
-
-
Return result.
3.2. Constructors
In all current engines.
Opera12+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android14+iOS Safari8+Chrome for Android25+Android WebView37+Samsung Internet1.5+Opera Mobile12+
new Blob(blobParts, options)
constructor steps are:
-
Let blob data be the result of processing blob parts given blobParts and options.
-
Let type be an empty string.
-
If the
type
member of theoptions
argument is not the empty string, run the following sub-steps:-
Let type be the
type
dictionary member. If type contains any characters outside the range U+0020 to U+007E, then set type to the empty string and return from these substeps. -
Convert every character in type to ASCII lowercase.
-
-
Let native line ending be be the code point U+000A LF.
-
If the underlying platform’s conventions are to represent newlines as a carriage return and line feed sequence, set native line ending to the code point U+000D CR followed by the code point U+000A LF.
-
Set result to the empty string.
-
Let position be a position variable for s, initially pointing at the start of s.
-
Let token be the result of collecting a sequence of code points that are not equal to U+000A LF or U+000D CR from s given position.
-
Append token to result.
-
While position is not past the end of s:
-
If the code point at position within s equals U+000D CR:
-
Append native line ending to result.
-
Advance position by 1.
-
If position is not past the end of s and the code point at position within s equals U+000A LF advance position by 1.
-
-
Otherwise if the code point at position within s equals U+000A LF, advance position by 1 and append native line ending to result.
-
Let token be the result of collecting a sequence of code points that are not equal to U+000A LF or U+000D CR from s given position.
-
Append token to result.
-
-
Return result.
// 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.3. Attributes
- blob .
size
-
Returns the size of the byte sequence represented by blob in number of bytes.
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for AndroidNoneiOS SafariNoneChrome for Android18+Android WebViewNoneSamsung Internet1.0+Opera MobileNone
The size
getter steps are to return this.[[data]].size.
- blob .
type
-
The ASCII-encoded string in lower case representing the media type of the
Blob
, or an empty string if the type cannot be determined.The
type
attribute can be set by the web application itself through constructor invocation and through theslice()
call;Note: The type of a
Blob
is considered a parsable MIME type, if performing the parse a MIME type algorithm to a byte sequence converted from the ASCII-encoded string representing the Blob object’s type does not return failure.Note: Use of the
type
attribute informs the package data algorithm and determines theContent-Type
header when fetching blob URLs.
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for AndroidNoneiOS SafariNoneChrome for Android18+Android WebViewNoneSamsung Internet1.0+Opera MobileNone
In all current engines.
Opera16+Edge79+
Edge (Legacy)12+IE10+
Firefox for AndroidNoneiOS Safari7+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileNone
The type
getter steps are to return this.[[type]].
3.4. Methods and Parameters
3.4.1. The slice()
method
- slice = blob .
slice
( start, end, contentType ) -
slice is a new
Blob
object, sharing storage with blob, with bytes ranging from the optional start parameter up to but not including the optional end parameter, and with atype
attribute that is the value of the optional contentType parameter.Negative values for start and end are interpreted as relative to the end of the blob.
In all current engines.
Opera12+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android14+iOS SafariYesChrome for Android25+Android WebViewYesSamsung Internet1.5+Opera MobileYes
slice(start, end, contentType)
method steps are:
-
Let relativeStart be 0.
-
If start is not
undefined
: -
If end is not
undefined
: -
Let span be
max((relativeEnd - relativeStart), 0)
. -
Let relativeContentType be an empty string.
-
If contentType is not
undefined
:-
If contentType does not contain any characters outside the range of U+0x0020 to U+0x007E:
-
Set relativeContentType to ASCII lowercase of contentType.
-
-
-
Let snapshot state be a new map.
-
Set snapshot state[
"offset"
] to relativeStart. -
Set snapshot state[
"span"
] to span. -
Let result be a new
Blob
object. -
Set result.[[type]] to relativeContentType.
-
Set result.[[data]].snapshot state to snapshot state.
-
Set result.[[data]].read initialization algorithm to the sliced blob read initialization steps.
-
Set result.[[data]].read algorithm to the sliced blob read steps.
-
Return result.
slice()
calls possible. Since the File
interface inherits from the Blob
interface, examples are based on the use of the File
interface.
// 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.4.2. The stream()
method
OperaNoneEdge79+
Edge (Legacy)NoneIENone
Firefox for AndroidNoneiOS SafariNoneChrome for Android76+Android WebView76+Samsung Internet12.0+Opera Mobile54+
The stream()
method, when invoked, must return
the result of calling get stream on the context object.
3.4.3. The text()
method
OperaNoneEdge79+
Edge (Legacy)NoneIENone
Firefox for AndroidNoneiOS SafariNoneChrome for Android76+Android WebView76+Samsung Internet12.0+Opera Mobile54+
The text()
method, when invoked, must run these steps:
-
Let promise be a new Promise.
-
Run the following steps in parallel:
-
Let bytes be the result of reading all bytes from this. If that threw an exception, reject promise with that exception and abort.
-
Resolve promise with the result of running UTF-8 decode on bytes.
-
-
Return promise.
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.4.4. The arrayBuffer()
method
OperaNoneEdge79+
Edge (Legacy)NoneIENone
Firefox for AndroidNoneiOS SafariNoneChrome for Android76+Android WebView76+Samsung Internet12.0+Opera Mobile54+
The arrayBuffer()
method, when invoked, must run these steps:
-
Let promise be a new Promise.
-
Run the following steps in parallel:
-
Let bytes be the result of reading all bytes from this. If that threw an exception, reject promise with that exception and abort.
-
Resolve promise with a new
ArrayBuffer
whose contents are bytes.
-
-
Return promise.
4. The File Interface
In all current engines.
Opera11.5+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android7+iOS Safari3+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile11.5+
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
A File
has an associated [[name]] intenral slot, a string.
A File
has an associated [[lastModified]] internal slot, something.
File
objects are serializable objects. Their serialization steps,
given value, serialized and forStorage, are:
-
Invoke the blob serialization steps given value, serialized and forStorage.
-
Set serialized.[[Name]] to value.[[name]].
-
Set serialized.[[LastModified]] to value.[[lastModified]].
Their deserialization steps, given value and serialized, are:
-
Invoke the blob deserialization steps given value and serialized.
-
Set value.[[name]] to serialized.[[Name]].
-
Set value.[[lastModified]] to serialized.[[LastModified]].
4.1. Concepts
The snapshot state for a file backed blob contains
a "file"
member (a reference to a native file on disk),
and a "last modified"
member (a number).
File
object for a given native file,
run these steps:
-
Let snapshot state be an empty map.
-
Set snapshot state[
"file"
] to native file. -
Let last modified be the last time native file was modified, as the number of milliseconds since the Unix Epoch. If this can’t be determined, set last modified to the current date and time represented as the number of milliseconds since the Unix Epoch.
-
Set snapshot state[
"last modified"
] to last modified. -
Let name be the file name of native file, converted to a string in a user agent defined manner.
-
Let content type be the mime type of native file (as a lowercase ASCII string), derived from name in a user agent defined manner, or an empty string if no type could be determined, taking into account the following file type guidelines:
-
User agents must return the
type
as an ASCII-encoded string in lower case, such that when it is converted to a corresponding byte sequence, it is a parsable MIME type, or the empty string – 0 bytes – if the type cannot be determined. -
When the file is of type
text/plain
user agents must NOT append a charset parameter to the dictionary of parameters portion of the media type [MIMESNIFF]. -
User agents must not attempt heuristic determination of encoding, including statistical methods.
-
-
Let result be a new
File
object. -
Set result.[[type]] to content type.
-
Set result.[[data]].snapshot state to snapshot state.
-
Set result.[[data]].read initialization algorithm to the file read initialization steps.
-
Set result.[[data]].read algorithm to the file read steps.
-
Set result.[[name]] to name.
-
Set result.[[lastModified]] to last modified.
-
Return result.
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).
-
Let file be snapshot state[
"file"
]. -
If the file referred to file no longer exists, throw a
NotFoundError
. -
Let last modified be the last time file was modified, as the number of milliseconds since the Unix Epoch.
-
If last modified is different from snapshot state[
"last modified"
], throw aNotReadableError
. -
User agents may attempt to detect in other ways that the file on disk has been changed. If this is the case, throw a
NotReadableError
. -
If the user agent for some other reason decides that the file should not be read by a website, throw a
SecurityError
. -
Let read state be a new file blob read state.
-
Set read state.file handle to the result of opening file for reading. If this fails, for example due to permission problems, throw a
NotReadableError
. -
Set read state.offset to offset.
-
Return read state.
-
Let bytes be the result of reading bytes from read state.file handle at read state.offset.
-
If reading bytes failed other than by reaching the end of the file, throw a
NotReadableError
. -
If reading bytes failed becaus the end of the file was reached, return end of blob.
-
Set read state.offset to read state.offset + bytes’s length.
-
Return bytes.
4.2. Constructor
new File(fileBits, fileName, options)
constructor steps are:
-
Run the
Blob
(fileBits, options) constructor steps. -
Let n be a new string of the same size as fileName.
-
Copy every character from fileName to n, replacing any "/" character (U+002F SOLIDUS) with a ":" (U+003A COLON).
Note: Underlying OS filesystems use differing conventions for file name; with constructed files, mandating UTF-16 lessens ambiquity when file names are converted to byte sequences.
-
If options.
lastModified
member is provided:-
Let d be options.
lastModified
dictionary member.
-
-
Otherwise:
-
Let d be the current date and time represented as the number of milliseconds since the Unix Epoch (which is the equivalent of
Date.now()
[ECMA-262]).Note: Since ECMA-262
Date
objects convert tolong long
values representing the number of milliseconds since the Unix Epoch, thelastModified
member could be aDate
object [ECMA-262].
-
-
Set this.[[lastModified]] to d.
4.3. Attributes
In all current engines.
Opera16+Edge79+
Edge (Legacy)18IENone
Firefox for AndroidNoneiOS Safari10+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileNone
In all current engines.
Opera16+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android4+iOS Safari7+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileNone
- file .
name
-
Returns the name of the file as a string. There are numerous file name variations and conventions used by different underlying OS file systems; this is merely the name of the file, without path information. On getting, if user agents cannot make this information available, they return the empty string.
The name
getter steps are to return this.[[name]].
- file .
lastModified
-
Return a the time the file was last modified as the number of milliseconds since the Unix Epoch. If the last modification date and time are not known, the attribute returns the current date and time (equivalent to
Date
[ECMA-262]).. now()
The lastModified
getter steps are to return this.[[lastModified]].
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
In all current engines.
Opera11.1+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android4+iOS Safari3+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile11.1+
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
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:
-
Set serialized.[[Files]] to an empty list.
-
For each file in value, append the sub-serialization of file to serialized.[[Files]].
Their deserialization step, given serialized and value, are:
-
For each file of serialized.[[Files]], add the sub-deserialization of file to value.
<input type="file">
element within a form,
and then accessing selected files.
// 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 indexth
File
object in theFileList
. If there is no indexthFile
object in theFileList
, then this method must returnnull
.index
must be treated by user agents as value for the position of aFile
object in theFileList
, with 0 representing the first file. Supported property indices are the numbers in the range zero to one less than the number ofFile
objects represented by theFileList
object. If there are no suchFile
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
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android32+iOS Safari6+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile11+
[Exposed =(Window ,Worker )]interface :
FileReader EventTarget {constructor (); // async read methodsvoid readAsArrayBuffer (Blob );
blob void readAsBinaryString (Blob );
blob void readAsText (Blob ,
blob optional DOMString );
encoding void readAsDataURL (Blob );
blob void abort (); // statesconst unsigned short = 0;
EMPTY const unsigned short = 1;
LOADING const unsigned short = 2;
DONE readonly attribute unsigned short readyState ; // File or Blob datareadonly attribute (DOMString or ArrayBuffer )?result ;readonly attribute DOMException ?error ; // event handler content attributesattribute 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.
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android32+iOS Safari6.1+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera Mobile11+
The readyState
attribute’s getter,
when invoked, switches on the context object's state and runs the associated step:
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android32+iOS Safari6.1+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera Mobile11+
The result
attribute’s getter,
when invoked, must return the context object's result.
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android32+iOS Safari6.1+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera Mobile11+
The error
attribute’s getter,
when invoked, must return the context object's error.
FileReader
fr has an associated read operation algorithm,
which given blob, a type and an optional encodingName,
runs the following steps:
-
If fr’s state is
"loading"
, throw anInvalidStateError
DOMException
. -
Set fr’s state to
"loading"
. -
Set fr’s result to
null
. -
Set fr’s error to
null
. -
Let stream be the result of calling get stream on blob.
-
Let reader be the result of getting a reader from stream.
-
Let bytes by an empty byte sequence.
-
Let chunkPromise be the result of reading a chunk from stream with reader.
-
Let isFirstChunk be true.
-
In parallel, while true:
-
Wait for chunkPromise to be fulfilled or rejected.
-
If chunkPromise is fulfilled, and isFirstChunk is true, queue a task to fire a progress event called
loadstart
at fr.We might change
loadstart
to be dispatched synchronously, to align with XMLHttpRequest behavior. <https://github.com/w3c/FileAPI/issues/119> -
Set isFirstChunk to false.
-
If chunkPromise is fulfilled with an object whose
done
property is false and whosevalue
property is aUint8Array
object, run these steps:-
Let bs be the byte sequence represented by the
Uint8Array
object. -
Append bs to bytes.
-
If roughly 50ms have passed since these steps were last invoked, queue a task to fire a progress event called
progress
at fr. -
Set chunkPromise to the result of reading a chunk from stream with reader.
-
-
Otherwise, if chunkPromise is fulfilled with an object whose
done
property is true, queue a task to run the following steps and abort this algorithm:-
Set fr’s state to
"done"
. -
Let result be the result of package data given bytes, type, blob’s
type
, and encodingName. -
If package data threw an exception error:
-
Set fr’s error to error.
-
Fire a progress event called
error
at fr.
-
-
Else:
-
Set fr’s result to result.
-
Fire a progress event called
load
at the fr.
-
-
If fr’s state is not
"loading"
, fire a progress event calledloadend
at the fr.Note: Event handler for the
load
orerror
events could have started another load, if that happens theloadend
event for this load is not fired.
-
-
Otherwise, if chunkPromise is rejected with an error error, queue a task to run the following steps and abort this algorithm:
-
Set fr’s state to
"done"
. -
Set fr’s error to error.
-
Fire a progress event called
error
at fr. -
If fr’s state is not
"loading"
, fire a progress event calledloadend
at fr.Note: Event handler for the
error
event could have started another load, if that happens theloadend
event for this load is not fired.
-
-
Use the file reading task source for all these tasks.
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:
event handler content attribute | event handler event type |
---|---|
onloadstart
| loadstart
|
onprogress
| progress
|
onabort
| abort
|
onerror
| error
|
onload
| load
|
onloadend
| loadend
|
6.2.2. FileReader States
FileReader
object can be in one of 3 states.
The readyState
attribute tells you in which state the object is:
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 mintedFileReader
object, until one of the read methods have been called on it. LOADING
(numeric value 1)-
A
File
orBlob
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
orBlob
has been read into memory, OR a file read error occurred, OR the read was aborted usingabort()
. TheFileReader
is no longer reading aFile
orBlob
. IfreadyState
is set toDONE
it means at least one of the read methods have been called on thisFileReader
.
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
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android32+iOS Safari6+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile11+
The readAsDataURL(blob)
method,
when invoked, must initiate a read operation for blob with DataURL.
6.2.3.2. The readAsText()
method
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android32+iOS Safari6+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile11+
The readAsText(blob, encoding)
method,
when invoked, must initiate a read operation for blob with Text and encoding.
6.2.3.3. The readAsArrayBuffer()
In all current engines.
Opera12+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android32+iOS Safari6+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile12+
The readAsArrayBuffer(blob)
method,
when invoked, must initiate a read operation for blob with ArrayBuffer.
6.2.3.4. The readAsBinaryString()
method
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IENone
Firefox for Android32+iOS Safari6+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile11+
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
In all current engines.
Opera11+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android32+iOS Safari6+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera Mobile11+
When the abort()
method is called,
the user agent must run the steps below:
-
If context object's state is
"empty"
or if context object's state is"done"
set context object's result tonull
and terminate this algorithm. -
If context object's state is
"loading"
set context object's state to"done"
and set context object's result tonull
. -
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.
-
Terminate the algorithm for the read method being processed.
-
Fire a progress event called
abort
at the context object. -
If context object's state is not
"loading"
, fire a progress event calledloadend
at the context object.
6.3. Packaging data
Blob
has an associated package data algorithm,
given bytes, a type, a optional mimeType, and a optional encodingName,
which switches on type and runs the associated steps:
- DataURL
-
Return bytes as a DataURL [RFC2397] subject to the considerations below:
-
Use mimeType as part of the Data URL if it is available in keeping with the Data URL specification [RFC2397].
-
If mimeType is not available return a Data URL without a media-type. [RFC2397].
Better specify how the DataURL is generated. <https://github.com/w3c/FileAPI/issues/104>
-
- Text
-
-
Let encoding be failure.
-
If the encodingName is present, set encoding to the result of getting an encoding from encodingName.
-
If encoding is failure, and mimeType is present:
-
Let type be the result of parse a MIME type given mimeType.
-
If type is not failure, set encoding to the result of getting an encoding from type’s parameters[
"charset"
].Ifblob
has atype
attribute oftext/plain;charset=utf-8
then getting an encoding is run using"utf-8"
as the label. Note that user agents must parse and extract the portion of the Charset Parameter that constitutes a label of an encoding.
-
-
If encoding is failure, then set encoding to UTF-8.
-
Decode bytes using fallback encoding encoding, and return the result.
-
- ArrayBuffer
-
Return a new
ArrayBuffer
whose contents are bytes. - BinaryString
-
Return bytes as a binary string, in which every byte is represented by a code unit of equal value [0..255].
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.
Event name | Interface | Fired when… |
---|---|---|
In all current engines.
Firefox79+SafariYesChromeYes
OperaYesEdgeYes Edge (Legacy)12+IEYes Firefox for Android79+iOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes loadstart
| ProgressEvent
| When the read starts. |
In all current engines.
FirefoxYesSafariYesChromeYes
OperaYesEdgeYes Edge (Legacy)12+IEYes Firefox for AndroidYesiOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes progress
| ProgressEvent
| While reading (and decoding) blob
|
In all current engines.
FirefoxYesSafariYesChromeYes
OperaYesEdgeYes Edge (Legacy)12+IEYes Firefox for AndroidYesiOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes abort
| ProgressEvent
| When the read has been aborted.
For instance, by invoking the abort() method.
|
In all current engines.
FirefoxYesSafariYesChromeYes
OperaYesEdgeYes Edge (Legacy)12+IEYes Firefox for AndroidYesiOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes error
| ProgressEvent
| When the read has failed (see file read errors). |
In all current engines.
FirefoxYesSafariYesChromeYes
OperaYesEdgeYes Edge (Legacy)12+IEYes Firefox for AndroidYesiOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes load
| ProgressEvent
| When the read has successfully completed. |
In all current engines.
FirefoxYesSafariYesChromeYes
OperaYesEdgeYes Edge (Legacy)12+IEYes Firefox for AndroidYesiOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes loadend
| ProgressEvent
| When the request has completed (either in success or failure). |
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:
-
Once a
loadstart
has been fired, a correspondingloadend
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
andloadend
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 -
-
One
progress
event will fire whenblob
has been completely read into memory. -
No
progress
event fires after any one ofabort
,load
, anderror
have fired. At most one ofabort
,load
, anderror
fire for a given read.
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
OperaYesEdgeYes
Edge (Legacy)12+IEYes
Firefox for Android8+iOS Safari6–7Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes
This interface provides methods to synchronously read File
or Blob
objects into memory.
[Exposed =(DedicatedWorker ,SharedWorker )]interface {
FileReaderSync (); // Synchronously return strings
constructor 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()
OperaYesEdgeYes
Edge (Legacy)12+IEYes
Firefox for Android8+iOS Safari6–7Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes
The readAsText(blob, encoding)
method,
when invoked, must run these steps:
-
Let stream be the result of calling get stream on blob.
-
Let reader be the result of getting a reader from stream.
-
Let promise be the result of reading all bytes from stream with reader.
-
Wait for promise to be fulfilled or rejected.
-
If promise fulfilled with a byte sequence bytes:
-
Return the result of package data given bytes, Text, blob’s
type
, and encoding.
-
-
Throw promise’s rejection reason.
6.5.1.3. The readAsDataURL()
method
OperaYesEdgeYes
Edge (Legacy)12+IEYes
Firefox for Android8+iOS Safari6–7Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes
The readAsDataURL(blob)
method,
when invoked, must run these steps:
-
Let stream be the result of calling get stream on blob.
-
Let reader be the result of getting a reader from stream.
-
Let promise be the result of reading all bytes from stream with reader.
-
Wait for promise to be fulfilled or rejected.
-
If promise fulfilled with a byte sequence bytes:
-
Return the result of package data given bytes, DataURL, and blob’s
type
.
-
-
Throw promise’s rejection reason.
6.5.1.4. The readAsArrayBuffer()
method
FileReaderSync/readAsArrayBuffer
OperaYesEdgeYes
Edge (Legacy)12+IEYes
Firefox for Android8+iOS Safari6–7Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes
The readAsArrayBuffer(blob)
method,
when invoked, must run these steps:
-
Let stream be the result of calling get stream on blob.
-
Let reader be the result of getting a reader from stream.
-
Let promise be the result of reading all bytes from stream with reader.
-
Wait for promise to be fulfilled or rejected.
-
If promise fulfilled with a byte sequence bytes:
-
Return the result of package data given bytes, ArrayBuffer, and blob’s
type
.
-
-
Throw promise’s rejection reason.
6.5.1.5. The readAsBinaryString()
method
FileReaderSync/readAsBinaryString
OperaYesEdgeYes
Edge (Legacy)12+IEYes
Firefox for Android8+iOS Safari6–7Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes
The readAsBinaryString(blob)
method,
when invoked, must run these steps:
-
Let stream be the result of calling get stream on blob.
-
Let reader be the result of getting a reader from stream.
-
Let promise be the result of reading all bytes from stream with reader.
-
Wait for promise to be fulfilled or rejected.
-
If promise fulfilled with a byte sequence bytes:
-
Return the result of package data given bytes, BinaryString, and blob’s
type
.
-
-
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
orBlob
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). SeeNotFoundError
. -
A
File
orBlob
may be unreadable. This may be due to permission problems that occur after a reference to aFile
orBlob
has been acquired (e.g. concurrent lock with another application). Additionally, the snapshot state may have changed. SeeNotReadableError
. -
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.
Type | Description and Failure Reason |
---|---|
NotFoundError
|
If the File or Blob resource could not be found at the time the read was processed,
this is the NotFound failure reason.
For asynchronous read methods the |
SecurityError
|
If:
For asynchronous read methods the This is a security error to be used in situations not covered by any other failure reason. |
NotReadableError
|
If:
For asynchronous read methods the |
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.
-
Let result be the empty string.
-
Append the string "
blob:
" to result. -
Let settings be the current settings object
-
Let origin be settings’s origin.
-
Let serialized be the ASCII serialization of origin.
-
If serialized is "
null
", set it to an implementation-defined value. -
Append serialized to result.
-
Append U+0024 SOLIDUS (
/
) to result. -
Generate a UUID [RFC4122] as a string and append it to result.
-
Return result.
blob:https://example.org/40a5fb5a-d56d-4a33-b4e2-0acf6a8e5f64
1. -
Let store be the user agent’s blob URL store.
-
Let url be the result of generating a new blob URL.
-
Let entry be a new blob URL entry consisting of object and the current settings object.
-
Set store[url] to entry.
-
Return url.
-
Let store be the user agent’s blob URL store;
-
Let url string be the result of serializing url.
-
Remove store[url string].
8.3. Dereferencing Model for blob URLs
-
Let store be the user agent’s blob URL store.
-
Let url string be the result of serializing url with the exclude fragment flag set.
-
If store[url string] exists, return store[url string]; otherwise return failure.
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:
-
Let environment be the
Document
's relevant settings object. -
Let store be the user agent’s blob URL store;
-
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
In all current engines.
Opera19+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android19+iOS Safari7+Chrome for Android32+Android WebView4.4+Samsung Internet2.0+Opera Mobile19+
Node.js10.0.0+
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
In all current engines.
Opera15+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android19+iOS Safari6+Chrome for Android25+Android WebViewYesSamsung Internet1.5+Opera Mobile14+
Node.jsNone
createObjectURL(obj)
static method must
return the result of adding an entry to the blob URL store for obj. In all current engines.
Opera15+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android19+iOS Safari6+Chrome for Android25+Android WebView37+Samsung Internet1.5+Opera Mobile14+
Node.jsNone
revokeObjectURL(url)
static method must run these steps:
-
Let url record be the result of parsing url.
-
If url record’s scheme is not "
blob
", return. -
Let origin be the origin of url record.
-
Let settings be the current settings object.
-
If origin is not same origin with settings’s origin, return.
Note: This means that rather than throwing some kind of error, attempting to revoke a URL that isn’t registered will silently fail. User agents might display a message on the error console if this happens.
Note: Attempts to dereference url after it has been revoked will result in a network error. Requests that were started before the url was revoked should still succeed.
window1
and window2
are separate,
but in the same origin; window2
could be an iframe
inside window1
.
myurl= window1. URL. createObjectURL( myblob); window2. URL. revokeObjectURL( myurl);
Since a user agent has one global blob URL store,
it is possible to revoke an object URL from a different window than from which it was created.
The URL.
call
ensures that subsequent dereferencing of revokeObjectURL()
myurl
results in a the user agent acting as if a network error has occurred.
8.4.1. Examples of blob URL Creation and Revocation
Blob URLs 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()
This section gives sample usage of creation and revocation of blob URLs with explanations.
img
elements [HTML] refer to the same blob URL:
url= URL. createObjectURL( blob); img1. src= url; img2. src= url;
URL.revokeObjectURL()
is explicitly called.
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 theFileList
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 aSecurityError
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.
-
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. Thetext/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 thea
element initiates a download, saving aFile
with the name specified. The combination of this API and thedownload
attribute ona
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.
-
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