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.

TheFileinterface represents file data typically obtained from the underlying file system, and theBlobinterface ( "Binary Large Object" - a name originally introduced to web APIs inGoogle Gears) represents immutable raw data.FileorBlobreads 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 anevent modelto read and access aFileorBlob’s data. AFileReaderobject 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 theprogress 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.

functionstartRead(){
// obtain input element through DOM

varfile=document.getElementById('file').files[0];
if(file){
getAsText(file);
}
}

functiongetAsText(readFile){

varreader=newFileReader();

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

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

functionloaded(evt){
// Obtain the read file data
varfileString=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)
}

functionerrorHandler(evt){
if(evt.target.error.name=="NotReadableError"){
// The file could not be read
}
}

2.Terminology and Algorithms

When this specification says toterminate an algorithmthe user agent must terminate the algorithm after finishing the step it is on. Asynchronousread methodsdefined in this specification may return before the algorithm in question is terminated, and can be terminated by anabort()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 termUnix Epochis 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

ABlobobject refers to abytesequence, and has asizeattribute which is the total number of bytes in the byte sequence, and atypeattribute, which is an ASCII-encoded string in lower case representing the media type of thebytesequence.

EachBlobmust have an internalsnapshot state, which must be initially set to the state of the underlying storage, if any such underlying storage exists. Further normative definition ofsnapshot statecan be found forFiles.

