// Allows access to the filesystem of the computer the UserAgent is running on.
//
// No current spec or prior work applies. The closest thing is:
// http://www.w3.org/TR/file-upload/, but it is an early draft and does not
// provide all the capabilities we would like.
//
// filterContentTypes is intended to be an array of acceptable mimetypes, eg
// ["image/png", "image/gif"]. It is also acceptable to have types like image/*,
// would mean "All image types". It is up to the implementation to map mimetypes
// to OS-specific file types and to determine the meaning of "all image types".
interface FileSystem {
  File[] promptSelectFiles(optional string title,
      optional bool allowMultiple, optional string[] filterContentTypes);

  // future
  File promptCreateFile(optional string promptTitle,
      optional string[] filterContentTypes);
  File createTemporaryFile();
};


// Represents a file.
interface File {
  string name; // just the filename component, not the path (for privacy)
  InputStream getInputStream();

  // future
  OuptutStream getOutputStream();
};


// This is the old Gears Blob object. It has been renamed for compatibility
// with a future need for writing to streams as well.
interface InputStream {
 int64 length;

 InputStream slice(int64 start, int64 length);

 // future APIs below...
 string contentType;

 void readAsText(ReadStreamCallback<string> callback, optional string encoding,
     optional int64 start, optional int64 length);
 void readAsBase64(ReadStreamCallback<string> callback optional int64 start,
     optional int64 length);
 // Future: ES4 apparently has a ByteArray concept
 void readAsBytes(ReadStreamCallback<ByteArray> callback optional int64 start,
     optional int64 length);
 // If we wanted something that could work with today's js engines
 void readAsByteString(ReadStreamCallback<string> callback optional int64 start,
     optional int64 length);
};
void ReadStreamCallback<T>(T data);


// Extensions to XMLHttpRequest to interoperate with <s>Blobs</s> InputStreams.
interface XMLHttpRequest {
  InputStream responseStream;
  void send(InputStream stream);
};

// future: integrate with canvas, media elements, database, offline, etc