File API

1. 序論

~Web~appは、［ 利用者からの入力をアリな限り広範囲に操作する能 ］を有するべきである — ~fileを［ 利用者が望むなら~remote~serverへ~uploadする／ 多彩な~Web~appの中で操作する ］ことも含めて。 この仕様は、 次を定義する： ◎ 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＼

• 次についての基本的な表現 ⇒＃ ~file, ~fileたちが成す~list, ~fileに~accessする際の~error, ~fileを~program的に読取る仕方 ◎ the basic representations for files, lists of files, errors raised by access to files, and programmatic ways to read files.＼
• 適合~UAの~main~threadと非同期に処理できる， “生~data” を表現する~interface ◎ Additionally, this specification also defines an interface that represents "raw data" which can be asynchronously processed on the main thread of conforming user agents.＼

この仕様で定義される~interfaceと~APIは、 ~Web~platformに公開された他の~interfaceや~APIと伴に利用できるものになる。 ◎ The interfaces and API defined in this specification can be used with other interfaces and APIs exposed to the web platform.

`File$I ~interfaceは、 概して，（利用者~環境の）下層の~file~systemから得された~file~dataを表現する。 `Blob$I ~interface （ "`Binary Large Object^en" — 元々は `Google Gears＠https://developers.google.com/gears/?csw=1$en の~Web~APIに由来する名称） は、 変異-不能な生~dataを表現する。 ［ `File$I ／ `Blob$I ］の読取りは，~main~threadと非同期に行われるべきものであり、 ~thread化された~Web~app【~worker環境下】においては，同期~APIを利用する選択肢もある。 非同期~APIで~fileを読取ることにより、 ~UAの~main~threadにおける~UIの “無反応”は，防止される。 ◎ The File interface represents file data typically obtained from the underlying file system, and the Blob interface ("Binary Large Object" - a name originally introduced to web APIs in Google Gears) represents immutable raw data. File or Blob 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.＼

この仕様は、［ `File$I ／ `Blob$I ］~dataの読取nと~access用に，`~event~model^emに基づく非同期~APIを定義する。 `FileReader$I ~objは、［ ~event~handler内容~属性と~eventの発火を通して~file~dataへ~accessする ］ための`非同期~読取n~method$を供する。 ~eventと~event~handlerを利用することで、［ `読取nの進捗^emを監視するとき （~file~accessの処理能が~local~driveとは異なる， ~remote~driveや~mountされた~drive用に特に有用になる） ］と［ ~file読取n中に起こり得る`~error条件$を監視するとき ］とで，別々な~code~blockを利用できるようになる — 次の例に示されるように： ◎ This specification defines an asynchronous API based on an event model to read and access a File or Blob’s data. A FileReader object provides asynchronous read methods to access that file’s data through event handler content 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 particularly useful for remote drives or mounted drives, where file access performance may vary from local drives) and error conditions that may arise during reading of a file. An example will be illustrative.

function startRead() {
  /* 
`input$e 要素を~DOMから得する
◎
obtain input element through DOM
 */

  var %file = document.getElementById('file').files[0];
  if(%file){
    getAsText(%file);
  }
}

function getAsText(%readFile) {

  var %reader = new FileReader();

  /* 
~UTF-16として~fileを~memory内に読取る
◎
Read file into memory as UTF-16
 */
  %reader.readAsText(%readFile, "UTF-16");

  /* 
進捗, 成功, ~error を取扱う
◎
Handle progress, success, and errors
 */
  %reader.onprogress = updateProgress;
  %reader.onload = loaded;
  %reader.onerror = errorHandler;
}

function updateProgress(%evt) {
  if (%evt.lengthComputable) {
    /* 
%evt . `loaded^m および %evt . `total^m は `ProgressEvent$I の~prop
◎
evt.loaded and evt.total are ProgressEvent properties
 */
    var %loaded = (%evt.loaded / %evt.total);
    if (%loaded < 1) {
      /* 
進捗~barの長さを増やす
◎
Increase the prog bar length
 */
      // style.width = (%loaded * 200) + "px";
    }
  }
}

function loaded(%evt) {
  /* 
読取られた~file~data（この事例では文字列）を得する
◎
Obtain the read file data
 */
  var %fileString = %evt.target.result;
  /* 
得られた~dataを取扱う
◎
Handle UTF-16 file dump
 */
  if(utils.regexp.isChinese(%fileString)) {
    /* 
Chinese 文字~並びの~~処理
◎
Chinese Characters + Name validation
 */
  }
  else {
    /* 
他の~charsetについての~test
◎
run other charset test
 */
  }
  // xhr.send(%fileString)
}