[Exposed=(Window,Worker),Serializable]
interfaceBlob{
constructor(optionalsequence<BlobPart>blobParts,
optionalBlobPropertyBagoptions= {});

readonlyattributeunsignedlonglongsize;
readonlyattributeDOMStringtype;

// slice Blob into byte-ranged chunks
Blobslice(optional[Clamp]longlongstart,
optional[Clamp]longlongend,
optionalDOMStringcontentType);

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

enumEndingType{"transparent","native"};

dictionaryBlobPropertyBag{
DOMStringtype= "";
EndingTypeendings= "transparent";
};

typedef(BufferSourceorBloborUSVString)BlobPart;

Blobobjects areserializable objects.Theirserialization steps, givenvalueandserialized,are:

1. Setserialized.[[SnapshotState]] tovalue’ssnapshot state.

2. Setserialized.[[ByteSequence]] tovalue’s underlying byte sequence.

Theirdeserialization step,givenserializedandvalue,are:

1. Setvalue’ssnapshot statetoserialized.[[SnapshotState]].

2. Setvalue’s underlying byte sequence toserialized.[[ByteSequence]].

3.1.Constructors

3.1.1.Constructor Parameters

TheBlob()constructor can be invoked with the parameters below:

AblobPartssequence

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

• BufferSourceelements.

• Blobelements.

• USVStringelements.

AnoptionalBlobPropertyBag

which takes these optional members:

• type, the ASCII-encoded string in lower case representing the media type of theBlob. Normative conditions for this member are provided in the§ 3.1 Constructors.

• endings, an enum which can take the values"transparent"or"native". By default this is set to"transparent".If set to"native",line endings will be converted to nativein anyUSVStringelements inblobParts.

// Create a new Blob object

vara=newBlob();

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

varbuffer=newArrayBuffer(1024);

// Create ArrayBufferView objects based on buffer

varshorts=newUint16Array(buffer,512,128);
varbytes=newUint8Array(buffer,shorts.byteOffset+shorts.byteLength);

varb=newBlob(["foobarbazetcetc"+"birdiebirdieboo"],{type:"text/plain;charset=utf-8"});

varc=newBlob([b,shorts]);

vara=newBlob([b,c,bytes]);

vard=newBlob([buffer,b,c,bytes]);

3.2.Attributes

size,of typeunsigned long long,readonly

Returns the size of thebytesequence in number of bytes. On getting, conforming user agents must return the total number of bytes that can be read by aFileReaderorFileReaderSyncobject, or 0 if theBlobhas no bytes to be read.

type,of typeDOMString,readonly

The ASCII-encoded string in lower case representing the media type of theBlob. On getting, user agents must return the type of aBlobas an ASCII-encoded string in lower case, such that when it is converted to abytesequence, it is aparsable MIME type, or the empty string – 0 bytes – if the type cannot be determined.

Thetypeattribute can be set by the web application itself through constructor invocation and through theslice()call; in these cases, further normative conditions for this attribute are in§ 3.1 Constructors,§ 4.1 Constructor, and§ 3.3.1 The slice() methodrespectively. User agents can also determine thetypeof aBlob, especially if thebytesequence is from an on-disk file; in this case, further normative conditions are in thefile type guidelines.

Note:The typetof aBlobis considered aparsable MIME type, if performing theparse a MIME typealgorithm to a byte sequence converted from the ASCII-encoded string representing the Blob object’s type does not return failure.

Note:Use of thetypeattribute informs thepackage dataalgorithm and determines theContent-Typeheader whenfetchingblob URLs.

3.3.Methods and Parameters

3.3.1.Theslice()method

// obtain input element through DOM

varfile=document.getElementById('file').files[0];
if(file)
{
// create an identical copy of file
// the two calls below are equivalent

varfileClone=file.slice();
varfileClone2=file.slice(0,file.size);

// slice file into 1/2 chunk starting at middle of file
// Note the use of negative number

varfileChunkFromEnd=file.slice(-(Math.round(file.size/2)));

// slice file into 1/2 chunk starting at beginning of file

varfileChunkFromStart=file.slice(0,Math.round(file.size/2));

// slice file from beginning till 150 bytes before end

varfileNoMetadata=file.slice(0,-150,"application/experimental");
}

3.3.2.Thestream()method

Thestream()method, when invoked, must return the result of callingget streamonthis.

3.3.3.Thetext()method

Thetext()method, when invoked, must run these steps:

1. Letstreambe the result of callingget streamonthis.

2. Letreaderbe the result ofgetting a readerfromstream. If that threw an exception, return a new promise rejected with that exception.

3. Letpromisebe the result ofreading all bytesfromstreamwithreader.

4. Return the result of transformingpromiseby a fulfillment handler that returns the result of runningUTF-8 decodeon its first argument.

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

3.3.4.ThearrayBuffer()method

ThearrayBuffer()method, when invoked, must run these steps:

1. Letstreambe the result of callingget streamonthis.

2. Letreaderbe the result ofgetting a readerfromstream. If that threw an exception, return a new promise rejected with that exception.

3. Letpromisebe the result ofreading all bytesfromstreamwithreader.

4. Return the result of transformingpromiseby a fulfillment handler that returns a newArrayBufferwhose contents are its first argument.

3.3.5.Thebytes()method

Thebytes()method, when invoked, must run these steps:

1. Letstreambe the result of callingget streamonthis.

2. Letreaderbe the result ofgetting a readerfromstream. If that threw an exception, return a new promise rejected with that exception.

3. Letpromisebe the result ofreading all bytesfromstreamwithreader.

4. Return the result of transformingpromiseby a fulfillment handler that returns a newUint8Arraywrapping anArrayBuffercontaining its first argument.

4.The File Interface

AFileobject is aBlobobject with anameattribute, which is a string; it can be created within the web application via a constructor, or is a reference to abytesequence from a file from the underlying (OS) file system.

If aFileobject is a reference to abytesequence originating from a file on disk, then itssnapshot stateshould be set to the state of the file on disk at the time theFileobject is created.

Note:This is a non-trivial requirement to implement for user agents, and is thus not amustbut ashould[RFC2119]. User agents should endeavor to have aFileobject’ssnapshot stateset to the state of the underlying storage on disk at the time the reference is taken. If the file is modified on disk following the time a reference has been taken, theFile'ssnapshot statewill differ from the state of the underlying storage. User agents may use modification time stamps and other mechanisms to maintainsnapshot state, but this is left as an implementation detail.

When aFileobject refers to a file on disk, user agents must return thetypeof that file, and must follow thefile type guidelinesbelow:

• User agents must return thetypeas an ASCII-encoded string in lower case, such that when it is converted to a corresponding byte sequence, it is aparsable MIME type, or the empty string – 0 bytes – if the type cannot be determined.

• When the file is of typetext/plainuser agents must NOT append a charset parameter to thedictionary of parametersportion of the media type[MIMESNIFF].

• User agents must not attempt heuristic determination of encoding, including statistical methods.

[Exposed=(Window,Worker),Serializable]
interfaceFile:Blob{
constructor(sequence<BlobPart>fileBits,
USVStringfileName,
optionalFilePropertyBagoptions= {});
readonlyattributeDOMStringname;
readonlyattributelonglonglastModified;
};

dictionaryFilePropertyBag:BlobPropertyBag{
longlonglastModified;
};

Fileobjects areserializable objects.Theirserialization steps, givenvalueandserialized,are:

1. Setserialized.[[SnapshotState]] tovalue’ssnapshot state.

2. Setserialized.[[ByteSequence]] tovalue’s underlying byte sequence.

3. Setserialized.[[Name]] to the value ofvalue’snameattribute.

4. Setserialized.[[LastModified]] to the value ofvalue’slastModifiedattribute.

Theirdeserialization steps,givenvalueandserialized,are:

1. Setvalue’ssnapshot statetoserialized.[[SnapshotState]].

2. Setvalue’s underlying byte sequence toserialized.[[ByteSequence]].

3. Initialize the value ofvalue’snameattribute toserialized.[[Name]].

4. Initialize the value ofvalue’slastModifiedattribute toserialized.[[LastModified]].

4.1.Constructor

4.1.1.Constructor Parameters

TheFile()constructor can be invoked with the parameters below:

AfileBitssequence

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

• BufferSourceelements.

• Blobelements, which includesFileelements.

• USVStringelements.

AfileNameparameter

AUSVStringparameter representing the name of the file; normative conditions for this constructor parameter can be found in§ 4.1 Constructor.

An optionalFilePropertyBagdictionary

which in addition to themembersofBlobPropertyBagtakes one member:

• An optionallastModifiedmember, which must be along long; normative conditions for this member are provided in§ 4.1 Constructor.

4.2.Attributes

name,of typeDOMString,readonly

The name of the file. On getting, this must return 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 must return the empty string. If aFileobject is created using a constructor, further normative conditions for this attribute are found in§ 4.1 Constructor.

lastModified,of typelong long,readonly

The last modified date of the file. On getting, if user agents can make this information available, this must return along longset to the time the file was last modified as the number of milliseconds since theUnix Epoch. If the last modification date and time are not known, the attribute must return the current date and time as along longrepresenting the number of milliseconds since theUnix Epoch; this is equivalent toDate.now()[ECMA-262]. If aFileobject is created using a constructor, further normative conditions for this attribute are found in§ 4.1 Constructor.

TheFileinterface is available on objects that expose an attribute of typeFileList; these objects are defined in HTML[HTML]. TheFileinterface, which inherits fromBlob,is immutable, and thus represents file data that can be read into memory at the time aread operationis initiated. User agents must process reads on files that no longer exist at the time of read aserrors, throwing aNotFoundErrorexception if using aFileReaderSyncon a Web Worker[Workers]or firing anerrorevent with theerrorattribute returning aNotFoundError.

varfile=document.getElementById("filePicker").files[0];
vardate=newDate(file.lastModified);
println("You selected the file"+file.name+"which was modified on"+date.toDateString()+".");

...

// Generate a file with a specific last modified date

vard=newDate(2013,12,5,16,23,45,600);
vargeneratedFile=newFile(["Rough Draft...."],"Draft1.txt",{type:"text/plain",lastModified:d})

...

5.The FileList Interface

Note:TheFileListinterface should be considered "at risk" since the general trend on the Web Platform is to replace such interfaces with theArrayplatform object in ECMAScript[ECMA-262]. In particular, this means syntax of the sortfilelist.item(0)is at risk; most other programmatic use ofFileListis unlikely to be affected by the eventual migration to anArraytype.

This interface is a list ofFileobjects.

[Exposed=(Window,Worker),Serializable]
interfaceFileList{
getterFile?item(unsignedlongindex);
readonlyattributeunsignedlonglength;
};

FileListobjects areserializable objects.Theirserialization steps, givenvalueandserialized,are:

1. Setserialized.[[Files]] to an emptylist.

2. For eachfileinvalue,append thesub-serializationoffiletoserialized.[[Files]].

Theirdeserialization step,givenserializedandvalue,are:

1. For eachfileofserialized.[[Files]], add thesub-deserializationoffiletovalue.

// uploadData is a form element
// fileChooser is input element of type 'file'
varfile=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 typeunsigned long,readonly

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

5.2.Methods and Parameters

item(index)

must return theindexthFileobject in theFileList. If there is noindexthFileobject in theFileList, then this method must returnnull.

indexmust be treated by user agents as value for the position of aFileobject in theFileList, with 0 representing the first file.Supported property indicesare the numbers in the range zero to one less than the number ofFileobjects represented by theFileListobject. If there are no suchFileobjects, then there are no supported property indices.

Note:TheHTMLInputElementinterface has a readonly attribute of typeFileList, which is what is being accessed in the above example. Other interfaces with a readonly attribute of typeFileListinclude theDataTransferinterface.

6.Reading Data

6.1.The File Reading Task Source

This specification defines a new generictask sourcecalled thefile reading task source, which is used for alltasks that are queuedin this specification to read byte sequences associated withBlobandFileobjects. It is to be used for features that trigger in response to asynchronously reading binary data.

6.2.TheFileReaderAPI

[Exposed=(Window,Worker)]
interfaceFileReader:EventTarget{
constructor();
// async read methods
undefinedreadAsArrayBuffer(Blobblob);
undefinedreadAsBinaryString(Blobblob);
undefinedreadAsText(Blobblob,optionalDOMStringencoding);
undefinedreadAsDataURL(Blobblob);

undefinedabort();

// states
constunsignedshortEMPTY= 0;
constunsignedshortLOADING= 1;
constunsignedshortDONE= 2;

readonlyattributeunsignedshortreadyState;

// File or Blob data
readonlyattribute(DOMStringorArrayBuffer)?result;

readonlyattributeDOMException?error;

// event handler content attributes
attributeEventHandleronloadstart;
attributeEventHandleronprogress;
attributeEventHandleronload;
attributeEventHandleronabort;
attributeEventHandleronerror;
attributeEventHandleronloadend;
};

AFileReaderhas an associatedstate, that is"empty","loading",or"done".It is initially"empty".

AFileReaderhas an associatedresult(null,aDOMStringor anArrayBuffer). It is initiallynull.

AFileReaderhas an associatederror(nullor aDOMException). It is initiallynull.

TheFileReader()constructor, when invoked, must return a newFileReaderobject.

ThereadyStateattribute’s getter, when invoked, switches onthis'sstateand runs the associated step:

"empty"

ReturnEMPTY

"loading"

ReturnLOADING

"done"

ReturnDONE

Theresultattribute’s getter, when invoked, must returnthis'sresult.

Theerrorattribute’s getter, when invoked, must returnthis'serror.

6.2.1.Event Handler Content Attributes

The following are theevent handler content attributes(and their correspondingevent handler event types) that user agents must support onFileReaderas DOM attributes:

6.2.2.FileReader States

6.2.3.Reading a File or Blob

TheFileReaderinterface makes available severalasynchronous read methods—readAsArrayBuffer(),readAsBinaryString(),readAsText()andreadAsDataURL(), which read files into memory.

Note:If multiple concurrent read methods are called on the sameFileReaderobject, user agents throw anInvalidStateErroron any of the read methods that occur whenreadyState=LOADING.

(FileReaderSyncmakes available severalsynchronous read methods. Collectively, the sync and async read methods ofFileReaderandFileReaderSyncare referred to as justread methods.)

6.2.3.1.ThereadAsDataURL()method

ThereadAsDataURL(blob)method, when invoked, must initiate aread operationforblobwithDataURL.

6.2.3.2.ThereadAsText()method

ThereadAsText(blob,encoding)method, when invoked, must initiate aread operationforblobwithTextandencoding.

6.2.3.3.ThereadAsArrayBuffer()

ThereadAsArrayBuffer(blob)method, when invoked, must initiate aread operationforblobwithArrayBuffer.

6.2.3.4.ThereadAsBinaryString()method

ThereadAsBinaryString(blob)method, when invoked, must initiate aread operationforblobwithBinaryString.

Note:The use ofreadAsArrayBuffer()is preferred overreadAsBinaryString(),which is provided for backwards compatibility.

6.2.3.5.Theabort()method

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

1. Ifthis'sstateis"empty"or ifthis'sstateis"done"setthis'sresulttonullandterminate this algorithm.

2. Ifthis'sstateis"loading"setthis'sstateto"done"and setthis'sresulttonull.

3. If there are anytasksfromthison thefile reading task sourcein an affiliatedtask queue, then remove thosetasksfrom that task queue.

4. Terminate the algorithmfor theread methodbeing processed.

5. Fire a progress eventcalledabortatthis.

6. Ifthis'sstateis not"loading",fire a progress eventcalledloadendatthis.

6.3.Packaging data

6.4.Events

TheFileReaderobject must be the event target for all events in this specification.

When this specification says tofire a progress eventcalled e(for someProgressEventeat a givenFileReaderreader), the following are normative:

• The progress eventedoes not bubble.e.bubblesmust be false[DOM]

• The progress eventeis NOT cancelable.e.cancelablemust be false[DOM]

6.4.1.Event Summary

The following are the events that arefiredatFileReaderobjects.

6.4.2.Summary of Event Invariants

This section is informative.

The following are invariants applicable toevent firingfor a given asynchronousread methodin this specification:

1. Once aloadstarthas been fired, a correspondingloadendfires at completion of the read, UNLESS any of the following are true:

   • theread methodhas been cancelled usingabort()and a newread methodhas been invoked

   • the event handler function for aloadevent initiates a new read

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

   Note:The eventsloadstartandloadendare 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. Oneprogressevent will fire whenblobhas been completely read into memory.

3. Noprogressevent fires beforeloadstart.

4. Noprogressevent fires after any one ofabort,load,anderrorhave fired. At most one ofabort,load,anderrorfire for a given read.

5. Noabort,load,orerrorevent fires afterloadend.

6.5.Reading on Threads

Web Workers allow for the use of synchronousFileorBlobread 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 (theFileReaderobject)andthe synchronous API (theFileReaderSyncobject).

6.5.1.TheFileReaderSyncAPI

This interface provides methods tosynchronously readFileorBlobobjects into memory.

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

ArrayBufferreadAsArrayBuffer(Blobblob);
DOMStringreadAsBinaryString(Blobblob);
DOMStringreadAsText(Blobblob,optionalDOMStringencoding);
DOMStringreadAsDataURL(Blobblob);
};

