File API

6.1.1. Constructor Parameters

The Blob() constructor can be invoked with the parameters below:

A blobParts Array

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

• ArrayBufferView [TypedArrays] array elements

• Blob array elements

• DOMString [WebIDL] array elements

An optional BlobPropertyBag

which takes two members:

• type, a DOMString which corresponds to the Blob object's type attribute.

• endings, an enum which can take the values "transparent" which is set by default, or "native". A description of both is given in the table below.

  Value	Description
  transparent	Code points from the string arguments must remain unchanged.
  native	Newlines must be transformed to the default line-ending representation of the underlying host operating system. For example, if the underlying OS is Windows, newlines will be transformed into \r\n pairs as the text is appended to the newly minted Blob object.

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

   4. This defines the normalization of the start parameter. When processing the slice call, user agents must normalize start to relativeStart.

3. The optional end parameter is a value for the end point of a slice call. The following requirements are normative for this parameter, and 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. This defines the normalization of the end parameter. When processing the slice call, user agents must normalize end to relativeEnd.

4. The optional contentType parameter is used to set a value identical to one that is set with the HTTP/1.1 Content-Type header [RFC2616] on the Blob returned by the slice call. The following requirements are normative for this parameter, and 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 following substeps:

      1. If relativeContentType consists of any non-ASCII characters, throw a SyntaxError (per [RFC2616]) and return from this algorithm.

      2. Convert every character in relativeContentType to lower case.

      3. Parse relativeContentType as an RFC2616 media-type, tokenizing it according to the ABNF for media-type [RFC2616] with the ASCII "/" character separating tokens representing the type and subtype productions. If relativeContentType cannot be tokenized according to the ABNF for media-type [RFC2616], throw a SyntaxError and return from this algorithm.

      4. If the type and subtype tokens consist of any CTLs or separators, throw a SyntaxError and return from this algorithm (per [RFC2616]).

   3. This defines the normalization of the contentType parameter. When processing the slice call, user agents must normalize contentType to relativeContentType.

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

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

   1. S consists of span consecutive bytes from O, beginning with the byte at byte-order position relativeStart.

   2. S.size = span.

   3. S.type = relativeContentType.

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

6.3.2. The close method

Calling the close method must permanently neuter the original Blob object. This is an irreversible and non-idempotent operation; once a Blob has been neutered, it cannot be used again; dereferencing a Blob URI bound to a Blob object on which close has been called results in a 500 Error. A neutered Blob must have a size of 0.

8.5.1. Multiple Reads

The FileReader interface makes available three asynchronous read methods - readAsArrayBuffer, readAsText, and readAsDataURL, which read files into memory. If multiple concurrent read methods are called on the same FileReader object, user agents must throw an InvalidStateError [DOM4] on any of the read methods that occur when readyState = LOADING.

8.5.2. The result attribute

On getting, the result attribute returns a Blob's data as a DOMString, or as an ArrayBuffer [TypedArrays], or null, depending on the read method that has been called on the FileReader, and any errors that may have occurred. It can also return partial Blob data. Partial Blob data is the part of the File or Blob that has been read into memory currently; when processing the read method readAsText, partial Blob data is a DOMString that is incremented as more bytes are loaded (a portion of the total) [ProgressEvents], and when processing readAsArrayBuffer partial Blob data is an ArrayBuffer [TypedArrays] object consisting of the bytes loaded so far (a portion of the total)[ProgressEvents]. The list below is normative for the result attribute and is the conformance criteria for this attribute:

• On getting, if the readyState is EMPTY (no read method has been called) then the result attribute must return null.

• On getting, if an error in reading the File or Blob has occurred (using any read method), then the result attribute must return null.

• On getting, if the readAsDataURL read method is used, the result attribute must return a DOMString that is a Data URL [DataURL] encoding of the File or Blob's data.