function errorHandler(%evt) {
  if(%evt.target.error.name == "NotReadableError") {
    /* 
~fileを読取れなかった
◎
The file could not be read
 */
  }
}

2. 各種用語と~algo

この仕様において，~algoを `終了-@ する所では、 ~UAが~~実行中の段を終えた所で~algoを終了するモノトスル。 この仕様が定義する`非同期~読取n~method$は、 当の~algo【が並列的に走らす下位-手続き】が終了する前に返ることも， `abort()$m ~callにより終了されることもある。 ◎ When this specification says to terminate an algorithm the user agent must terminate the algorithm after finishing the step it is on. Asynchronous read methods defined in this specification may return before the algorithm in question is terminated, and can be terminated by an abort() call.

整数 %a, %b に対する［ `max^op( %a, %b ) ／ `min^op( %a, %b ) ］は、 %a, %b の［ 最大値／最小値 ］を返す。 ◎ The algorithms and steps in this specification use the following mathematical operations: ◎ max(a,b) returns the maximum of a and b, and is always performed on integers as they are defined in WebIDL [WebIDL]; in the case of max(6,4) the result is 6. This operation is also defined in ECMAScript [ECMA-262]. ◎ min(a,b) returns the minimum of a and b, and is always performed on integers as they are defined in WebIDL [WebIDL]; in the case of min(6,4) the result is 4. This operation is also defined in ECMAScript [ECMA-262]. ◎ Mathematical comparisons such as < (less than), ≤ (less than or equal to), and > (greater than) are as in ECMAScript [ECMA-262].

用語 `~Unix~epoch@ （ `Unix Epoch^en ）は、 UTC 1970年 1月 1日 午前 0時 0分 0秒を指す…† ◎ The term Unix Epoch is used in this specification to refer to the time 00:00:00 UTC on January 1 1970 (or 1970-01-01T00:00:00Z ISO 8601); this is the same time that is conceptually "0" in ECMA-262 [ECMA-262].

【† `HR-TIME$r に定義される`~Unix~epoch＠~HRTIME#dfn-unix-epoch$と同じ。 この用語を利用して時間を導出している箇所は、 おそらく同~仕様に定義される用語に基づくよう，更新されるべきであろう。 】

【この訳に特有な表記規約】

`~Blob@ とは、 `Blob$I ~interfaceを実装する~objの略記である （したがって， `File$I ~objも含まれる）。

`~file入力~要素@ とは、 `input$e 要素のうち［ その `type^a 属性の状態 ~EQ `File$st ］を満たすものである。 `HTML$r

原文が参照している他の仕様の用語には、 今や，廃された／改称されたものもある。 この訳では、 その現在の仕様に揃うよう改めている：

• 原文の “`media type^en” に代えて、 “`~MIME型$（ `MIME type^en ）” を利用している。 `MIMESNIFF$r
• 原文が参照していた用語 `構文解析-可能な~MIME型@ は、 今や `MIMESNIFF$r から廃された。 おそらく，この用語を利用している箇所は、 `妥当な~MIME型~文字列$を利用するべきであろう。

3. `Blob^I ~interfaceと~binary~data

各`~Blob$は、 `~byte列~data@ を参照rする。 ~Blobの ⇒＃ `size$m 属性は，この~dataの総~byte数を表現する／ `type$m 属性は，この~dataの~MIME型を（~ASCII小文字に符号化された文字列として）表現する ◎ A Blob object refers to a byte sequence, and has a size attribute which is the total number of bytes in the byte sequence, and a type attribute, which is an ASCII-encoded string in lower case representing the media type of the byte sequence.

各`~Blob$は、 `~snapshot状態@ を内部的に有する — それは、 `~byte列~data$が下層~storageから得られた場合に限り， 当の~storageの状態に初期化するモノトスル 【他の場合、~snapshot状態は “無い” 】。 `~snapshot状態$についての更なる規範的な定義は、 § `File^I ~interface にて見出せる。 ◎ Each Blob must have an internal snapshot state, which must be initially set to the state of the underlying storage, if any such underlying storage exists. Further normative definition of snapshot state can be found for Files.