6.5.1.1.Constructors

When theFileReaderSync()constructor is invoked, the user agent must return a newFileReaderSyncobject.

6.5.1.2.ThereadAsText()

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

1. Letstreambe the result of callingget streamonblob.

2. Letreaderbe the result ofgetting a readerfromstream.

3. Letpromisebe the result ofreading all bytesfromstreamwithreader.

4. Wait forpromiseto be fulfilled or rejected.

5. Ifpromisefulfilled with abyte sequencebytes:

   1. Return the result ofpackage datagivenbytes,Text,blob’stype,andencoding.

6. Throwpromise’s rejection reason.

6.5.1.3.ThereadAsDataURL()method

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

1. Letstreambe the result of callingget streamonblob.

2. Letreaderbe the result ofgetting a readerfromstream.

3. Letpromisebe the result ofreading all bytesfromstreamwithreader.

4. Wait forpromiseto be fulfilled or rejected.

5. Ifpromisefulfilled with abyte sequencebytes:

   1. Return the result ofpackage datagivenbytes,DataURL,andblob’stype.

6. Throwpromise’s rejection reason.

6.5.1.4.ThereadAsArrayBuffer()method

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

1. Letstreambe the result of callingget streamonblob.

2. Letreaderbe the result ofgetting a readerfromstream.