• On getting, if the readAsText read method is called and no error in reading the File or Blob has occurred, then the 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. On getting, while processing the readAsText read method, this attibute should return partial Blob data in the format specified by the encoding determination as a DOMString that is incremented as more data is read. User agents must return at least one such result, with the final result returned at completion of the read. See the caveat about partial Blob data being valid within a giving encoding.

• On getting, if the readAsArrayBuffer read method is called and no error in reading the File or Blob has occurred, then the result attribute must return an ArrayBuffer [TypedArrays] object. On getting, while processing the readAsArrayBuffer read method, the result attribute should return partial Blob data as an ArrayBuffer [TypedArrays]. User agents must return at least one such result, with the final result returned at completion of the read.

If a read is successful, the result attribute must return a non-null value only after a progress event (see also [ProgressEvents]) has fired, since all the read methods access Blob data asynchronously. Tasks are queued to update the result attribute as Blob data is made available.

8.5.3. The readAsDataURL(blob) method

When the readAsDataURL(blob) method is called, the user agent must run the steps below (unless otherwise indicated).

1. If readyState = LOADING throw an InvalidStateError exception [DOM4] and terminate this algorithm.

   Note: The readAsDataURL() method returns due to the algorithm being terminated.

2. If the blob has been neutered through the close method, throw an InvalidStateError exception [DOM4] and terminate this algorithm.

   Note: The readAsDataURL() method returns due to the algorithm being terminated.

3. If an error occurs during reading of the blob parameter, OR if a user agent's URL length limitations prevent returning data as a Data URL [DataURL], set readyState to DONE and set result to null. Proceed to the error steps below.

   1. Fire a progress event called error. Set the error attribute; on getting, the error attribute must be a a DOMError object that indicates the kind of file error that has occurred.

   2. Fire a progress event called loadend.

   3. Terminate this algorithm.

      Note: The readAsDataURL() method returns due to the algorithm being terminated.

4. If no error has occurred, set readyState to LOADING

5. Fire a progress event called loadstart.

6. Return the readAsDataURL() method, but continue to process the steps in this algorithm.

7. Fire a progress event called progress at completion of the read.

8. Queue a task to update the result attribute with the blob as a DataURL [DataURL] after it has been fully read into memory; on getting, the result attribute returns the (complete) data of blob as a Data URL [DataURL].

   • Use the blob's type attribute as part of the Data URL if it is available in keeping with the Data URL specification [DataURL] .
   • If the type attribute is not available on the blob return a Data URL without a media-type. [DataURL].

     Data URLs that do not have media-types [RFC2046] must be treated as plain text by conforming user agents. [DataURL].

9. Set readyState to DONE

10. Fire a progress event called load.

11. Fire a progress event called loadend.

12. Terminate this algorithm.

8.5.4. The readAsText(blob, encoding) method

When the readAsText(blob, encoding) method is called (the encoding argument is optional), the user agent must run the steps below (unless otherwise indicated).

1. If readyState = LOADING throw an InvalidStateError [DOM4] and terminate these steps.

   Note: The readAsText() method returns due to the algorithm being terminated.

2. If the blob has been neutered through the close method, throw an InvalidStateError exception [DOM4] and terminate this algorithm.

   Note: The readAsText() method returns due to the algorithm being terminated.

3. If an error occurs during reading the blob parameter, set readyState to DONE and set result to null. Proceed to the error steps below.

   1. Fire a progress event called error. Set the error attribute; on getting, the error attribute must be a a DOMError object that indicates the kind of file error that has occurred.

   2. Fire a progress event called loadend.

   3. Terminate this algorithm.

      Note: The readAsText() method returns due to the algorithm being terminated.

4. If no error has occurred, set readyState to LOADING

5. Fire a progress event called loadstart.

6. Return the readAsText() method, but continue to process the steps in this algorithm

7. Make progress notifications.

