File Upload

This specification provides an API used to prompt the user with a file selection dialogue and obtain the data contained in files on the user's file system.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is a First Public Working Draft. The authors of this document are the members of the W3C Web API Working Group.

This document is produced by the Web API WG, part of the Rich Web Clients Activity in the W3C Interaction Domain.

Web content and browser developers are encouraged to review this draft. Please send comments to public-webapi@w3.org, the W3C's public email list for issues related to Web API. Archives of the list are available.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

• 1. Introduction
• 2. The FileException exception
• 3. The FileDialog interface
• 4. The FileList interface
• 5. The File interface
• 6. The 'files-selected' Event
• • 6.1. The FilesSelectionEvent interface
• 7. Integration with XMLHttpRequest
• 8. Conformance
• 9. Acknowledgements

• A. References

1. Introduction

It is desirable for Web applications to 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 application. This specification provides application writers with the means to trigger a file selection prompt with which the user can select one or more files. Unlike the file upload forms control available to HTML, this API can be used for more than simply inserting a file into the content of a form being submitted but also allows client-side manipulation of the content, for instance to display an image or parse an XML document from disk.

Important Note: this is a very rough first public working draft. Its purpose is in exposing a first pass on the design of this API, in order to gather feedback from the community.

2. The FileException exception

exception FileException {
  unsigned short   code;
};
// FileExceptionCode
const unsigned short      NOT_FOUND_ERR         = 0;
const unsigned short      NOT_READABLE_ERR      = 1;

3. The FileDialog interface

The purpose of the FileDialog interface is to control the display of a file dialogue, and to register the event listeners that will handle the selection of files. The FileDialog object inherits from EventTarget and it is this possible to attach event listeners to it using the addEventListener method.

It is possible that some platforms will only allow for one file to be selected at a time, however when possible a user-agent SHOULD provide the option to select multiple files in one pass.

interface FileDialog : events::EventTarget {
  void open();
};

4. The FileList interface

This interface exposes the list of files that has been selected through the file dialogue. When no file has been selected, its length is zero.

interface FileList {
  readonly attribute unsigned long  length;
  File               item(in unsigned long index);
  File               removeItem(in unsigned long index);
};

5. The File interface

This interface describes a single file in a FileList, exposes its name and media type, and provides access its content.

Please note that in order to be memory-efficient, implementations are not required to load the content of files into memory as soon as they have been selected, but only when their content is required by the application. When passing a File object to network API such as XMLHttpRequest an implementation may stream the content of a file to a socket and never need to hold more than a few of its bytes in memory. Therefore one needs to be aware that the content of the file may change or cease to be available between the moment the file is selected and the moment it is accessed.

interface File {

  readonly attribute DOMString      fileName;
  readonly attribute DOMString      mediaType;
  readonly attribute unsigned long  fileSize;
  DOMString          getDataAsString()
                                        raises(FileException);
  DOMString          getDataAsBase64()
                                        raises(FileException);
  DOMString          getDataAsHexBinary()
                                        raises(FileException);
};

6. The 'files-selected' Event

interface FilesSelectionEvent : events::Event {
  readonly attribute FileList  fileList;
};

7. Integration with XMLHttpRequest

8. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].

Unless otherwise specified immediately following the header, all sections in this document — to the exclusion of examples which are all informative — are normative.

9. Acknowledgements

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

A. References

RFC2119

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner.