File API

1. Introduction

This section is informative.

Web applications should have the ability to manipulate as wide as possible a range of user input, including files that a user may wish to upload to a remote server or manipulate inside a rich web application. This specification defines the basic representations for files, lists of files, errors raised by access to files, and programmatic ways to read files. The interfaces and API defined in this specification can be used with other interfaces and APIs exposed to the web platform.

File 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's data. Moreover, this specification defines separate interfaces for files and the objects used to read a file's data. While a File object provides a reference to a single file that a user has selected from a file picker (typically spawned by the HTML input element), a FileReader object provides asynchronous read methods to access that file's data through event handler 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 useful for remote drives that appear to be local, but behave slower than local drives), error conditions that may arise, and successful reading of a file. An example will be illustrative.

function startRead() {  
  // obtain input element through DOM 
  
  var file = document.getElementById('file').files[0];
  if(file){
    getAsText(file);
  }
}

function getAsText(readFile) {
        
  var reader = new FileReader();
  
  // Read file into memory as UTF-16      
  reader.readAsText(readFile, "UTF-16");
  
  // Handle progress, success, and errors
  reader.onprogress = updateProgress;
  reader.onload = loaded;
  reader.onerror = errorHandler;
}

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

function loaded(evt) {  
  // Obtain the read file data    
  var fileString = evt.target.result;
  // Handle UTF-16 file dump
  if(utils.regexp.isChinese(fileString)) {
    //Chinese Characters + Name validation
  }
  else {
    // run other charset test
  }
  // xhr.send(fileString)     
}

function errorHandler(evt) {
  if(evt.target.error.code == evt.target.error.NOT_READABLE_ERR) {
    // The file could not be read
  }
}

2. Conformance

Everything in this specification is normative except for examples and sections marked as being informative.

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels [RFC2119].

The following conformance classes are defined by this specification:

conforming implementation

A user agent is considered to be a conforming implementation if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification that apply to implementations.

3. Terminology and Algorithms

The terms and algorithms <fragment>, <scheme>, document base URL, event handler attributes, event handler event type, Function, origin, resolve a URL, same origin, task, task source, URL, URL character encoding, the "already started" flag for script processing, and queue a task are defined by the HTML 5 specification [HTML5].

This specification includes algorithms (steps) as part of the definition of methods. Conforming implementations (referred to as "user agents" from here on) MAY use other algorithms in the implementation of these methods, provided the end result is the same.

4. The FileList Sequence

This sequence parameterized type exposes the list of files that have been selected.

    typedef sequence<File> FileList;
    

    // uploadData is a form element
    // fileChooser is input element of type 'file'
    var file = document.forms['uploadData']['fileChooser'].files[0];
    
    if(file)
    {
      // Perform file ops
    }  
    

5. The Blob Interface

This interface represents raw data. It provides a method to slice data objects between ranges of bytes into further chunks of raw data. It also provides an attribute representing the size of the chunk of data. The File interface inherits from this interface.

    interface Blob {
      
      readonly attribute unsigned long long size;
      
      //slice Blob into byte-ranged chunks
      
      Blob slice(in long long start,
                 in long long length); // raises DOMException
    
    };
    

6. The File Interface

This interface describes a single file in a FileList and exposes its name, media type and a URN to access the file. It inherits from Blob.

  interface File : Blob {

      readonly attribute DOMString name;
      readonly attribute DOMString type;
      readonly attribute DOMString urn;
};
  

7. The FileReader Interface

This interface provides methods to read files in memory, and to access the data from those files using progress events and event handler attributes [DOM3Events]. It is desirable to read data from file systems asynchronously in the main thread of user agents. This interface provides such an asynchronous API, and is specified to be used within the context of the global object (Window [HTML5]) as well as Web Workers (WorkerUtils [WebWorkers]).

[Constructor]
interface FileReader {

  // async read methods 
  void readAsBinaryString(in Blob fileBlob);
  void readAsText(in Blob fileBlob, [Optional] in DOMString encoding);
  void readAsDataURL(in File file);

  void abort();

  // states
  const unsigned short EMPTY = 0;
  const unsigned short LOADING = 1;
  const unsigned short DONE = 2;
  
  
  readonly attribute unsigned short readyState;

  // file data
  readonly attribute DOMString result;
  
  readonly attribute FileError error;

  // event handler attributes
  attribute Function onloadstart;
  attribute Function onprogress;
  attribute Function onload;
  attribute Function onabort;
  attribute Function onerror;
  attribute Function onloadend;

};
FileReader implements EventTarget;
  

8. Reading on Threads

Web Workers allow for the use of synchronous file read APIs, since the effect of such read mechanisms on the main thread is mitigated. 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).

[Constructor]
interface FileReaderSync {

  // Synchronously return strings
  // All three methods raise FileException
  
  DOMString readAsBinaryString(in Blob fileBlob); 
  DOMString readAsText(in Blob fileBlob, [Optional] in DOMString encoding);                                                       
  DOMString readAsDataURL(in File file); 
};

9. Errors and Exceptions

Error conditions can occur when reading files from the underlying filesystem. The list below of potential error conditions is informative, with links to normative descriptions of error codes:

• The file 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 NOT_FOUND_ERR

• A file may be unreadable. This may be due to permission problems that occur after a reference to a file has been acquired (e.g. concurrent lock with another application). See NOT_READABLE_ERR

• 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 the security considerations. See SECURITY_ERR

• Files may be too large to return to the data structures of a Web application. An example might be that URL length limitations imposed by user agents on Data URLs may make obtaining large files encoded as Data URLs impossible to return [DataURL]. See ENCODING_ERR

• During the reading of a file, the Web application may itself wish to abort (see abort()) the call to an asynchronous read method. See ABORT_ERR

 interface FileError {
   // File error codes
   // Found in DOMException
   const unsigned short NOT_FOUND_ERR = 8;
   const unsigned short SECURITY_ERR = 18;
   const unsigned short ABORT_ERR = 20;
   
   // Added by this specification
   const unsigned short NOT_READABLE_ERR = 24;
   const unsigned short ENCODING_ERR = 26;
 
   readonly attribute unsigned short code;
};

 exception FileException {
  
  const unsigned short NOT_FOUND_ERR = 8;
  const unsigned short SECURITY_ERR = 18;
  const unsigned short ABORT_ERR = 20;
  
  const unsigned short NOT_READABLE_ERR = 24;
  const unsigned short ENCODING_ERR = 26;
 
  unsigned short code;
};

10. A UUID URN for File reference

RFC4122 [RFC4122] describes a UUID URN namespace. A File URN is a UUID URN described in RFC4122 [RFC4122] that is used to reference a File object, subject to an origin policy, a lifetime stipulation, and a processing model. A valid File URN takes the form urn:uuid:UUID where UUID matches the UUID production in Section 3 of RFC4122 [RFC4122], and is always a Version 1 UUID as described in Section 4.2.2 of RFC4122 [RFC4122]. Thus urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 is a valid File URN.

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 [HTML5], 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, other native operating system executables) typically should not be exposed to web content, and should not be accessed via URNs. User agents MAY raise a SECURITY_ERR if such files are accessed or a read method is called on them.

• Post-selection file modifications occur when a file changes on disk after it has been selected. In such cases, if a read method is called on a file, user agents MAY raise a SECURITY_ERR.

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.

  • 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. 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 Jonas Sicking, Olli Pettay, Nikunj Mehta, Garrett Smith, Michael Nordman, Ian Hickson, Sam Weinig, Aaron Boodman, Julian Reschke

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

14. References