8. While processing the read, as data from the blob becomes available, user agents should queue tasks to update the result with partial Blob data represented as a string in a format determined by the encoding determination until the read is complete, to accompany the firing of progress events. On getting, the result attribute returns partial Blob data representing the number of bytes currently loaded (as a fraction of the total) [ProgressEvents], decoded into memory according to the encoding determination; user agents must return at least one such result while processing this read method. The last returned value is at completion of the read.

   Partial Blob data must be returned such that where possible, the bytes read thus far should be valid code points within the encoding; in particular, when executing the encoding determination for Partial Blob data, user agents must NOT return the U+FFFD character for bytes that are invalid within an encoding till the entire codepoint has been read. The following encoding caveat must be followed:

   Suppose a file resource is to be read in UTF-8, and in hexadecimal the bytes in this file are E3 83 91 E3 83 91, which is effectively 0x30D1 0x30D1. Suppose the first 5 bytes have been read. The result returned here must be 0x30D1 and have result.length == 1 , and NOT be 0x30D1 0xFFFD with result.length == 2 . Even though the trailing E3 83 is not a valid code point in UTF-8 at the fifth byte, user agents must NOT return a result with such invalid code points replaced with U+FFFD till it can be determined definitively that the codepoint is invalid.

9. When the blob has been read into memory fully, set readyState to DONE

10. Terminate this algorithm.

8.5.5. The readAsArrayBuffer(blob) method

When the readAsArrayBuffer(blob) method is called, the user agent must run the steps below (unless otherwise indicated).

1. If readyState = LOADING throw an InvalidStateError exception [DOM4] and terminate these steps.

   Note: The readAsArrayBuffer() method returns due to the algorithm being terminated.

2. If the blob has been neutered through the close method, throw an InvalidStateError exception [DOM4] and terminate this algorithm.

   Note: The readAsArrayBuffer() method returns due to the algorithm being terminated.

3. If an error occurs during reading the blob parameter, set readyState to DONE and set result to null. Proceed to the error steps below.

   1. Fire a progress event called error. Set the error attribute; on getting, the error attribute must be a a DOMError that indicates the kind of file error that has occurred.

   2. Fire a progress event called loadend.

   3. Terminate this algorithm.

      Note: The readAsArrayBuffer() method returns due to the algorithm being terminated.

4. If no error has occurred, set readyState to LOADING

5. Fire a progress event called loadstart.

6. Return the readAsArrayBuffer() method, but continue to process the steps in this algorithm.

7. Make progress notifications.

8. While processing the read, as data from the blob becomes available, user agents should queue tasks to update the result with partial Blob data as an ArrayBuffer [TypedArrays] object containing the bytes read until the read is complete, to accompany the firing of progress events. On getting, the result attribute returns partial Blob data representing the number of bytes currently loaded (as a fraction of the total) [ProgressEvents], as an ArrayBuffer [TypedArrays] object; user agents must return at least one such ArrayBuffer [TypedArrays] while processing this read method. The last returned value is at completion of the read.

9. When the blob has been read into memory fully, set readyState to DONE

10. Terminate this algorithm.

8.5.6. The abort() method

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

1. If readyState = EMPTY or if readyState = DONE set result to null and terminate this overall set of steps without doing anything else.

2. If readyState = LOADING set readyState to DONE and result to null.

3. If there are any tasks from the object's FileReader task source in one of the task queues, then remove those tasks.

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

5. Fire a progress event called abort

6. Fire a progress event called loadend

8.5.7. Blob Parameters

The three asynchronous read methods, the three synchronous read methods, and createObjectURL take a mandatory 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 object not obtained from the file system that is in scope of the global object from which the method call was made.

8.5.8. Determining Encoding

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

1. Let charset be null

2. If the encoding argument is present, and is the name or alias of a character set used on the Internet [IANACHARSET], let charset be set to the value of the encoding parameter.