[ `Exposed$=(Window,Worker), `Serializable$]
interface `Blob@I {
  `Blob$mc(
      optional `sequence$<`BlobPart$I> `blobParts$V,
      optional `BlobPropertyBag$I `options$V = {}
  );

  readonly attribute `unsigned long long$ `size$m;
  readonly attribute `DOMString$ `type$m;

  /* 
~Blobから~byte範囲の~chunkを切出す
◎
slice Blob into byte-ranged chunks
 */
  Blob `slice$m(
      optional [`Clamp$] `long long$ %start,
      optional [`Clamp$] `long long$ %end,
      optional `DOMString$ %contentType
  );
  /* 
~Blobから読取る。
◎
read from the Blob.
 */
  [`NewObject$] `ReadableStream$I `stream$m();
  [`NewObject$] `Promise$<`USVString$> `text$m();
  [`NewObject$] `Promise$<`ArrayBuffer$> `arrayBuffer$m();
  [`NewObject$] `Promise$<`Uint8Array$> `bytes$m();
};

enum `EndingType@I { `transparent@l, `native@l };

dictionary `BlobPropertyBag@I {
  `DOMString$ `type$dm = "";
  `EndingType$I `endings$dm = `transparent$l;
};

typedef (`BufferSource$ or `Blob$I or `USVString$) `BlobPart@I;

`Blob$I ~objは、 `直列化-可能$である： ◎ Blob objects are serializable objects.＼

• その`直列化~手続き$は、 所与の ( %値, %直列形 ) に対し，次を走らす： ◎ Their serialization steps, given value and serialized, are:

  1. %直列形 . `SnapshotState^sl ~SET %値 の`~snapshot状態$ ◎ Set serialized.[[SnapshotState]] to value’s snapshot state.
  2. %直列形 . `ByteSequence^sl ~SET %値 の下層の~byte列 ◎ Set serialized.[[ByteSequence]] to value’s underlying byte sequence.

• その`逆直列化~手続き$は、 所与の ( %値, %直列形, %宛先~realm ) に対し，次を走らす： ◎ Their deserialization step, given serialized and value, are:

  1. %値 の`~snapshot状態$ ~SET %直列形 . `SnapshotState^sl ◎ Set value’s snapshot state to serialized.[[SnapshotState]].
  2. %値 の下層の~byte列 ~SET %直列形 . `ByteSequence^sl ◎ Set value’s underlying byte sequence to serialized.[[ByteSequence]].

/* 
新たな `Blob^I ~objを作成する
◎
Create a new Blob object
 */

var %a = new Blob();

/* 
1024 ~byteの `ArrayBuffer^I を作成する
◎
Create a 1024-byte ArrayBuffer
 */
/* 
~bufferは `File^I 読取nからも得られる
◎
buffer could also come from reading a File
 */

var %buffer = new ArrayBuffer(1024);

/* 
~bufferに基づく `ArrayBufferView^I ~objを作成する
◎
Create ArrayBufferView objects based on buffer
 */

var %shorts = new Uint16Array(%buffer, 512, 128);
var %bytes = new Uint8Array(
  %buffer,
  %shorts.byteOffset + %shorts.byteLength
);

var %b = new Blob(
  ["foobarbazetcetc" + "birdiebirdieboo"],
  {type: "text/plain;charset=utf-8"}
);

var %c = new Blob([%b, %shorts]);

var %a = new Blob([%b, %c, %bytes]);

var %d = new Blob([%buffer, %b, %c, %bytes]);

/* 
~DOMから得される `input$e 要素から， `File$I ~objを得る
◎
obtain input element through DOM
 */
var %file = document.getElementById('file').files[0];

if(%file) {
  /* 
%file を複製する
— 次の 2 つの~callは等価
◎
create an identical copy of file
the two calls below are equivalent
 */
  var %fileClone = %file.slice();
  var %fileClone2 = %file.slice(0, %file.size);

  /* 
%file の後半を成す~chunkを切出す
— 負な数を利用していることに注意
◎
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)));

  /* 
%file の前半を成す~chunkを切出す
◎
slice file into 1/2 chunk starting at beginning of file
 */
  var %fileChunkFromStart = %file.slice(0, Math.round(%file.size/2));

  /* 
%file の［
先頭から，末尾から 150 ~byte手前まで
］の部分を切出す
◎
slice file from beginning till 150 bytes before end
 */
  var %fileNoMetadata = %file.slice(0, -150, "application/experimental");
}

4. `File^I ~interface

`File$I ~objは、［ 文字列を値にとる `name$m 属性 ］も伴う， `Blob$I ~objである。 それは、 ~Web~appの中で構築子を通して作成されるか，あるいは 下層の~OS~file~systemからの~fileを成す`~byte列$への参照である。 ◎ A File object is a Blob object with a name attribute, which is a string; it can be created within the web application via a constructor, or is a reference to a byte sequence from a file from the underlying (OS) file system.

`File$I ~objの`~byte列~data$が~disk上の~file由来の`~byte列$である場合、 その`~snapshot状態$は，~objの作成-時点における~fileの状態を~~反映するべきである。 ◎ If a File object is a reference to a byte sequence originating from a file on disk, then its snapshot state should be set to the state of the file on disk at the time the File object is created.

注記： これは、 ~UAにとって実装するのは自明でない要件なので， “`〜するモノトスル^em” ではなく “`〜するベキ^em” とされている `RFC2119$r。 ~UAは、 `File$I ~objの`~snapshot状態$が［ 参照が得られた時点における~disk上の下層~storageの状態 ］に設定されるよう，努めるべきである。 その時点より後に~disk上の~fileが改変された場合、 `~snapshot状態$は，下層~storageの状態とは異なるものになる。 ~UAは、 改変~時刻印その他の仕組みを利用して，`~snapshot状態$を保守してもヨイが、 それについては実装の詳細~に委ねられる。 ◎ Note: This is a non-trivial requirement to implement for user agents, and is thus not a must but a should [RFC2119]. User agents should endeavor to have a File object’s snapshot state set to the state of the underlying storage on disk at the time the reference is taken. If the file is modified on disk following the time a reference has been taken, the File's snapshot state will differ from the state of the underlying storage. User agents may use modification time stamps and other mechanisms to maintain snapshot state, but this is left as an implementation detail.

`File$I ~objが~disk上の~fileを参照rしている場合、 ~UAは，［ ~objの `type$m 属性の取得子が［ 以下に与える `~file型~指針@ に従う~MIME型 ］を返す ］ようにするモノトスル： ◎ When a File object refers to a file on disk, user agents must return the type of that file, and must follow the file type guidelines below:

• ~MIME型は、 次のようにすること：

  • ~fileの~MIME型を決定できる場合 ⇒ ［ ~byte列に変換した結果が`構文解析-可能な~MIME型$になる ］ような，~ASCII小文字に符号化された文字列
  • 他の場合 ⇒ 空~文字列（~byte列に変換されたときに 0 ~byteになる）
  ◎ User agents must return the type as an ASCII-encoded string in lower case, such that when it is converted to a corresponding byte sequence, it is a parsable MIME type, or the empty string – 0 bytes – if the type cannot be determined.
• ［ `~Blob$の `type$m ~EQ `text/plain^l ］の場合 ⇒ ~MIME型の［ `~parameter群$ `MIMESNIFF$r にあたる部位 ］には、 ~charset~parameterを`付加しない^emこと。 ◎ When the file is of type text/plain user agents must NOT append a charset parameter to the dictionary of parameters portion of the media type [MIMESNIFF].
• 経験則（統計的~手法も含む）により符号化法を決定するよう試みないこと。 ◎ User agents must not attempt heuristic determination of encoding, including statistical methods.

[`Exposed$=(Window,Worker), `Serializable$]
interface `File@I : `Blob$I {
  `File$mc(【！原文引数抜け】
      `sequence$<`BlobPart$I> `fileBits$V,
      `USVString$ `fileName$V,
      optional `FilePropertyBag$I `fileOptions$V = {}
  );
  readonly attribute `DOMString$ `name$m;
  readonly attribute `long long$ `lastModified$m;
};

dictionary `FilePropertyBag@I : `BlobPropertyBag$I {
      `long long$ `lastModified$dm;
};

`File$I ~objは、 `直列化-可能$である： ◎ File objects are serializable objects.＼

• その`直列化~手続き$は、 所与の ( %値, %直列形 ) に対し，次を走らす： ◎ Their serialization steps, given value and serialized, are:

  1. %直列形 . `SnapshotState^sl ~SET %値 の`~snapshot状態$ ◎ Set serialized.[[SnapshotState]] to value’s snapshot state.
  2. %直列形 . `ByteSequence^sl ~SET %値 の下層の~byte列 ◎ Set serialized.[[ByteSequence]] to value’s underlying byte sequence.
  3. %直列形 . `Name^sl ~SET %値 の `name$m 属性の値 ◎ Set serialized.[[Name]] to the value of value’s name attribute.
  4. %直列形 . `LastModified^sl ~SET %値 の `lastModified$m 属性の値 ◎ Set serialized.[[LastModified]] to the value of value’s lastModified attribute.

• その`逆直列化~手続き$は、 所与の ( %値, %直列形, %宛先~realm ) に対し，次を走らす： ◎ Their deserialization steps, given value and serialized, are:

  1. %値 の`~snapshot状態$ ~SET %直列形 . `SnapshotState^sl ◎ Set value’s snapshot state to serialized.[[SnapshotState]].
  2. %値 の下層の~byte列 ~SET %直列形 . `ByteSequence^sl ◎ Set value’s underlying byte sequence to serialized.[[ByteSequence]].
  3. %値 の `name$m 属性~値 ~SET %直列形 . `Name^sl に初期化する ◎ Initialize the value of value’s name attribute to serialized.[[Name]].
  4. %値 の `lastModified$m 属性~値 ~SET %直列形 . `LastModified^sl に初期化する ◎ Initialize the value of value’s lastModified attribute to serialized.[[LastModified]].

`File$I ~interfaceは、 `FileList$I 型の属性を公開する~objにて可用にされる。 その種の~objは~HTML `HTML$r にて定義されている。 `File$I ~objは、 `Blob$I を継承する変異-不能な~objであり， `読取n演算$が起動された時点で~memory内に読取n可能な~file~dataを表現する。 ~UAは、 読取n中に~fileが存在しなくなっていた場合には， `読取n~error$にするモノトスル — すなわち： ◎ The File interface is available on objects that expose an attribute of type FileList; these objects are defined in HTML [HTML]. The File interface, which inherits from Blob, is immutable, and thus represents file data that can be read into memory at the time a read operation is initiated. User agents must process reads on files that no longer exist at the time of read as errors,＼

• `FileReaderSync$I が （ Web Worker `WORKERS$r の下で） 利用されている場合 ⇒ `NotFoundError$E 例外を投出する ◎ throwing a NotFoundError exception if using a FileReaderSync on a Web Worker [Workers]＼
• 他の場合 ⇒ ［ `error$m 属性は `NotFoundError$E 例外を返す ］ようにした上で， `error$et `~eventを発火する$ ◎ or firing an error event with the error attribute returning a NotFoundError.

var %file = document.getElementById("filePicker").files[0];
var %date = new Date(%file.lastModified);
println(
    "選択された~file: " + %file.name +
    "~fileの最終更新日: " + %date.toDateString() + "."
);

...

/* 
特定の最終更新日が伴われた~fileを生成する
◎
Generate a file with a specific last modified date
 */

var %d = new Date(2013, 12, 5, 16, 23, 45, 600);
var %generatedFile = new File(
    ["Rough Draft ...."],
    "Draft1.txt",
    {type: "text/plain", lastModified: %d}
);

...

5. `FileList^I ~interface

注記： `FileList^I ~interfaceは “~risk下にある” ものと見なされるべきである。 ~Web~platformでは、 この種の~interfaceを `ECMA-262$r における `Array$I ~platform~objに置換するのが，趨勢なので。 特に、 `filelist.item(0)^c の類の構文は~risk下にある。 他のほとんどの［ ~programにおける `FileList^I の利用 ］については、 最終的に `Array^I 型に移行されたとしても，およそ影響されないものと見込まれる。 ◎ Note: The FileList interface should be considered "at risk" since the general trend on the Web Platform is to replace such interfaces with the Array platform object in ECMAScript [ECMA-262]. In particular, this means syntax of the sort filelist.item(0) is at risk; most other programmatic use of FileList is unlikely to be affected by the eventual migration to an Array type.

この~interfaceは、 `File$I ~objたちが成す`~list$を表現する。 以下、 この~listを指して，当の `FileList$I の~objの `~file~list@ と称する。 【この用語は、以下を明確化するため，この訳に導入している。】 ◎ This interface is a list of File objects.

[`Exposed$=(Window,Worker), `Serializable$]
interface `FileList@I {
  getter `File$I? `item＠#dfn-item$(`unsigned long$ %index);
  readonly attribute `unsigned long$ `length$m;
};

`FileList$I ~objは、 `直列化-可能$である： ◎ FileList objects are serializable objects.＼

• その`直列化~手続き$は、 所与の ( %値, %直列形 ) に対し，次を走らす： ◎ Their serialization steps, given value and serialized, are:

  1. %直列形 . `Files^sl ~SET 空`~list$ ◎ Set serialized.[[Files]] to an empty list.
  2. %値 の`~file~list$を成す ~EACH( %~file ) に対し ⇒ %直列形 . `Files^sl に %~file の`下位-直列化$を`付加する$ ◎ For each file in value, append the sub-serialization of file to serialized.[[Files]].

• その`逆直列化~手続き$は、 所与の ( %値, %直列形, %宛先~realm ) に対し，次を走らす： ◎ Their deserialization step, given serialized and value, are:

  1. %直列形 . `Files^sl を成す ~EACH( %~file ) に対し ⇒ %値 の`~file~list$に %~file の`下位-逆直列化$を`付加する$ ◎ For each file of serialized.[[Files]], add the sub-deserialization of file to value.

/* 
`uploadData^c は `form$e 要素 ／
`fileChooser^c は`~file入力~要素$
◎
uploadData is a form element
fileChooser is input element of type 'file'
 */
var %file = document.forms['uploadData']['fileChooser'].files[0];

/* 
等価な構文
◎
alternative syntax can be
 */
// var %file = document.forms['uploadData']['fileChooser'].files.item(0);

if(%file)
{
  /* 
~fileを開く
◎
Perform file ops
 */
}

注記： `HTML$r における `FileList^I 型の読専~属性を有する~interfaceには、 `HTMLInputElement$I, `DataTransfer$I がある。 前者は，上の例でも~accessされている。 ◎ Note: The HTMLInputElement interface has a readonly attribute of type FileList, which is what is being accessed in the above example. Other interfaces with a readonly attribute of type FileList include the DataTransfer interface.

6. ~dataの読取n法

[`Exposed$=(Window,Worker)]
interface `FileReader@I: `EventTarget$I {
  `FileReader$mc();
  /* 
`非同期~読取n~method$
◎
async read methods
 */
  `undefined$ `readAsArrayBuffer$m(`Blob$I %blob);
  `undefined$ `readAsBinaryString$m(`Blob$I %blob);
  `undefined$ `readAsText$m(`Blob$I %blob, optional `DOMString$ %encoding);
  `undefined$ `readAsDataURL$m(`Blob$I %blob);
  `undefined$ `abort()$m;

  /* 
状態
◎
states
 */
  const `unsigned short$ `EMPTY@m = 0;
  const `unsigned short$ `LOADING@m = 1;
  const `unsigned short$ `DONE@m = 2;

  readonly attribute `unsigned short$ `readyState$m;

  /* 
`File^I または `Blob^I ~data
◎
File or Blob data
 */
  readonly attribute (`DOMString$ or `ArrayBuffer$)? `result$m;

  readonly attribute `DOMException$I? `error$m;

  /* 
~event~handler内容~属性
◎
event handler content attributes
 */
  attribute `EventHandler$I `onloadstart$m;
  attribute `EventHandler$I `onprogress$m;
  attribute `EventHandler$I `onload$m;
  attribute `EventHandler$I `onabort$m;
  attribute `EventHandler$I `onerror$m;
  attribute `EventHandler$I `onloadend$m;

};

[
 `Exposed$=(DedicatedWorker,SharedWorker)]
interface `FileReaderSync@I {
  `FileReaderSync$mc();

  /* 
同期的に文字列を返す
◎
Synchronously return strings
 */

  `ArrayBuffer$ `readAsArrayBuffer$mS(`Blob$I %blob);
  `DOMString$ `readAsBinaryString$mS(`Blob$I %blob);
  `DOMString$ `readAsText$mS(`Blob$I %blob, optional `DOMString$ %encoding);
  `DOMString$ `readAsDataURL$mS(`Blob$I %blob);
};

7. ~errorと例外

`読取n~error@ は下層の~file~systemから~fileを読取る際に生じ得る。 起こり得る~errorのいくつかを下に挙げる。 これらは `参考^em である。 ◎ File read errors can occur when reading files from the underlying filesystem. The list below of potential error conditions is informative.

• ~accessされている`~Blob$ 【が参照rしている~data】 は、［ `非同期~読取n~method$／`同期~読取n~method$ ］が~callされた時点では，存在しないかもしれない。 例えば、 その参照が獲得された後に移動されたか削除されたことに因り （例：他の~appにより同時並行に）。 `NotFoundError$E を見よ。 ◎ The File or Blob 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 NotFoundError.
• `~Blob$は読取n不能かもしれない。 例えば、 `~Blob$への参照が獲得された後の許可~問題に因り （例：他の~appにより同時並行に~lockされたなど）。 あるいは，`~snapshot状態$が変化したかもしれない。 `NotReadableError$E を見よ。 ◎ A File or Blob may be unreadable. This may be due to permission problems that occur after a reference to a File or Blob has been acquired (e.g. concurrent lock with another application). Additionally, the snapshot state may have changed. See NotReadableError.
• ~UAは，一部の~fileについて ~Web~app内での利用を安全でないものと決定してもヨイ。 ~disk上の~fileは 元々の~file選択から変化し得るので、 読取n結果は無効なものになり得る。 加えて、 一部の~fileや~directory構造は，下層の~file~systemにおいて制約されていることもある。 例えば、 それらからの読取nは，~security違反と見なされ得る。 `§ ~securityの考慮点＠#security-discussion$, `SecurityError$E を見よ。 ◎ 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 § 9 Security and Privacy Considerations and SecurityError.

8. `Blob^I ／ `MediaSource^I への~URL参照

この節では［ `~Blob$／ `MediaSource$I ~obj ］を指すために利用される`~URL$の`~scheme$urlを定義する。 ◎ This section defines a scheme for a URL used to refer to Blob and MediaSource objects.

[`Exposed$=(Window,DedicatedWorker,SharedWorker)]
partial interface `URL$I {
    static `DOMString$ `createObjectURL$m((`Blob$I or MediaSource) %obj);
    static `undefined$ `revokeObjectURL$m(`DOMString$ %url);
};

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

%url = URL.createObjectURL(%blob);
%img1.src = %url;
%img2.src = %url;

var %blobURLref = URL.createObjectURL(%file);
%img1 = new Image();
%img2 = new Image();

/* 
次の両~代入とも期待したとおり働く：
◎
Both assignments below work as expected
 */
%img1.src = %blobURLref;
%img2.src = %blobURLref;

/* 
… body の読込nに後続して、
画像が 2 つとも読込まれたかどうか検査する
◎
... 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);
}

9. ~security／~privacyの考慮点

この仕様は、 ~Web内容が［ 下層の~file~systemから~fileを読取る ］ことを許容し，一意な識別子を通して~fileに~accessする手段を与えるが、 その種のものは~securityの考慮点になる。 この仕様は、［ 利用者は，首に~HTML~form内の`~file入力~要素$に対しヤリトリしていて、 `FileReader$I ~objから読取られるすべての~fileは， 最初に利用者の手により選択されたものである ］と見做している。 重要な~security上の考慮点には、 次が挙げられる ⇒＃ 悪意的な~file選択攻撃（選択looping）の防止-法, `~systemに敏感な~file$への~accessの防止-法, 選択-後の~disk上の~fileに対する改変からの防護-法 ◎ 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.

`選択looping@ の防止-法 ◎ Preventing selection looping

~file選択の間、 利用者は，`~file入力~要素$に結付けられた~file~pickerにより爆撃され得る （選択しない限り，~file~pickerが際限なく現れる “選択強制” ）。 ~UAは、 返される `FileList$I ~objの~sizeを 0 にすることにより，~file~accessを防止してもヨイ。 ◎ 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に敏感な~file@ （ `system-sensitive files^en） ◎ System-sensitive files

そのような~file （例： `/usr/bin/^c 内の~file, `password^c ~file, ~OSに~nativeな他の実行-可能~file）は、 概して，~Web内容に公開されるべきではないので、 `~blob~URL$を通して~accessされるべきではない。 ~UAは ⇒＃ `同期~読取n~method$用には `SecurityError$E 例外を`投出-$してもヨイ／ `非同期~読取n~method$用には `SecurityError$E 例外を返してもヨイ ◎ (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 exception for asynchronous reads.

課題： この節は、 暫定的である。 後続な草案には、 さらなる~security考慮点が補足され得る。 ◎ This section is provisional; more security data may supplement this in subsequent drafts.

10. 要件と利用事例

この節では、 この~API用にどのような要件が課されるかについて, および 一部の利用事例についての~~説明を与える。 この~versionの~APIは、 すべての利用事例に応えるものではない。 それらに取組むことは後続な~versionに委ねられる。 ◎ 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.

• 利用者からの許可を得たなら、 ~UAは，~local~fileからの~dataを ~program的に直に読取って構文解析する能を供するべきである。 ◎ Once a user has given permission, user agents should provide the ability to read and parse data directly from a local file programmatically.

  例： 歌詞~viewer。 利用者は自身の plist ~file【プレイリスト】から楽曲の歌詞を読みたいとする。 利用者は plist ~fileを閲覧するとき、 ~fileは［ 開かれ, 読取られ, 構文解析され ］，~Web~appの中で［ ~sort可能, 動作~可能 ］な一覧として利用者に示される。 利用者は曲を選択してその歌詞を閲覧できる。 利用者は “~fileを閲覧する” ~dialogを利用する。 ◎ 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は後の利用のために~localに格納できるべきである。 それは~Web~appにおける~offline~data~accessに有用になる。 ◎ 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.

  例： ~Calendar~app。 利用者の会社には予定表があり、 利用者は自身の~eventと会社の “多忙期間” として~markされた予定表との同期cを（個人-情報が漏れないように）とりたいとする。 利用者は、 一覧から~fileを探して選択する。 【~MIME型】 `text/calendar^c ~fileは、 ~browserにより構文解析され，単一の予定表~viewに併合できるようになる。 利用者は、 それを自分用の予定表~fileに保存することも（ “~~別名で保存-…” を利用して）， 統合された予定表~fileを非同期に送信して~serverに格納することもできる。 ◎ 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.

• ~UAは、 所与の~dataと~file名から，~program的に~local~fileに保存する能を供するべきである。 ◎ User agents should provide the ability to save a local file programmatically given an amount of data and a file name.

  注記： この仕様は，~downloadを誘発させる明示的な~API~callは供さないが、 それは~HTML仕様にて取組まれている。 `a$e 要素の `download$a 属性 `HTML$r は、 ~downloadを起動させ， `File$I を指定された名前で保存する。 この~APIと `a^e 要素の `download^a 属性との組合nにより、 ~Web~appの中で~fileを作成して，~localに保存することが可能になる。 ◎ 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 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.

  例： ~spreadsheet~app。 利用者は、 ~formを通して何らかの入力を生成する。 その入力から~spreadsheetに組み入れられる CSV （ `Comma Separated Variables^en ）出力が生成され， “保存-…” が行われる。 生成された出力は、 ~Webに基づく~spreadsheetへ直に統合することも， 非同期に~uploadすることもできる。 ◎ 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.

• ~UAは、 今日における~formに基づく~uploadよりも効率的に働くような，［ ~fileから~dataを~remote~serverへ滞りなく送信する ］ための~program的な能を供するべきである。 ◎ 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.

  例： 動画や写真の~upload~app。 利用者は~uploadに巨大な~fileを選択でき，~chunkごとに~serverに送信できる。 ◎ A Video/Photo Upload App.＼ User is able to select large files for upload, which can then be "chunk-transfered" to the server.

• ~UAは、 上に挙げた特能を可能にする~APIを~scriptに公開するべきである。 ~file~systemとのヤリトリに入るときは、 常に，~UIを通して利用者に通知される — あらゆる~transactionを［ 取消す／中止する ］能を利用者に与えるよう。 いかなる~file選択も，利用者に通知され、 利用者は，それを取消せる。 これらの~APIが、 利用者の介入を経ずに黙って呼出されることはない。 ◎ 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.

謝辞

この仕様は元々は SVG Working Group により開発された。 `Mark Baker^en, `Anne van Kesteren^en 両氏からの~feedbackに。 ◎ This specification was originally developed by the SVG Working Group. Many thanks to Mark Baker and Anne van Kesteren for their feedback.

元々の仕様の編集を行った `Robin Berjon^en, `Jonas Sicking^en, `Vsevolod Shmyroff^en 各氏に。 ◎ Thanks to Robin Berjon, Jonas Sicking and Vsevolod Shmyroff 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.

W3C WebApps WG, および public-webapps@w3.org listserv の参加者達に。 ◎ Thanks to the W3C WebApps WG, and to participants on the public-webapps@w3.org listserv