diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b2680aa..684a114 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,6 +5,10 @@ Contributions to this repository are intended to become part of Recommendation-t
[Software and Document License](http://www.w3.org/Consortium/Legal/copyright-software). To make substantive contributions to specifications, you must either participate
in the relevant W3C Working Group or make a non-member patent licensing commitment.
+# Pull Requests
+
+To make a pull request, please edit the `index.bs` in the `master` branch, our travis bot will generate an `index.html` and push the file to `gh-pages` branch once you submit your patch.
+
If you are not the sole contributor to a contribution (pull request), please identify all
contributors in the pull request comment.
diff --git a/index.bs b/index.bs
deleted file mode 100644
index 08afe89..0000000
--- a/index.bs
+++ /dev/null
@@ -1,1940 +0,0 @@
-
-Indent: 2
-Title: File API
-Shortname: FileAPI
-Level: 1
-Group: webplatform
-Editor: Marijn Kruisselbrink, Google, mek@chromium.org, w3cid 72440
-Editor: Vsevolod Shmyroff, Yandex, w3cid 93074
-Former Editor: Arun Ranganathan, Mozilla Corporation, http://arunranga.com/, arun@mozilla.com, w3cid 37240
-Status: ED
-ED: https://w3c.github.io/FileAPI/
-TR: https://www.w3.org/TR/FileAPI/
-Repository: w3c/FileAPI
-Previous Version: https://www.w3.org/TR/2017/WD-FileAPI-20171026/
-!Tests: web-platform-tests FileAPI/ (ongoing work)
-Abstract: This specification provides an API for representing file objects in web applications,
- as well as programmatically selecting them and accessing their data. This includes:
-
- * A {{FileList}} interface, which represents an array of individually selected files from the underlying system. The user interface for selection can be invoked via <input type="file">, i.e. when the input element is in the File Upload state [[HTML]].
- * A {{Blob}} interface, which represents immutable raw binary data, and allows access to ranges of bytes within the {{Blob}} object as a separate {{Blob}}.
- * A {{File}} interface, which includes readonly informational attributes about a file such as its name and the date of the last modification (on disk) of the file.
- * A {{FileReader}} interface, which provides methods to read a {{File}} or a {{Blob}}, and an event model to obtain the results of these reads.
- * A URL scheme for use with binary data such as files, so that they can be referenced within web applications.
-
- Additionally, this specification defines objects to be used within threaded web applications for the synchronous reading of files.
-
- [[#requirements]] covers the motivation behind this specification.
-
- This API is designed to be used in conjunction with other APIs and elements on the web platform, notably:
- {{XMLHttpRequest}} (e.g. with an overloaded {{XMLHttpRequest/send()}} method for {{File}} or {{Blob}} arguments),
- {{Worker/postMessage()}},
- {{DataTransfer}} (part of the drag and drop API defined in [[HTML]])
- and Web Workers.
- Additionally, it should be possible to programmatically obtain a list of files from the <{input}> element
- when it is in the File Upload state [[HTML]].
- These kinds of behaviors are defined in the appropriate affiliated specifications.
-Status Text: Previous discussion of this specification has taken place on two other mailing lists: public-webapps@w3.org (archive) and public-webapi@w3.org (archive). Ongoing discussion will be on the public-webapps@w3.org mailing list.
-
- This draft consists of changes made to the previous Last Call Working Draft. Please send comments to the public-webapi@w3.org as described above. You can see Last Call Feedback on the W3C Wiki: http://www.w3.org/wiki/Webapps/LCWD-FileAPI-20130912
-Translate Ids: dictdef-blobpropertybag dfn-BlobPropertyBag, dictdef-filepropertybag dfn-FilePropertyBag, filereadersync dfn-FileReaderSync, filelist dfn-filelist, filereader dfn-filereader, file dfn-file, blob dfn-Blob, blob-section blob, file-section file
-Markup Shorthands: css no, markdown yes
-
-
-
-spec: dom
- type:interface
- text:Document
-spec: html
- type: element
- text: a
- text: iframe
-spec: infra
- type: dfn
- text: list
- text: string
-spec: streams
- type: dfn
- text: chunk
-spec: url
- type: dfn
- text: url; for:/
- type: interface
- text: URL
-
-
-
-spec: xhr; urlPrefix: https://xhr.spec.whatwg.org/
- type: method
- for: XMLHttpRequest
- text: getAllResponseHeaders(); url: #dom-xmlhttprequest-getallresponseheaders
-spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
- urlPrefix: semantics.html
- type: element-attr; for: a; text: download; url: #attr-hyperlink-download
- type:dfn; text:origin
-spec: mimesniff; urlPrefix: https://mimesniff.spec.whatwg.org/
- type: dfn
- text: parsable mime type
- text: parse a MIME type
-spec: ecma-262; urlPrefix: http://tc39.github.io/ecma262/
- type: interface
- text: Array; url: sec-array-constructor
- text: Date; url: sec-date-constructor
-
-
-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.
-
-
- In the example below, different code blocks handle progress, error, and success conditions.
-
-
- 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
- }
- }
-
-
-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 {{FileReader/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]].
-
-
-
-
-The Blob Interface and Binary Data
-
-A {{Blob}} object refers to a byte sequence,
-and has a {{Blob/size}} attribute which is the total number of bytes in the byte sequence,
-and a {{Blob/type}} attribute,
-which is an ASCII-encoded string in lower case representing the media type of the byte sequence.
-
-Each {{Blob}} must have an internal snapshot state,
-which must be initially set to the state of the underlying storage,
-if any such underlying storage exists.
-Further normative definition of snapshot state can be found for {{File}}s.
-
-
-[Constructor(optional sequence<BlobPart> blobParts,
- optional BlobPropertyBag options),
- Exposed=(Window,Worker), Serializable]
-interface Blob {
-
- readonly attribute unsigned long long size;
- readonly attribute DOMString type;
-
- // slice Blob into byte-ranged chunks
- Blob slice([Clamp] optional long long start,
- [Clamp] optional long long end,
- optional DOMString contentType);
-};
-
-enum EndingType { "transparent", "native" };
-
-dictionary BlobPropertyBag {
- DOMString type = "";
- EndingType endings = "transparent";
-};
-
-typedef (BufferSource or Blob or USVString) BlobPart;
-
-
-{{Blob}} objects are [=serializable objects=]. Their [=serialization steps=],
-given |value| and |serialized|, are:
-
-1. Set |serialized|.\[[SnapshotState]] to |value|'s [=snapshot state=].
-
-2. Set |serialized|.\[[ByteSequence]] to |value|'s underlying byte sequence.
-
-Their [=deserialization step=], given |serialized| and |value|, are:
-
-1. Set |value|'s [=snapshot state=] to |serialized|.\[[SnapshotState]].
-
-2. Set |value|'s underlying byte sequence to |serialized|.\[[ByteSequence]].
-
-
-Constructors
-
-
-The {{Blob()}} constructor can be invoked with zero or more parameters.
-When the {{Blob()}} constructor is invoked,
-user agents must run the following steps:
-
-1. If invoked with zero parameters,
- return a new {{Blob}} object consisting of 0 bytes,
- with {{Blob/size}} set to 0,
- and with {{Blob/type}} set to the empty string.
-
-1. Let |bytes| be the result of [=processing blob parts=] given {{blobParts}} and {{Blob/Blob(blobParts, options)/options}}.
-
-1. If the {{BlobPropertyBag/type}} member of the optional {{Blob/Blob(blobParts, options)/options}} argument is provided
- and is not the empty string,
- run the following sub-steps:
-
- 1. Let |t| be the {{BlobPropertyBag/type}} dictionary member.
- If |t| contains any characters outside the range U+0020 to U+007E,
- then set |t| to the empty string and return from these substeps.
- 1. Convert every character in |t| to [=ASCII lowercase=].
-
-1. Return a {{Blob}} object referring to |bytes| as its associated
byte sequence,
- with its {{Blob/size}} set to the length of |bytes|,
- and its {{Blob/type}} set to the value of |t| from the substeps above.
-
-
-Constructor Parameters
-
-The {{Blob()}} constructor can be invoked with the parameters below:
-
-
- - A
blobParts sequence
- - which takes any number of the following types of elements, and in any order:
- * {{BufferSource}} elements.
- * {{Blob}} elements.
- * {{USVString}} elements.
-
-
- An *optional* {{BlobPropertyBag}}
-
- which takes these optional members:
- * type,
- the ASCII-encoded string in lower case representing the media type of the {{Blob}}.
- Normative conditions for this member are provided in the [[#constructorBlob]].
- * endings,
- an enum which can take the values {{"transparent"}} or {{"native"}}.
- By default this is set to {{"transparent"}}. If set to {{"native"}},
- [=convert line endings to native|line endings will be converted to native=]
- in any {{USVString}} elements in {{blobParts}}.
-
-
-
-To
process blob parts given a sequence of {{BlobPart}}'s |parts|
-and {{BlobPropertyBag}} |options|,
-run the following steps:
-
-1. Let |bytes| be an empty sequence of bytes.
-
-1. For each |element| in |parts|:
-
- 1. If |element| is a {{USVString}}, run the following substeps:
-
- 1. Let |s| be |element|.
-
- 1. If the {{BlobPropertyBag/endings}} member of |options| is {{"native"}},
- set |s| to the result of [=converting line endings to native=] of |element|.
-
- 1. 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.
-
- 1. If |element| is a {{BufferSource}},
get
- a copy of the bytes held by the buffer source, and append those bytes to |bytes|.
-
- 1. If |element| is a {{Blob}},
- append the bytes it represents to |bytes|.
-
- Note: The {{Blob/type}} of the {{Blob}} array element is ignored and will not affect {{Blob/type}} of returned
- {{Blob}} object.
-
-1. Return |bytes|.
-
-
-To
-convert line endings to native in a [=string=] |s|,
-run the following steps:
-
-1. Let |native line ending| be be the [=code point=] U+000A LF.
-
-1. 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.
-
-1. Set |result| to the empty [=string=].
-
-1. Let |position| be a [=position variable=] for |s|,
- initially pointing at the start of |s|.
-
-1. 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|.
-
-1. Append |token| to |result|.
-
-1. While |position| is not past the end of |s|:
-
- 1. If the [=code point=] at |position| within |s| equals U+000D CR:
-
- 1. Append |native line ending| to |result|.
-
- 1. Advance |position| by 1.
-
- 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.
-
- 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|.
-
- 1. 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|.
-
- 1. Append |token| to |result|.
-
-1. Return |result|.
-
-
-
-
- Examples of constructor usage follow.
-
-
- // 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]);
-
-
-Attributes
-
-
- - size
-
- Returns the size of the byte sequence in number of bytes.
- On getting, conforming user agents must return the total number of bytes that can be read by a {{FileReader}} or {{FileReaderSync}} object,
- or 0 if the {{Blob}} has no bytes to be read.
-
-
- type
-
- The ASCII-encoded string in lower case representing the media type of the {{Blob}}.
- On getting, user agents must return the type of a {{Blob}}
- as an ASCII-encoded string in lower case,
- such that when it is converted to a byte sequence,
- it is a parsable MIME type,
- or the empty string – 0 bytes – if the type cannot be determined.
-
- The {{Blob/type}} attribute can be set by the web application itself through constructor invocation
- and through the {{Blob/slice()}} call;
- in these cases, further normative conditions for this attribute are in [[#constructorBlob]],
- [[#file-constructor]],
- and [[#slice-method-algo]] respectively.
- User agents can also determine the {{Blob/type}} of a {{Blob}},
- especially if the byte sequence is from an on-disk file;
- in this case, further normative conditions are in the file type guidelines.
-
- Note: The type t 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 undefined.
-
- Note: Use of the {{Blob/type}} attribute informs the encoding determination
- and determines the `Content-Type` header when [=/fetching=] [=blob URLs=].
-
-
-
-
-Methods and Parameters
-
-
-The slice method
-
-The slice() method
-returns a new {{Blob}} object with bytes ranging from
-the optional {{start}} parameter
-up to but not including the optional {{end}} parameter,
-and with a {{Blob/type}} attribute that is the value of the optional {{contentType!!argument}} parameter.
-It must act as follows:
-
-1. Let |O| be the {{Blob}} context object on which the {{slice()}} method is being called.
-2. The optional start parameter
- is a value for the start point of a {{slice()}} call,
- and must be treated as a byte-order position,
- with the zeroth position representing the first byte.
- User agents must process {{Blob/slice()}} with {{start}} normalized according to the following:
-
-
- - If the optional {{start}} parameter is not used as a parameter when making this call, let |relativeStart| be 0.
-
- If {{start}} is negative, let |relativeStart| be
max(({{Blob/size}} + {{start}}), 0).
- - Else, let |relativeStart| be
min(start, size).
-
-
-3. The optional end parameter
- is a value for the end point of a {{slice()}} call.
- User agents must process {{Blob/slice()}} with {{end}} normalized according to the following:
-
-
- - If the optional {{end}} parameter is not used as a parameter when making this call, let |relativeEnd| be {{Blob/size}}.
-
- If {{end}} is negative, let |relativeEnd| be
max((size + end), 0).
- - Else, let |relativeEnd| be
min(end, size).
-
-
-4. The optional contentType parameter
- is used to set the ASCII-encoded string in lower case representing the media type of the Blob.
- User agents must process the {{Blob/slice()}} with {{contentType}} normalized according to the following:
-
-
- - If the {{contentType}} parameter is not provided, let |relativeContentType| be set to the empty string.
-
- Else let |relativeContentType| be set to {{contentType}} and run the substeps below:
- 1. If |relativeContentType| contains any characters outside the range of U+0020 to U+007E,
- then set |relativeContentType| to the empty string and return from these substeps.
- 2. Convert every character in |relativeContentType| to [=ASCII lowercase=].
-
-
-5. Let |span| be max((relativeEnd - relativeStart), 0).
-
-6. Return a new {{Blob}} object |S| with the following characteristics:
-
-
- - |S| refers to |span| consecutive bytes from |O|,
- beginning with the byte at byte-order position |relativeStart|.
-
- |S|.{{Blob/size}} = |span|.
-
- |S|.{{Blob/type}} = |relativeContentType|.
-
-
-
- The examples below illustrate the different types of {{slice()}} calls possible. Since the
- {{File}} interface inherits from the {{Blob}} interface, examples are based on the use of the {{File}} interface.
-
-
- // 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");
- }
-
-
-The File Interface
-
-A {{File}} object is a {{Blob}} object with a {{File/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.
-
-If a {{File}} object is a reference to a byte sequence originating from a file on disk,
-then its snapshot state should be set to the state of the file on disk at the time the {{File}} object is created.
-
-Note: This is a non-trivial requirement to implement for user agents,
-and is thus not a *must* but a *should* [[RFC2119]].
-User agents should endeavor to have a {{File}} object's snapshot state
-set 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,
-the {{File}}'s snapshot state will differ from the state of the underlying storage.
-User agents may use modification time stamps and other mechanisms to maintain snapshot state,
-but this is left as an implementation detail.
-
-When a {{File}} object refers to a file on disk,
-user agents must return the {{Blob/type}} of that file,
-and must follow the file type guidelines below:
-
-* User agents must return the {{Blob/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.
-
-
-[Constructor(sequence<BlobPart> fileBits,
- USVString fileName,
- optional FilePropertyBag options),
- Exposed=(Window,Worker), Serializable]
-interface File : Blob {
- readonly attribute DOMString name;
- readonly attribute long long lastModified;
-};
-
-dictionary FilePropertyBag : BlobPropertyBag {
- long long lastModified;
-};
-
-
-{{File}} objects are [=serializable objects=]. Their [=serialization steps=],
-given |value| and |serialized|, are:
-
-1. Set |serialized|.\[[SnapshotState]] to |value|'s [=snapshot state=].
-
-2. Set |serialized|.\[[ByteSequence]] to |value|'s underlying byte sequence.
-
-3. Set |serialized|.\[[Name]] to the value of |value|'s {{File/name}} attribute.
-
-4. Set |serialized|.\[[LastModified]] to the value of |value|'s {{File/lastModified}} attribute.
-
-Their [=deserialization steps=], given |value| and |serialized|, are:
-
-1. Set |value|'s [=snapshot state=] to |serialized|.\[[SnapshotState]].
-
-2. Set |value|'s underlying byte sequence to |serialized|.\[[ByteSequence]].
-
-3. Initialize the value of |value|'s {{File/name}} attribute to |serialized|.\[[Name]].
-
-4. Initialize the value of |value|'s {{File/lastModified}} attribute to
- |serialized|.\[[LastModified]].
-
-
-Constructor
-
-
-The {{File}} constructor is invoked with two or three parameters,
-depending on whether the optional dictionary parameter is used.
-When the {{File()}} constructor is invoked,
-user agents must run the following steps:
-
-1. Let |bytes| be the result of [=processing blob parts=] given {{fileBits}}
- and {{File/File(fileBits, fileName, options)/options}}.
-
-
-2. Let |n| be a new string of the same size as the {{fileName}} argument to the constructor.
- 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.
-
-3. If the optional {{FilePropertyBag}} dictionary argument is used,
- then run the following substeps:
-
- 1. If the {{BlobPropertyBag/type}} member is provided and is not the empty string,
- let |t| be set to the {{BlobPropertyBag/type}} dictionary member.
- If |t| contains any characters outside the range U+0020 to U+007E,
- then set |t| to the empty string and return from these substeps.
- 2. Convert every character in |t| to [=ASCII lowercase=].
- 3. If the {{FilePropertyBag/lastModified}} member is provided,
- let |d| be set to the {{FilePropertyBag/lastModified}} dictionary member.
- If it is not provided,
- set |d| to 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 to
long long values
- representing the number of milliseconds since the
Unix Epoch,
- the {{FilePropertyBag/lastModified}} member could be a {{Date}} object [[ECMA-262]].
-
-4. Return a new {{File}} object |F| such that:
- 2. |F| refers to the |bytes|
byte sequence.
- 3. |F|.{{Blob/size}} is set to the number of total bytes in |bytes|.
- 4. |F|.{{File/name}} is set to |n|.
- 5. |F|.{{Blob/type}} is set to |t|.
- 6. |F|.{{File/lastModified}} is set to |d|.
-
-
-Constructor Parameters
-
-The {{File()}} constructor can be invoked with the parameters below:
-
-
- - A
fileBits sequence
- - which takes any number of the following elements, and in any order:
- * {{BufferSource}} elements.
- * {{Blob}} elements, which includes {{File}} elements.
- * {{USVString}} elements.
-
-
- A
fileName parameter
- - A {{USVString}} parameter representing the name of the file;
- normative conditions for this constructor parameter can be found in [[#file-constructor]].
-
-
- An optional {{FilePropertyBag}} dictionary
-
- which in addition to the members of
- {{BlobPropertyBag}} takes one member:
- * An optional lastModified member,
- which must be a
long long;
- normative conditions for this member are provided in [[#file-constructor]].
-
-
-
-Attributes
-
-
- - name
-
- The name of the file.
- On getting, this must return the name of the file as a string.
- There are numerous file name variations 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 a {{File}} object is created using a constructor,
- further normative conditions for this attribute are found in [[#file-constructor]].
-
-
- lastModified
-
- The last modified date of the file.
- On getting, if user agents can make this information available,
- this must return a
long long set to 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 must return the current date and time
- as a long long representing the number of milliseconds since the Unix Epoch;
- this is equivalent to Date.now() [[ECMA-262]].
- If a {{File}} object is created using a constructor,
- further normative conditions for this attribute are found in [[#file-constructor]].
-
-
-The {{File}} interface is available on objects that expose an attribute of type {{FileList}};
-these objects are defined in HTML [[HTML]].
-The {{File}} interface, which inherits from {{Blob}}, is immutable,
-and thus represents file data that can be read into memory at the time a read operation is initiated.
-User agents must process reads on files that no longer exist at the time of read as errors,
-throwing a {{NotFoundError}} exception
-if using a {{FileReaderSync}} on a Web Worker [[Workers]]
-or firing an {{error!!event}} event
-with the {{error!!attribute}} attribute returning a {{NotFoundError}}.
-
-
- In the examples below, metadata from a file object is displayed meaningfully, and a file object is created with a name and a last modified date.
-
-
- 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})
-
- ...
-
-
-The FileList Interface
-
-Note: The {{FileList}} interface should be considered "at risk"
-since the general trend on the Web Platform is to replace such interfaces
-with the {{Array}} platform object in ECMAScript [[ECMA-262]].
-In particular, this means syntax of the sort filelist.item(0) is at risk;
-most other programmatic use of {{FileList}} is unlikely to be affected by the eventual migration to an {{Array}} type.
-
-This interface is a list of {{File}} objects.
-
-
-[Exposed=(Window,Worker), Serializable]
-interface FileList {
- getter File? item(unsigned long index);
- readonly attribute unsigned long length;
-};
-
-
-{{FileList}} objects are [=serializable objects=]. Their [=serialization steps=],
-given |value| and |serialized|, are:
-
-1. Set |serialized|.\[[Files]] to an empty [=list=].
-
-2. For each |file| in |value|, append the [=sub-serialization=] of |file| to
- |serialized|.\[[Files]].
-
-Their [=deserialization step=], given |serialized| and |value|, are:
-
-1. [=list/For each=] |file| of |serialized|.\[[Files]], add the [=sub-deserialization=] of |file| to |value|.
-
-
- Sample usage typically involves DOM access to the
<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
- }
-
-
-Attributes
-
-
- - length
-
- must return the number of files in the {{FileList}} object.
- If there are no files, this attribute must return 0.
-
-
-
-Methods and Parameters
-
-
- - item(index)
-
- must return the |index|th {{File}} object in the {{FileList}}.
- If there is no |index|th {{File}} object in the {{FileList}},
- then this method must return
null.
-
- index must be treated by user agents
- as value for the position of a {{File}} object in the {{FileList}},
- with 0 representing the first file.
- Supported property indices are the numbers in the range zero
- to one less than the number of {{File}} objects represented by the {{FileList}} object.
- If there are no such {{File}} objects,
- then there are no supported property indices.
-
-
-Note: The {{HTMLInputElement}} interface has a readonly attribute of type {{FileList}},
-which is what is being accessed in the above example.
-Other interfaces with a readonly attribute of type {{FileList}} include the {{DataTransfer}} interface.
-
-
-
-Reading Data
-
-
-The Read Operation
-
-The algorithm below defines a read operation,
-which takes a {{Blob}} and a synchronous flag as input,
-and reads bytes into a byte stream
-which is returned as the |result| of the read operation,
-or else fails along with a failure reason.
-Methods in this specification invoke the read operation
-with the synchronous flag either set or unset.
-
-The synchronous flag determines if a read operation is synchronous or asynchronous,
-and is *unset* by default.
-Methods may set it.
-If it is set,
-the read operation takes place synchronously.
-Otherwise, it takes place asynchronously.
-
-To perform a read operation on a {{Blob}} and the synchronous flag,
-run the following steps:
-
-1. Let |s| be a a new [=/body=],
- |b| be the {{Blob}} to be read from,
- and |bytes| initially set to an empty byte sequence.
- Set the |length| on |s| to the {{Blob/size}} of |b|.
- While there are still bytes to be read in |b|,
- perform the following substeps:
-
- 1. If the synchronous flag is set, follow the steps below:
- 1. Let |bytes| be the byte sequence that results from reading a chunk from |b|.
- If a file read error occurs reading a chunk from |b|,
- return |s| with the error flag set,
- along with a failure reason,
- and terminate this algorithm.
-
- Note: Along with returning failure,
- the synchronous part of this algorithm must return the failure reason that occurred
- for throwing an exception by synchronous methods
- that invoke this algorithm with the synchronous flag set.
-
- 2. If there are no errors,
- push |bytes| to |s|,
- and increment |s|'s |transmitted| [[Fetch]]
- by the number of bytes in |bytes|.
- Reset |bytes| to the empty byte sequence
- and continue reading chunks as above.
-
- 3. When all the bytes of |b| have been read into |s|,
- return |s|
- and terminate this algorithm.
-
- 2. Otherwise, the synchronous flag is unset.
- Return |s| and process the rest of this algorithm asynchronously.
-
- 3. Let |bytes| be the byte sequence that results from reading a chunk from |b|.
- If a file read error occurs reading a chunk from |b|,
- set the error flag on |s|,
- and terminate this algorithm with a failure reason.
-
- Note: The asynchronous part of this algorithm must signal the failure reason that occurred
- for asynchronous error reporting by methods expecting |s|
- and which invoke this algorithm with the synchronous flag unset.
-
- 4. If no file read error occurs,
- push |bytes| to |s|,
- and increment |s|'s |transmitted| [[Fetch]]
- by the number of bytes in |bytes|.
- Reset |bytes| to the empty byte sequence
- and continue reading chunks as above.
-
-To perform an annotated task read operation
-on a {{Blob}} |b|,
-perform the steps below:
-
-1. Perform a read operation on |b| with the synchronous flag unset,
- along with the additional steps below.
-2. If the read operation terminates with a failure reason,
- queue a task to process read error with the failure reason
- and terminate this algorithm.
-3. When the first chunk is being pushed to the [=/body=] |s| during the read operation,
- queue a task to process read.
-4. Once the [=/body=] |s| from the read operation has at least one chunk read into it,
- or there are no chunks left to read from |b|,
- queue a task to process read data.
- Keep queuing tasks to process read data
- for every chunk read or every 50ms,
- whichever is *least frequent*.
-5. When all of the chunks from |b| are read into the [=/body=] |s| from the read operation,
- queue a task to process read EOF.
-
-Use the file reading task source for all these tasks.
-
-
-
-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.
-
-
-The FileReader API
-
-
-[Constructor, Exposed=(Window,Worker)]
-interface FileReader: EventTarget {
-
- // async read methods
- void readAsArrayBuffer(Blob blob);
- void readAsBinaryString(Blob blob);
- void readAsText(Blob blob, optional DOMString label);
- void readAsDataURL(Blob blob);
-
- void abort();
-
- // states
- const unsigned short EMPTY = 0;
- const unsigned short LOADING = 1;
- const unsigned short DONE = 2;
-
-
- readonly attribute unsigned short readyState;
-
- // File or Blob data
- readonly attribute (DOMString or ArrayBuffer)? result;
-
- readonly attribute DOMException? error;
-
- // event handler content attributes
- attribute EventHandler onloadstart;
- attribute EventHandler onprogress;
- attribute EventHandler onload;
- attribute EventHandler onabort;
- attribute EventHandler onerror;
- attribute EventHandler onloadend;
-
-};
-
-
-
-Constructor
-
-When the {{FileReader()}} constructor is invoked,
-the user agent must return a new {{FileReader}} object.
-
-In environments where the global object is represented by a {{Window}} or a {{WorkerGlobalScope}} object,
-the {{FileReader}} constructor must be available.
-
-
-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:
-
-
-
-
-FileReader States
-
-The {{FileReader}} object can be in one of 3 states.
-The readyState attribute,
-on getting,
-must return the current state,
-which must be one of the following values:
-
-
- - EMPTY (numeric value 0)
-
- The {{FileReader}} object has been constructed,
- and there are no pending reads.
- None of the read methods have been called.
- This is the default state of a newly minted {{FileReader}} object,
- until one of the read methods have been called on it.
-
- LOADING (numeric value 1)
-
- A {{File}} or {{Blob}} is being read.
- One of the read methods is being processed,
- and no error has occurred during the read.
-
- DONE (numeric value 2)
-
- The entire {{File}} or {{Blob}} has been read into memory,
- OR a file read error occurred,
- OR the read was aborted using {{FileReader/abort()}}.
- The {{FileReader}} is no longer reading a {{File}} or {{Blob}}.
- If {{FileReader/readyState}} is set to {{FileReader/DONE}}
- it means at least one of the read methods have been called on this {{FileReader}}.
-
-
-
-Reading a File or Blob
-
-The {{FileReader}} interface makes available several asynchronous read methods--
-{{FileReader/readAsArrayBuffer()}}, {{FileReader/readAsBinaryString()}}, {{FileReader/readAsText()}} and {{FileReader/readAsDataURL()}},
-which read files into memory.
-If multiple concurrent read methods are called on the same {{FileReader}} object,
-user agents must throw an {{InvalidStateError}} on any of the read methods that occur
-when {{FileReader/readyState}} = {{FileReader/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.)
-
-
-The {{FileReader/result}} attribute
-
-On getting, the result attribute returns a {{Blob}}'s data
-as a {{DOMString}}, or as an {{ArrayBuffer}}, or null,
-depending on the read method that has been called on the {{FileReader}},
-and any errors that may have occurred.
-
-The list below is normative for the {{FileReader/result}} attribute
-and is the conformance criteria for this attribute:
-
-* On getting,
- if the {{FileReader/readyState}} is {{FileReader/EMPTY}}
- (no read method has been called)
- then the {{FileReader/result}} attribute must return null.
-* On getting,
- if an error in reading the {{File}} or {{Blob}} has occurred
- (using *any* read method)
- then the {{FileReader/result}} attribute must return null.
-* On getting, if the {{FileReader/readAsDataURL()}} read method is used,
- the {{FileReader/result}} attribute must return a {{DOMString}}
- that is a Data URL [[!RFC2397]] encoding of the {{File}} or {{Blob}}'s data.
-* On getting, if the {{FileReader/readAsBinaryString()}} read method is called
- and no error in reading the {{File}} or {{Blob}} has occurred,
- then the {{FileReader/result}} attribute must return a {{DOMString}}
- representing the {{File}} or {{Blob}}'s data as a binary string,
- in which every byte is represented by a code unit of equal value [0...255].
-* On getting, if the {{FileReader/readAsText()}} read method is called
- and no error in reading the {{File}} or {{Blob}} has occurred,
- then the {{FileReader/result}} attribute must return a string
- representing the {{File}} or {{Blob}}'s data as a text string,
- and should decode the string into memory in the format specified by the encoding determination as a {{DOMString}}.
-* On getting, if the {{FileReader/readAsArrayBuffer()}} read method is called
- and no error in reading the {{File}} or {{Blob}} has occurred,
- then the {{FileReader/result}} attribute must return an {{ArrayBuffer}} object.
-
-
-The {{FileReader/readAsDataURL()}} method
-
-When the readAsDataURL(blob) method is called,
-the user agent must run the steps below.
-
-1. If {{FileReader/readyState}} = {{FileReader/LOADING}}
- throw an {{InvalidStateError}} exception and terminate this algorithm.
-3. Otherwise set {{FileReader/readyState}} to {{FileReader/LOADING}}.
-4. Initiate an annotated task read operation using the blob argument as |input|
- and handle tasks queued on the file reading task source per below.
-5. To process read error with a failure reason,
- proceed to [[#dfn-error-steps]].
-6. To process read fire a progress event called {{loadstart}} at the context object.
-7. To process read data fire a progress event called {{progress}} at the context object.
-8. To process read EOF run these substeps:
- 1. Set {{FileReader/readyState}} to {{FileReader/DONE}}.
- 2. Set the {{FileReader/result}} attribute to the [=/body=] returned by the read operation as a DataURL [[!RFC2397]];
- on getting, the {{FileReader/result}} attribute returns the blob as a Data URL [[!RFC2397]].
-
- * Use the blob's {{Blob/type}} attribute as part of the Data URL if it is available
- in keeping with the Data URL specification [[!RFC2397]].
- * If the {{Blob/type}} attribute is not available on the blob return a Data URL without a media-type. [[!RFC2397]].
- Data URLs that do not have media-types [[RFC2046]] must be treated as plain text by conforming user agents. [[!RFC2397]].
- 3. Fire a progress event called {{load}} at the context object.
- 4. Unless {{FileReader/readyState}} is {{FileReader/LOADING}}
- fire a progress event called {{loadend}} at the context object.
- If {{FileReader/readyState}} is {{FileReader/LOADING}} do NOT fire {{loadend}} at the context object.
-9. Terminate this algorithm.
-
-
-The {{FileReader/readAsText()}} method
-
-The {{FileReader/readAsText()}} method can be called with an optional parameter,
-label,
-which is a {{DOMString}} argument that represents the label of an encoding [[!Encoding]];
-if provided, it must be used as part of the encoding determination used when processing this method call.
-
-When the readAsText(blob, label) method is called,
-the user agent must run the steps below.
-
-1. If {{FileReader/readyState}} = {{FileReader/LOADING}} throw an {{InvalidStateError}} and terminate this algorithm.
-3. Otherwise set {{FileReader/readyState}} to {{FileReader/LOADING}}.
-4. Initiate an annotated task read operation using the blob argument as |input|
- and handle tasks queued on the file reading task source per below.
-5. To process read error with a failure reason,
- proceed to the [[#dfn-error-steps]].
-6. To process read fire a progress event called {{loadstart}} at the context object.
-7. To process read data fire a progress event called {{progress}} at the context object.
-8. To process read EOF run these substeps:
- 1. Set {{FileReader/readyState}} to {{FileReader/DONE}}
- 2. Set the {{FileReader/result}} attribute to the [=/body=] returned by the read operation,
- represented as a string in a format determined by the encoding determination.
- 3. Fire a progress event called {{load}} at the context object.
- 4. Unless {{FileReader/readyState}} is {{FileReader/LOADING}}
- fire a progress event called {{loadend}} at the context object.
- If {{FileReader/readyState}} is {{FileReader/LOADING}}
- do NOT fire {{loadend}} at the context object.
-9. Terminate this algorithm.
-
-
-The {{FileReader/readAsArrayBuffer()}} method
-
-When the readAsArrayBuffer(blob) method is called,
-the user agent must run the steps below.
-
-1. If {{FileReader/readyState}} = {{FileReader/LOADING}} throw an {{InvalidStateError}} exception and terminate this algorithm.
-3. Otherwise set {{FileReader/readyState}} to {{FileReader/LOADING}}.
-4. Initiate an annotated task read operation using the blob argument as |input|
- and handle tasks queued on the file reading task source per below.
-5. To process read error with a failure reason,
- proceed to the [[#dfn-error-steps]].
-6. To process read fire a progress event called {{loadstart}} at the context object.
-7. To process read data fire a progress event called {{progress}} at the context object.
-8. To process read EOF run these substeps:
- 1. Set {{FileReader/readyState}} to {{FileReader/DONE}}
- 2. Set the {{FileReader/result}} attribute to the [=/body=] returned by the read operation as an {{ArrayBuffer}} object.
- 3. Fire a progress event called {{load}} at the context object.
- 4. Unless {{FileReader/readyState}} is {{FileReader/LOADING}}
- fire a progress event called {{loadend}} at the context object.
- If {{FileReader/readyState}} is {{FileReader/LOADING}}
- do NOT fire {{loadend}} at the context object.
-9. Terminate this algorithm.
-
-
-The {{FileReader/readAsBinaryString()}} method
-
-When the readAsBinaryString(blob) method is called,
-the user agent must run the steps below.
-
-1. If {{FileReader/readyState}} = {{FileReader/LOADING}} throw an {{InvalidStateError}} exception and terminate this algorithm.
-3. Otherwise set {{FileReader/readyState}} to {{FileReader/LOADING}}.
-4. Initiate an annotated task read operation using the blob argument as |input|
- and handle tasks queued on the file reading task source per below.
-5. To process read error with a failure reason,
- proceed to the [[#dfn-error-steps]].
-6. To process read fire a progress event called {{loadstart}} at the context object.
-7. To process read data fire a progress event called {{progress}} at the context object.
-8. To process read EOF run these substeps:
- 1. Set {{FileReader/readyState}} to {{FileReader/DONE}}
- 2. Set the {{FileReader/result}} attribute to the [=/body=] returned by the read operation as a binary string.
- 3. Fire a progress event called {{load}} at the context object.
- 4. Unless {{FileReader/readyState}} is {{FileReader/LOADING}}
- fire a progress event called {{loadend}} at the context object.
- If {{FileReader/readyState}} is {{FileReader/LOADING}}
- do NOT fire {{loadend}} at the context object.
-9. Terminate this algorithm.
-
-
- The use of {{FileReader/readAsArrayBuffer()}} is preferred over
- {{FileReader/readAsBinaryString()}}, which is provided for backwards
- compatibility.
-
-
-
-Error Steps
-
-These error steps are to process read error with a failure reason.
-
-1. Set the context object's {{FileReader/readyState}} to {{FileReader/DONE}}
- and {{FileReader/result}} to null if it is not already set to null.
-2. Set the {{error!!attribute}} attribute on the context object;
- on getting, the {{error!!attribute}} attribute must be a a {{DOMException}} object
- that corresponds to the failure reason.
- Fire a progress event called {{error!!event}} at the context object.
-3. Unless {{FileReader/readyState}} is {{FileReader/LOADING}},
- fire a progress event called {{loadend}} at the context object.
- If {{FileReader/readyState}} is {{FileReader/LOADING}}
- do NOT fire {{loadend}} at the context object.
-4. Terminate the algorithm for any read method.
-
-
-The abort() method
-
-When the abort() method is called,
-the user agent must run the steps below:
-
-1. If {{FileReader/readyState}} = {{FileReader/EMPTY}}
- or if {{FileReader/readyState}} = {{FileReader/DONE}}
- set {{FileReader/result}} to null
- and terminate this algorithm.
-2. If {{FileReader/readyState}} = {{FileReader/LOADING}}
- set {{FileReader/readyState}} to {{FileReader/DONE}}
- and {{FileReader/result}} to null.
-3. If there are any tasks from the context object
- on the file reading task source in an affiliated task queue,
- then remove those tasks from that task queue.
-4. Terminate the algorithm for the read method being processed.
-5. Fire a progress event called {{abort}}.
-6. Fire a progress event called {{loadend}}.
-
-
-Blob Parameters
-
-The asynchronous read methods,
-the synchronous read methods, and
-URL.{{URL/createObjectURL()}}
-take a {{Blob}} parameter.
-This section defines this parameter.
-
-
- - blob
-
- This is a {{Blob}} argument
- and must be a reference to a single {{File}} in a {{FileList}}
- or a {{Blob}} argument not obtained from the underlying OS file system.
-
-
-
-
-Determining Encoding
-
-When reading {{Blob}} objects using the {{FileReader/readAsText()}} read method,
-the following encoding determination steps must be followed:
-
-1. Let |encoding| be null.
-2. If the {{FileReader/readAsText()/label}} argument is present when calling the method,
- set |encoding| to the result of the getting an encoding from {{FileReader/readAsText()/label}}.
-3. If the getting an encoding steps above return failure,
- then set |encoding| to null.
-4. If |encoding| is null,
- and the {{FileReader/readAsText()/blob}} argument's {{Blob/type}} attribute is present,
- and it uses a Charset Parameter [[RFC2046]],
- set |encoding| to the result of getting an encoding
- for the portion of the Charset Parameter that is a label of an encoding.
-
-
- If
blob has a {{Blob/type}} attribute of
text/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.
-
blob using fallback encoding |encoding|,
- and return the result.
- On getting, the {{FileReader/result}} attribute of the {{FileReader}} object
- returns a string in |encoding| format.
- The synchronous {{FileReaderSync/readAsText()}} method of the {{FileReaderSync}} object
- returns a string in |encoding| format.
-
-
-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]]
-
-
-Event Summary
-
-The following are the events that are fired at {{FileReader}} objects.
-
-
-
-
- | Event name
- | Interface
- | Fired when…
- |
-
- | loadstart
- | {{ProgressEvent}}
- | When the read starts.
- |
- | progress
- | {{ProgressEvent}}
- | While reading (and decoding) blob
- |
- | abort
- | {{ProgressEvent}}
- | When the read has been aborted.
- For instance, by invoking the {{FileReader/abort()}} method.
- |
- | error
- | {{ProgressEvent}}
- | When the read has failed (see file read errors).
- |
- | load
- | {{ProgressEvent}}
- | When the read has successfully completed.
- |
- | loadend
- | {{ProgressEvent}}
- | When the request has completed (either in success or failure).
- |
-
-
-Summary of Event Invariants
-
-*This section is informative.*
-
-The following are invariants applicable to event firing
-for a given asynchronous read method in this specification:
-
-1. Once a {{loadstart}} has been fired,
- a corresponding {{loadend}} fires at completion of the read,
- UNLESS any of the following are true:
-
- * the read method has been cancelled using {{FileReader/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}} event initiates a new read.
-
- Note: The events {{loadstart}} and {{loadend}} are not coupled in a one-to-one manner.
-
-
- This example showcases "read-chaining":
- initiating another read from within an event handler while the "first" read continues processing.
-
-
- // In code of the sort...
- reader.readAsText(file);
- reader.onload = function(){reader.readAsText(alternateFile);}
-
- .....
-
- //... the loadend event must not fire for the first read
-
- reader.readAsText(file);
- reader.abort();
- reader.onabort = function(){reader.readAsText(updatedFile);}
-
- //... the loadend event must not fire for the first read
-
-
blob has been completely read into memory.
-3. No {{progress}} event fires before {{loadstart}}.
-4. No {{progress}} event fires after any one of {{abort}}, {{load}}, and {{error!!event}} have fired.
- At most one of {{abort}}, {{load}}, and {{error!!event}} fire for a given read.
-5. No {{abort}}, {{load}}, or {{error!!event}} event fires after {{loadend}}.
-
-
-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).
-
-
-The {{FileReaderSync}} API
-
-This interface provides methods to synchronously read
-{{File}} or {{Blob}} objects into memory.
-
-
-[Constructor, Exposed=(DedicatedWorker,SharedWorker)]
-interface FileReaderSync {
- // Synchronously return strings
-
- ArrayBuffer readAsArrayBuffer(Blob blob);
- DOMString readAsBinaryString(Blob blob);
- DOMString readAsText(Blob blob, optional DOMString label);
- DOMString readAsDataURL(Blob blob);
-};
-
-
-
-Constructors
-
-When the {{FileReaderSync()}} constructor is invoked,
-the user agent must return a new {{FileReaderSync}} object.
-
-In environments where the global object is represented by a {{WorkerGlobalScope}} object,
-the {{FileReaderSync}} constructor must be available.
-
-
-The {{FileReaderSync/readAsText()}} method
-
-When the readAsText(blob, label) method is called,
-the following steps must be followed:
-
-1. Initiate a read operation using the blob argument,
- and with the synchronous flag *set*.
- If the read operation returns failure,
- throw the appropriate exception as defined in [[#dfn-error-codes]].
- Terminate this algorithm.
-1. If no error has occurred,
- return the |result| of the read operation represented as a string
- in a format determined through the encoding determination algorithm.
-
-
-The {{FileReaderSync/readAsDataURL()}} method
-
-When the readAsDataURL(blob) method is called,
-the following steps must be followed:
-
-1. Initiate a read operation using the blob argument,
- and with the synchronous flag *set*.
- If the read operation returns failure,
- throw the appropriate exception as defined in [[#dfn-error-codes]].
- Terminate this algorithm.
-1. If no error has occurred, return the |result| of the read operation
- as a Data URL [[!RFC2397]] subject to the considerations below:
-
- * Use the blob's {{Blob/type}} attribute as part of the Data URL if it is available
- in keeping with the Data URL specification [[!RFC2397]].
- * If the {{Blob/type}} attribute is not available on the blob return a Data URL without a media-type. [[!RFC2397]].
- Data URLs that do not have media-types [[RFC2046]] must be treated as plain text by conforming user agents. [[!RFC2397]].
-
-
-The {{FileReaderSync/readAsArrayBuffer()}} method
-
-When the readAsArrayBuffer(blob) method is called,
-the following steps must be followed:
-
-1. Initiate a read operation using the blob argument,
- and with the synchronous flag *set*.
- If the read operation returns failure,
- throw the appropriate exception as defined in [[#dfn-error-codes]].
- Terminate this algorithm.
-1. If no error has occurred, return the |result| of the read operation as an {{ArrayBuffer}}.
-
-
-The {{FileReaderSync/readAsBinaryString()}} method
-
-When the readAsBinaryString(blob) method is called,
-the following steps must be followed:
-
-1. Initiate a read operation using the blob argument,
- and with the synchronous flag *set*.
- If the read operation returns failure,
- throw the appropriate exception as defined in [[#dfn-error-codes]].
- Terminate this algorithm.
-1. If no error has occurred, return the |result| of the
- read operation as an binary string.
-
-
- The use of {{FileReaderSync/readAsArrayBuffer()}} is preferred over
- {{FileReaderSync/readAsBinaryString()}}, which is provided for
- backwards compatibility.
-
-
-
-Errors and Exceptions
-
-File read errors can occur when reading files from the underlying filesystem.
-The list below of potential error conditions is *informative*.
-
-* The {{File}} or {{Blob}} being accessed may not exist
- at the time one of the asynchronous read methods or synchronous read methods are called.
- This may be due to it having been moved or deleted after a reference to it was acquired
- (e.g. concurrent modification with another application).
- See {{NotFoundError}}.
-* A {{File}} or {{Blob}} may be unreadable.
- This may be due to permission problems that occur after a reference to a {{File}} or {{Blob}} has been acquired
- (e.g. concurrent lock with another application).
- Additionally, the snapshot state may have changed.
- See {{NotReadableError}}.
-* User agents MAY determine that some files are unsafe for use within Web applications.
- A file may change on disk since the original file selection,
- thus resulting in an invalid read.
- Additionally, some file and directory structures may be considered restricted by the underlying filesystem;
- attempts to read from them may be considered a security violation.
- See [[#security-discussion]] and {{SecurityError}}.
-
-
-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 a read operation to return failure
-or queue a task to process read error
-is called a failure reason.
-
-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 {{error!!attribute}} attribute must return a {{NotFoundError}} exception
- and synchronous read methods must throw a {{NotFoundError}} exception.
- |
- | {{SecurityError}}
- | If:
- * it is determined that certain files are unsafe for access within a Web application, this is the UnsafeFile failure reason.
- * it is determined that too many read calls are being made on {{File}} or {{Blob}} resources, this is the TooManyReads failure reason.
-
- For asynchronous read methods the {{error!!attribute}} attribute may return a {{SecurityError}} exception
- and synchronous read methods may throw a {{SecurityError}} exception.
-
- This is a security error to be used in situations not covered by any other failure reason.
- |
- | {{NotReadableError}}
- | If:
- * the snapshot state of a {{File}} or a {{Blob}} does not match the state of the underlying storage,
- this is the SnapshotState failure reason.
- * the {{File}} or {{Blob}} cannot be read,
- typically due due to permission problems that occur after a snapshot state has been established
- (e.g. concurrent lock on the underlying storage with another application)
- then this is the FileLock failure reason.
-
- For asynchronous read methods the {{error!!attribute}} attribute must return a {{NotReadableError}} exception
- and synchronous read methods must throw a {{NotReadableError}} exception.
- |
-
-
-A URL for Blob and File reference
-
-This section defines a [=url/scheme=] for a [=/URL=] used to refer to {{Blob}} objects (and {{File}} objects).
-
-Note: other specifications, such as [[MEDIA-SOURCE]] extend this scheme to also refer to other types of objects.
-
-
-Introduction
-
-*This section is informative.*
-
-[=Blob URL|Blob (or object) URLs=] are URLs like
-`blob:http://example.com/550e8400-e29b-41d4-a716-446655440000`.
-This enables integration of {{Blob}}s and {{File}}s with other Web Platform 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,
-{{URL/createObjectURL(blob)}} and {{URL/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.
-
-
-Model
-
-Each user agent must maintain a blob URL store.
-A [=blob URL store=] is a [=map=]
-where [=map/keys=] are [=valid URL strings=]
-and [=map/values=] are [=blob URL Entries=].
-
-A blob URL entry consists of
-an object (typically a {{Blob}},
-but other specs can extend this to refer to other types of objects),
-and an environment (an [=environment settings object=]).
-
-[=map/Keys=] in the [=blob URL store=] (also known as blob URLs)
-are [=valid URL strings=] that when [=URL parser|parsed=]
-result in a [=/URL=] with a [=url/scheme=] equal to "`blob`",
-an [=empty host=], and a [=url/path=] consisting of one element itself also a [=valid URL string=].
-
-
-To
-generate a new blob URL, run the following steps:
-
-1. Let |result| be the empty string.
-1. Append the string "`blob:`" to |result|.
-1. Let |settings| be the [=current settings object=]
-1. Let |origin| be |settings|'s [=environment settings object/origin=].
-1. Let |serialized| be the
ASCII serialization of |origin|.
-1. If |serialized| is "`null`", set it to an implementation-defined value.
-1. Append |serialized| to |result|.
-1. Append U+0024 SOLIDUS (`/`) to |result|.
-1. Generate a UUID [[!RFC4122]] as a string and append it to |result|.
-1. Return |result|.
-
-
- An example of a blob URL that can be generated by this algorithm is
- `blob:https://example.org/9115d58c-bcda-ff47-86e5-083e9a215304`1.
-
-
-
-To
-add an entry to the blob URL store for a given |object|,
-run the following steps:
-
-1. Let |store| be the user agent's [=blob URL store=].
-1. Let |url| be the result of [=generating a new blob URL=].
-1. Let |entry| be a new [=blob URL entry=] consisting of |object| and the [=current settings object=].
-1. [=map/Set=] |store|[|url|] to |entry|.
-1. Return |url|.
-
-
-
-
-To
-remove an entry from the blob URL store for a given |url|,
-run the following steps:
-
-1. Let |store| be the user agent's [=blob URL store=];
-1. Let |url string| be the result of [=URL serializer|serializing=] |url|.
-1. [=map/Remove=] |store|[|url string|].
-
-
-
-
-Dereferencing Model for blob URLs
-
-
-To resolve a blob URL given a |url| (a [=URL=]), run the following steps:
-
-1. [=Assert=]: |url|'s [=url/scheme=] is "`blob`".
-1. Let |store| be the user agent's [=blob URL store=].
-1. Let |url string| be the result of [=URL serializer|serializing=] |url| with the *exclude fragment flag* set.
-1. If |store|[|url string|] [=map/exists=], return |store|[|url string|]; otherwise return failure.
-
-
-
-Futher requirements for the parsing an fetching model for [=blob URLs=] are defined in the [[!URL]] and [[!Fetch]] specifications.
-
-
-Origin of blob URLs
-
-
-To resolve the origin of a blob URL given a |url| (a [=URL=]), run the following steps:
-
-1. [=Assert=]: |url|'s [=url/scheme=] is "`blob`".
-1. Let |entry| be the result of [=blob URL/resolve|resolving=] |url|.
-1. If |entry| is not failure, return |entry|'s [=blob URL entry/environment=]'s [=environment settings object/origin=].
-1. Let |nested url| be the result of [=URL parser|parsing=] |url|'s [=url/path=][0].
-1. Return a new [=opaque origin=], if |nested url| is failure, and |nested url|'s [=url/origin=] otherwise.
-
-
-
-Note: The effect of this algorithm is that 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.
-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.
-
-Issue: The [[URL]] spec should be updated to refer to this algorithm to resolve the origin of a blob URL when the URL is first parsed.
-This is tracked in issue #63 and in
-whatwg/url#127.
-
-
-Lifetime of blob URLs
-
-This specification extends the [=unloading document cleanup steps=] with the following steps:
-
-1. Let |environment| be the {{Document}}'s [=relevant settings object=].
-1. Let |store| be the user agent's [=blob URL store=];
-1. Remove from |store| any entries for which the [=map/value=]'s [=blob URL entry/environment=] is equal to |environment|.
-
-Issue: This needs a similar hook when a worker is unloaded.
-
-
-Creating and Revoking a blob URL
-
-Blob URLs are created and revoked using static methods exposed on the {{URL}} object.
-Revocation of a blob URL decouples the blob URL from the resource it refers to,
-and if it is dereferenced after it is revoked,
-user agents must act as if a network error has occurred.
-This section describes a supplemental interface to the URL specification [[URL]]
-and presents methods for blob URL creation and revocation.
-
-
-[Exposed=(Window,DedicatedWorker,SharedWorker)]
-partial interface URL {
- static DOMString createObjectURL(Blob blob);
- static void revokeObjectURL(DOMString url);
-};
-
-
-
-The createObjectURL(|blob|) static method must
-return the result of [=adding an entry to the blob URL store=] for |blob|.
-
-
-
-The revokeObjectURL(|url|) static method must run these steps:
-
-1. Let |url record| be the result of [=URL parser|parsing=] |url|.
-1. If |url record|'s [=url/scheme=] is not "`blob`", return.
-1. Let |origin| be the result of [=resolving the origin=] of |url record|.
-1. Let |settings| be the [=current settings object=].
-1. If |origin| is not [=same origin=] with |settings|'s [=environment settings object/origin=], return.
-1. [=Remove an entry from the Blob URL Store=] for |url|.
-
-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 is 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.
-
-
-
- In the example below,
-
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.{{revokeObjectURL()}} call
- ensures that subsequent dereferencing of
myurl
- results in a the user agent acting as if a
network error has occurred.
-
-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()}}--
-see [[#lifeTime]].
-
-This section gives sample usage of creation and revocation of blob URLs with explanations.
-
-
- In the example below, two <{img}> elements [[HTML]] refer to the same
blob URL:
-
-
- url = URL.createObjectURL(blob);
- img1.src = url;
- img2.src = url;
-
-
- In the example below,
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);
- }
-
-
URL.{{revokeObjectURL()}}.
-
-
-Security and Privacy Considerations
-
-*This section is informative.*
-
-This specification allows web content to read files from the underlying file system,
-as well as provides a means for files to be accessed by unique identifiers,
-and as such is subject to some security considerations.
-This specification also assumes that the primary user interaction is with the <input type="file"/> element of HTML forms [[HTML]],
-and that all files that are being read by {{FileReader}} objects have first been selected by the user.
-Important security considerations include preventing malicious file selection attacks (selection looping),
-preventing access to system-sensitive files,
-and guarding against modifications of files on disk after a selection has taken place.
-
-* Preventing selection looping.
- During file selection, a user may be bombarded with the file picker associated with <input type="file"/>
- (in a "must choose" loop that forces selection before the file picker is dismissed)
- and a user agent may prevent file access to any selections by making the {{FileList}} object returned be of size 0.
-* System-sensitive files
- (e.g. files in /usr/bin, password files, and other native operating system executables)
- typically should not be exposed to web content,
- and should not be accessed via blob URLs.
- User agents may throw a {{SecurityError}} exception for synchronous read methods,
- or return a {{SecurityError}} exception for asynchronous reads.
-
-Issue: This section is provisional; more security data may supplement this in subsequent drafts.
-
-
-Requirements and Use Cases
-
-This section covers what the requirements are for this API,
-as well as illustrates some use cases.
-This version of the API does not satisfy all use cases;
-subsequent versions may elect to address these.
-
-* Once a user has given permission,
- user agents should provide the ability to read and parse data directly from a local file programmatically.
-
-
- A lyrics viewer.
- User wants to read song lyrics from songs in his plist file.
- User browses for plist file.
- File is opened, read, parsed, and presented to the user as a sortable, actionable list within a web application.
- User can select songs to fetch lyrics.
- User uses the "browse for file" dialog.
-
-* Data should be able to be stored locally so that it is available for later use,
- which is useful for offline data access for web applications.
-
-
- A Calendar App.
- User's company has a calendar.
- User wants to sync local events to company calendar,
- marked as "busy" slots (without leaking personal info).
- User browses for file and selects it.
- The text/calendar file is parsed in the browser,
- allowing the user to merge the files to one calendar view.
- The user wants to then save the file back to his local calendar file (using "Save As"?).
- The user can also send the integrated calendar file back to the server calendar store asynchronously.
-
-* User agents should provide the ability to save a local file programmatically given an amount of data and a file name.
-
- Note: While this specification doesn't provide an explicit API call to trigger downloads,
- the HTML5 specification has addressed this.
- The <{a/download}> attribute of the <{a}> element initiates a download,
- saving a {{File}} with the name specified.
- The combination of this API and the <{a/download}> attribute on <{a}> elements
- allows for the creation of files within web applications,
- and the ability to save them locally.
-
-
- A Spreadsheet App.
- User interacts with a form, and generates some input.
- The form then generates a CSV (Comma Separated Variables) output for the user to import into a spreadsheet,
- and uses "Save...".
- The generated output can also be directly integrated into a web-based spreadsheet,
- and uploaded asynchronously.
-
-* User agents should provide a streamlined programmatic ability to send data from a file to a remote server
- that works more efficiently than form-based uploads today.
-
-
- A Video/Photo Upload App.
- User is able to select large files for upload,
- which can then be "chunk-transfered" to the server.
-
-* User agents should provide an API exposed to script that exposes the features above.
- The user is notified by UI anytime interaction with the file system takes place,
- giving the user full ability to cancel or abort the transaction.
- The user is notified of any file selections,
- and can cancel these.
- No invocations to these APIs occur silently without user intervention.
-
-
-Acknowledgements
-
-This specification was originally developed by the SVG Working Group. Many thanks to Mark Baker and Anne van Kesteren for their feedback.
-
-Thanks to Robin Berjon and Jonas Sicking 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