File API

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

• ArrayBuffer [TypedArrays] elements.

• ArrayBufferView [TypedArrays] elements.

• Blob elements.

• DOMString [WebIDL] elements.

An optional BlobPropertyBag

which takes one member:

• type, the ASCII-encoded string in lower case representing the media type of the Blob. Normative conditions for this member are provided in the Blob constructor steps.

5.3.1. The slice method

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

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 slice with start normalized according to the following:

   1. If the optional start parameter is not used as a parameter when making this call, let relativeStart be 0.

   2. If start is negative, let relativeStart be max((size + start), 0).

   3. Else, let relativeStart be min(start, size).

3. The optional end parameter is a value for the end point of a slice call. User agents must process slice with end normalized according to the following:

   1. If the optional end parameter is not used as a parameter when making this call, let relativeEnd be size.

   2. If end is negative, let relativeEnd be max((size + end), 0)

   3. Else, let relativeEnd be min(end, size)

4. 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 slice with contentType normalized according to the following:

   1. If the contentType parameter is not provided, let relativeContentType be set to the empty string .

   2. Else let relativeContentType be set to contentType and run the 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 lower case using the "Converting a string to ASCII lowercase" algorithm.

5. Let span be max((relativeEnd - relativeStart), 0).

6. Return a new Blob object S with the following characteristics:

   1. S has a readability state equal to that of O's readability state.

      Note

      The readability state of the context object is retained by the Blob object returned by the slice call; this has implications on whether the returned Blob is actually usable for read operations or as a Blob URL.

   2. S refers to span consecutive bytes from O, beginning with the byte at byte-order position relativeStart.

   3. S.size = span.

   4. S.type = relativeContentType.

      Note

      The type t of a Blob is considered a parsable MIME type if the ASCII-encoded string representing the Blob object's type, when converted to a byte sequence, does not return undefined for the parse MIME type algorithm [MIMESNIFF].

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

5.3.2. The close method

The close method is said to close a Blob, and must act as follows on the Blob on which the method has been called:

1. If the readability state of the context object is CLOSED, terminate this algorithm.

2. Otherwise, set the readability state of the context object to CLOSED.

3. If the context object has an entry in the Blob URL Store, remove the entry that corresponds to the context object.

7.1. Attributes

length

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

7.2. Methods and Parameters

item(index)

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

index must be treated by user agents as value for the position of a File object in the FileList, with 0 representing the first file. Supported property indices [WebIDL] 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 [WebIDL].

8.3.1. Constructors

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

In environments where the global object is represented by a Window or a WorkerGlobalScope object, the FileReader constructor must be available.

8.3.2. Event Handler Attributes

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

8.3.3. FileReader States

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

EMPTY (numeric value 0)

The FileReader object has been constructed, and there are no pending reads. None of the read methods have been called. This is the default state of a newly minted FileReader object, until one of the read methods have been called on it.

LOADING (numeric value 1)

A File or Blob is being read. One of the read methods is being processed, and no error has occurred during the read.

DONE (numeric value 2)

The entire File or Blob has been read into memory, OR a file error occurred during read, OR the read was aborted using abort(). The FileReader is no longer reading a File or Blob. If readyState is set to DONE it means at least one of the read methods have been called on this FileReader.

8.3.4. Reading a File or Blob

8.4. Determining Encoding

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

1. Let encoding be null

2. If the label argument is present when calling the method, set encoding to the result of "getting an encoding" using the Encoding Specification [Encoding Specification] for label.

3. If the "getting an encoding" steps above return failure, then set encoding to null.

4. If encoding is null, and the blob argument's type attribute is present, and it uses a Charset Parameter [RFC2046], set encoding to the result of "getting an encoding" using the Encoding Specification [Encoding Specification] for the portion of the Charset Parameter that is a label of an encoding.

   Example

   If blob has a 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.

5. If the "getting an encoding" steps above return failure, then set encoding to null.

6. If encoding is null, then set encoding to utf-8.

7. "Decode" [Encoding Specification] this blob using fallback encoding encoding, and return the result. On getting, the result attribute of the FileReader object returns a string in encoding format. The synchronous readAsText method of the FileReaderSync object returns a string in encoding format.

8.5.10. 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 [DOM4]

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