3. If charset is null, then for each of the rows in the following table, starting with the first one and going down, if the first bytes of blob match the bytes given in the first column, then let charset be the encoding given in the cell in the second column of that row. If there is no match then charset remains null.

   Bytes in Hexadecimal	Description
   FE FF	UTF-16BE BOM
   FF FE	UTF-16LE BOM
   EF BB BF	UTF-8 BOM

4. If charset is null, and the blob argument's type attribute is present, and its Charset Parameter [RFC2046] is the name or alias of a character set used on the Internet [IANACHARSET], let charset be set to its Charset Parameter.

   Example

   If blob has a type attribute of text/plain;charset=UTF-8 then charset is UTF-8.

5. If charset is null let charset be UTF-8.

6. Return the result of decoding the blob using charset; on getting, the result attribute of the FileReader object returns a string in charset format. The synchronous readAsText method of the FileReaderSync object returns a string in charset format. Replace bytes or sequences of bytes that are not valid according to the charset with a single U+FFFD character [Unicode]. When processing Partial Blob Data, use the encoding caveat, if applicable.

8.5.9. Events

When this specification says to make progress notifications for a read method, the following steps must be followed:

1. While the read method is processing, queue a task to fire a progress event called progress at the FileReader object about every 50ms or for every byte read into memory, whichever is least frequent. At least one event called progress must fire before load is fired, and at 100% completion of the read operation; if 100% of blob can be read into memory in less than 50ms, user agents must fire a progress event called progress at completion.

   Example

   If a given implementation uses buffers of size 65536 bytes to read files, and thus limits reading operations to that size, and a read method is called on a file that is 65537 bytes, then that implementation must fire one progress event for the 65536 first bytes, one progress event for the 65537th byte (which is at completion of read), one load event and one loadend event.

2. When the data from the blob has been completely read into memory, queue a task to fire a progress event called load at the FileReader object.

3. When the data from the blob has been completely read into memory, queue a task to fire a progress event called loadend at the FileReader object.

When this specification says to fire a progress event called e (for some ProgressEvent e at a FileReader reader), 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].

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

9.1.2. The readAsText method

When the readAsText(blob, encoding) method is called (the encoding argument is optional), the following steps must be followed:

1. If an error occurs during reading of the blob parameter, throw the appropriate exception. Terminate these overall steps.

2. If no error has occurred, read blob into memory. Return the data contents of blob using the encoding determination algorithm.

9.1.3. The readAsDataURL method

When the readAsDataURL(blob) method is called, the following steps must be followed:

1. If an error occurs during reading of the blob parameter, throw the appropriate exception. Terminate these overall steps.

2. If no error has occurred, read blob into memory. Return the data contents of blob as a Data URL [DataURL]

   • Use the blob's type attribute as part of the Data URL if it is available in keeping with the Data URL specification [DataURL] .
   • If the type attribute is not available on the blob return a Data URL without a media-type. [DataURL].

     Data URLs that do not have media-types [RFC2046] must be treated as plain text by conforming user agents. [DataURL].

9.1.4. The readAsArrayBuffer method

When the readAsArrayBuffer(blob) method is called, the following steps must be followed:

1. If an error occurs during reading the blob parameter, throw the appropriate exception. Terminate these overall steps.

2. If no error has occurred, read blob into memory. Return the data contents of blob as an ArrayBuffer [TypedArrays]

11.3.1. The Opaque String

Opaque strings must NOT include any reserved characters from [RFC3986] without percent-encoding them. Opaque strings must be globally unique. Such strings should only use characters in the ranges U+002A to U+002B, U+002D to U+002E, U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E [Unicode], and should be at least 36 characters long. UUID is one potential option available to user agents for use with Blob URIs as opaque strings, and their use is strongly encouraged. UUIDs are defined in [RFC4122]. For an ABNF of UUID, see Appendix A.

11.7.1. 200 OK