3. Letpromisebe the result ofreading all bytesfromstreamwithreader.

4. Wait forpromiseto be fulfilled or rejected.

5. Ifpromisefulfilled with abyte sequencebytes:

   1. Return the result ofpackage datagivenbytes,ArrayBuffer,andblob’stype.

6. Throwpromise’s rejection reason.

6.5.1.5.ThereadAsBinaryString()method

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

1. Letstreambe the result of callingget streamonblob.

2. Letreaderbe the result ofgetting a readerfromstream.

3. Letpromisebe the result ofreading all bytesfromstreamwithreader.

4. Wait forpromiseto be fulfilled or rejected.

5. Ifpromisefulfilled with abyte sequencebytes:

   1. Return the result ofpackage datagivenbytes,BinaryString,andblob’stype.

6. Throwpromise’s rejection reason.

Note:The use ofreadAsArrayBuffer()is preferred overreadAsBinaryString(),which is provided for backwards compatibility.

7.Errors and Exceptions

File read errorscan occur when reading files from the underlying filesystem. The list below of potential error conditions isinformative.

• TheFileorBlobbeing accessed may not exist at the time one of theasynchronous read methodsorsynchronous read methodsare 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.

• AFileorBlobmay be unreadable. This may be due to permission problems that occur after a reference to aFileorBlobhas been acquired (e.g. concurrent lock with another application). Additionally, thesnapshot statemay 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 ConsiderationsandSecurityError.