• The term "fire an event" is defined in DOM Core [DOM4]. Progress Events are defined in Progress Events [ProgressEvents].

8.6.1. The FileReaderSync API

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

  [Constructor, Exposed=Worker]
  interface FileReaderSync {
    // Synchronously return strings
    ArrayBuffer readAsArrayBuffer(Blob blob); 
    DOMString readAsText(Blob blob, optional DOMString label);
    DOMString readAsDataURL(Blob blob);
  };
  

9.1. Throwing an Exception or Returning an Error

This section is normative. Error conditions can arise when reading a File or a Blob.

The read operation can terminate due to error conditions when reading a File or a Blob; the particular error condition that causes 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 DOMError object [DOM4] 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.

10.1. Requirements for a New Scheme

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

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

  This scheme should have defined response codes, so that web applications can respond to scenarios where the resource is not found, or raises an error, etc.

• This scheme should have an origin policy and a lifetime stipulation, to allow safe access to binary data from web applications.

  URLs in this scheme should be used as a references to "in-memory" Blobs, and also be re-used elsewhere on the platform to refer to binary resources (e.g. for video-conferencing [WebRTC]). URLs in this scheme are designed for impermanence, since they will be typically used to access "in memory" resources.

• Developers should have the ability to revoke URLs in this scheme, so that they no longer refer to Blob objects. This includes scenarios where file references are no longer needed by a program, but also other uses of Blob objects. Consider a scenario where a Blob object can be exported from a drawing program which uses the canvas element and API [HTML]. A snapshot of the drawing can be created by exporting a Blob. This scheme can be used with the img [HTML] element to display the snapshot; if the user deletes the snapshot, any reference to the snapshot in memory via a URL should be invalid, and hence the need to be able to revoke such a URL.

10.2. Discussion of Existing Schemes

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