This response [RFC2616] must be used if the request has succeeded, namely the blob: URI has been requested with a GET, satisfies the origin requirement, and satisfies the lifetime requirement. If this response code is used, the user agent must also use a Content-Type header [RFC2616] with a value equal to the Blob object's type attribute. See blob: protocol examples.

11.7.2. 500 Error Condition

This response [RFC2616] must be used if:

• Any request method other than GET is used to dereference the URL.

• The request violates the origin requirement. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Origin Violation."

• The request does not satisfy the lifetime requirement. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Expired URI."

• The underlying resource has changed, moved, been deleted or has become invalid. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Invalid Resource."

• The permissions surrounding the underlying resource do not permit access. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Access Violation."

• A security error has occurred. In this case, the response should be accompanied by clarifying text alongside the 500 response, e.g. "500 Security Violation."

This response may be accompanied by additional messages in the response indicating why the Blob resource could not be served. See blob: protocol examples.

The 500 Error Condition provides a response code, but not a fixed status. User agents MAY leave it as simply "500 Error Condition" or supply additional status information (e.g. "500 Origin Violation"). Implementers are strongly encouraged to provide messages to developers along with the response code.

11.7.3. Request and Response Headers

This section provides sample exchanges between web applications and user agents using the blob: protocol. A request can be triggered using HTML markup of the sort <img src="blob:550e8400-e29b-41d4-a716-446655440000">, after a web application calls URL.createObjectURL on a given blob, which returns blob:550e8400-e29b-41d4-a716-446655440000 to dereference that blob. These examples merely illustrate the protocol; web developers are not likely to interact with all the headers, but the getAllResponseHeaders() method of XMLHttpRequest, if used, will show relevant response headers [XHR2].

	GET 550e8400-e29b-41d4-a716-446655440000
	

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

	500 Error Condition
	This file cannot be read.
	

11.8.1. Methods and Parameters

The createObjectURL static method

Returns a unique Blob URI each time it is called on a valid blob argument, which is a non-null Blob in scope of the global object's URL property from which this static method is called.

1. If this method is called with a Blob argument that is NOT valid, then user agents must return null.

2. If this method is called with a valid Blob argument, user agents must run the following steps:

   1. The optional objectURLOptions dictionary argument called options has a boolean member autoRevoke that defaults to true; if called without using the optional dictionary, or if called with autoRevoke set to true, execute the following sub-steps:
      1. Return a unique Blob URI that can be used to dereference the blob argument, and run the rest of this algorithm asynchronously.
      2. Provide a stable state
      3. Revoke the Blob URI by calling revokeObjectURL on it and terminate this algorithm.

   2. If this method is called with the autoRevoke dictionary member set to false, return a unique Blob URI that can be used to dereference the blob argument.

      Note

      This Blob URI must persist till a call to revokeObjectURL is made, or till the unloading document cleanup steps are executed.

Example

In the example below, after obtaining a reference to a Blob object (in this case, a user-selected File from the underlying file system), the static method URL.createObjectURL() is called on that Blob object.

ECMAScript

	var file = document.getElementById('file').files[0];
	if(file){
	  blobURLref = window.URL.createObjectURL(file);
	  myimg.src = blobURLref;
	}
	

The revokeObjectURL static method

Revokes the Blob URI provided in the string url argument.

1. If the url refers to a Blob that is both valid and in the same origin of the global object's URL property on which this static method was called, user agents must return a 500 response code when the url is dereferenced.
2. If the url refers to a Blob that is NOT valid OR if the value provided for the url argument is not a Blob URI OR if the url argument refers to a Blob that is NOT in the same origin as the global object's URL property, this method call does nothing. User agents may display a message on the error console.

The url argument to the revokeObjectURL method is a Blob URI string.

Example

In the example below, window1 and window2 are separate, but in the same origin; window2 could be an iframe [HTML] inside window1.

ECMAScript

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

Since window1 and window2 are in the same origin, the URL.revokeObjectURL call ensures that subsequent dereferencing of myurl results in a 500 Error Condition response.