7.1.Throwing an Exception or Returning an Error

This section is normative.

Error conditions can arise when reading aFileor aBlob.

Theread operationcan terminate due to error conditions when reading aFileor aBlob; the particular error condition that causes theget streamalgorithm to fail is called afailure reason.Afailure reasonis one ofNotFound,UnsafeFile,TooManyReads,SnapshotState,orFileLock.

Synchronous read methodsthrowexceptions of the type in the table below if there has been an error owing to a particularfailure reason.

Asynchronous read methods use theerrorattribute of theFileReaderobject, which must return aDOMExceptionobject of the most appropriate type from the table below if there has been an error owing to a particularfailure reason, or otherwise return null.

8.A URL for Blob and MediaSource reference

This section defines aschemefor aURLused to refer toBlobandMediaSourceobjects.

8.1.Introduction

This section is informative.

Blob (or object) URLsare URLs likeblob:http://example.com/550e8400-e29b-41d4-a716-446655440000. This enables integration ofBlobs andMediaSources with other APIs that are only designed to be used with URLs, such as theimgelement.Blob URLscan 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 theURLinterface,createObjectURL(obj)andrevokeObjectURL(url). The first method creates a mapping from aURLto aBlob, and the second method revokes said mapping. As long as the mapping exist theBlobcan’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 ablob URL store. Ablob URL storeis amapwherekeysarevalid URL stringsandvaluesareblob URL Entries.