• HTTP could be repurposed for the use cases mentioned above; it already comes with well-defined request-response semantics that are already used by web applications. But Blob resources are typically "in-memory" resident (e.g. after a file has been read into memory), and are thus unlike "traditional" HTTP resources that are dereferenced via DNS. While some user agents automatically "proxy" the underlying file system on the local machine via an HTTP server (e.g. with URLs of the sort https://localhost), HTTP is not traditionally used with local resources. Moreover, an important use case for these URLs are that they can be revoked with an API call. HTTP URLs have traditionally been used for resources that may be more permanent (and that are certainly not chiefly memory-resident, such as files that a web application can read). Reusing the HTTP scheme might be confusing for web developers owing to well-established practice.

• The reuse of file URLs would involve changes to file URL use today, such as adding response codes. While they are used inconsistently in web applications, the structure of the URLs would change, and request-response behavior would have to be superimposed on what already works in a more-or-less ad-hoc manner. Modifying this for the use cases cited above is imprudent, given legacy usage. Additionally, the use cases for a Blob URL scheme call for uses beyond the file system.

• A scheme of the sort urn:uuid [RFC4122] could be used, though use of this scheme is unprecedented in HTML and JavaScript web applications. The urn:uuid scheme is very generic. URLs in the scheme urn:uuid have the disadvantage of unfamiliarity and inconsistency across the web platform. A new scheme has the advantage of being explicit about what is being referenced. In theory, URLs make no guarantee about what sort of resource is obtained when they are dereferenced; that is left to content labeling and media type. But in practice, the name of the scheme creates an expectation about both the resource and the protocol of the request-response transaction. Choosing a name that clarifies the primary use case - namely, access to memory-resident Blob resources - is a worthwhile compromise, and favors clarity, familiarity, and consistency across the web platform.

10.3. The Blob URL

A Blob URL must consist of the blob: scheme followed by scheme data which must consist of a string tuple comprising the origin of the Blob URL, the "/" (U+0024 SOLIDUS) character, and a UUID [RFC4122; for an ABNF of UUID, see Appendix A]. A Blob URL may contain an optional fragment. The Blob URL is serialized as a string according to the Unicode Serialization of a Blob URL algorithm.

A fragment, if used, has a distinct interpretation depending on the media type of the Blob or File resource in question (see fragment discussion).

  blob = scheme ":" origin "/" UUID [fragIdentifier]
  scheme = "blob"
  ; scheme is always "blob"
  ; origin is a string representation of the Blob URL's origin.
  ; UUID is as defined in [RFC4122] and Appendix A
  ; fragIdentifier is optional and as defined in [RFC3986] and Appendix A
  

10.4. Dereferencing Model for Blob URLs

Blob URLs are dereferenced when the user agent retrieves the resource identified by the Blob URL and returns it to the requesting entity. This section provides guidance on requests and responses.

Only requests with GET [RFC7231] are supported. Specifically, responses are only a subset of the following from HTTP [RFC7231]:

  GET https://example.org:8080/550e8400-e29b-41d4-a716-446655440000
  

  
  200 OK
  Content-Type: image/jpeg
  Content-Length: 21897
  
  ....
  

partial interface URL {
  static DOMString createObjectURL(Blob blob);
  static DOMString createFor(Blob blob);
  static void revokeObjectURL(DOMString url);
};
  

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

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

var blobURLref2 = URL.createFor(file);
img1 = new Image();
img1.src = blobURLref2;
....

// file is an HTML file
// One of the anchor identifiers in file is "#applicationInfo"
var blobURLAnchorRef = URL.createFor(file) + "#applicationInfo";
// openPopup is an utility function to open a small informational window
var windowRef = openPopup(blobURLAnchorRef, "Application Info");
....

11. Security Considerations

This section is informative.

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

• Preventing selection looping. During file selection, a user may be bombarded with the file picker associated with <input type="file"/> (in a "must choose" loop that forces selection before the file picker is dismissed) and a user agent may prevent file access to any selections by making the FileList object returned be of size 0.

• System-sensitive files (e.g. files in /usr/bin, password files, and other native operating system executables) typically should not be exposed to web content, and should not be accessed via Blob URLs. User agents may throw a SecurityError exception for synchronous read methods, or return a SecurityError DOMError for asynchronous reads.

12. Requirements and Use Cases

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

• Once a user has given permission, user agents should provide the ability to read and parse data directly from a local file programmatically.

  • Example: A lyrics viewer. User wants to read song lyrics from songs in his plist file. User browses for plist file. File is opened, read, parsed, and presented to the user as a sortable, actionable list within a web application. User can select songs to fetch lyrics. User uses the "browse for file" dialog.

• Data should be able to be stored locally so that it is available for later use, which is useful for offline data access for web applications.

  • Example: A Calendar App. User's company has a calendar. User wants to sync local events to company calendar, marked as "busy" slots (without leaking personal info). User browses for file and selects it. The text/calendar file is parsed in the browser, allowing the user to merge the files to one calendar view. The user wants to then save the file back to his local calendar file. (using "Save As" ?). The user can also send the integrated calendar file back to the server calendar store asynchronously.

• User agents should provide the ability to save a local file programmatically given an amount of data and a file name.

  Note

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

  • Example: A Spreadsheet App. User interacts with a form, and generates some input. The form then generates a CSV (Comma Separated Variables) output for the user to import into a spreadsheet, and uses "Save...". The generated output can also be directly integrated into a web-based spreadsheet, and uploaded asynchronously.

• User agents should provide a streamlined programmatic ability to send data from a file to a remote server that works more efficiently than form-based uploads today

  • Example: A Video/Photo Upload App. User is able to select large files for upload, which can then be "chunk-transfered" to the server.

• User agents should provide an API exposed to script that exposes the features above. The user is notified by UI anytime interaction with the file system takes place, giving the user full ability to cancel or abort the transaction. The user is notified of any file selections, and can cancel these. No invocations to these APIs occur silently without user intervention.

13. Appendix A

This section uses the Augmented Backus-Naur Form (ABNF), defined in [RFC5234] to describe components of blob: URLs.

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

  fragIdentifier = "#" fragment
  ; Fragment Identifiers depend on the media type of the Blob
  ; fragment is defined in [RFC3986]
  ; fragment processing for HTML is defined in [HTML]
  fragment    = *( pchar / "/" / "?" )
  pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
  unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
  pct-encoded   = "%" HEXDIG HEXDIG
  sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
                   / "*" / "+" / "," / ";" / "="
  

14. Acknowledgements

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

Thanks to Robin Berjon for editing the original specification.

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

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

15. References