Ablob URL entryconsists of anobject(of typeBloborMediaSource), and anenvironment(anenvironment settings object).

Keysin theblob URL store(also known asblob URLs) arevalid URL stringsthat whenparsedresult in aURLwith aschemeequal to "blob", anempty host,and apathconsisting of one element itself also avalid URL string.

8.3.Dereferencing Model for blob URLs

Futher requirements for the parsing and fetching model forblob URLsare 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 theblob URL storewhen 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 theunloading document cleanup stepswith the following steps:

1. Letenvironmentbe theDocument'srelevant settings object.

2. Letstorebe the user agent’sblob URL store;

3. Remove fromstoreany entries for which thevalue'senvironmentis equal toenvironment.

This needs a similar hook when a worker is unloaded.

8.4.Creating and Revoking a blob URL

Blob URLsare created and revoked using static methods exposed on theURLobject. Revocation of ablob URLdecouples theblob URLfrom the resource it refers to, and if it is dereferenced after it is revoked, user agents must act as if anetwork errorhas occurred. This section describes a supplemental interface to the URL specification[URL]and presents methods forblob URLcreation and revocation.

[Exposed=(Window,DedicatedWorker,SharedWorker)]
partialinterfaceURL{
staticDOMStringcreateObjectURL((BloborMediaSource)obj);
staticundefinedrevokeObjectURL(DOMStringurl);
};

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

8.4.1.Examples of blob URL Creation and Revocation

Blob URLs are strings that are used tofetchBlobobjects, and can persist for as long as thedocumentfrom which they were minted usingURL.createObjectURL()—see§ 8.3.2 Lifetime of blob URLs.

This section gives sample usage of creation and revocation ofblob URLs with explanations.

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

varblobURLref=URL.createObjectURL(file);
img1=newImage();
img2=newImage();

// 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 singleblob URL, and the web developer then revokes theblob URLstring after both image objects have been loaded. While not restricting number of uses of theblob URLoffers more flexibility, it increases the likelihood of leaks; developers should pair it with a corresponding call toURL.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 byFileReaderobjects 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 theFileListobject 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 viablob URLs. User agents maythrowaSecurityErrorexception for synchronous read methods, or return aSecurityErrorexception 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. Thetext/calendarfile 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. Thedownloadattribute of theaelement initiates a download, saving aFilewith the name specified. The combination of this API and thedownloadattribute onaelements 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 [email protected] listserv