1. 序論
~INFORMATIVE~Web~appは、~fileを~remoteの~serverへ~uploadしたり, 多彩な~Web~appの中で扱うことも含め、利用者からの入力を可能な限り広範囲に扱えるようになっているべきである。 この仕様は、~file, ~fileの~list, ~fileに~accessする際の~error, ~fileを~program的に読取る仕方についての基本的な表現を定義する。 加えて、適合~UAの~main~threadと非同期に処理し得る “生~data” を表現する~interfaceも定義する。 仕様で定義される~interfaceと~APIは、 ~Web~platformに公開されている他の~interfaceや~APIと伴用し得るものになる。 ◎ 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. Additionally, this specification also defines an interface that represents "raw data" which can be asynchronously processed on the main thread of conforming user agents. 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" — 元々は Google Gears の~Web~APIに由来する名称)は、変異-不能な生~dataを表現する。 `File$I/`Blob$I の読取は~main~threadと非同期に行われるべきものであり、~thread化された~Web~app 【~worker環境下】 においては,同期的~APIを利用する選択肢もある。 非同期~APIによる~fileの読取りにより、~UAの~main~threadの~UIの “無反応” は防止される。 この仕様は、 `File$I/`Blob$I ~dataの読取りと~access用に、~event~model に基づく非同期~APIを定める。 `FileReader$I ~objは、~event~handler内容~属性と~eventの発火を通して ~file~dataへの~accessを行うための,`非同期~読取り~method$を供する。 ~eventと~event~handlerの利用により、読取りの進捗を監視するとき(~file~accessの処理能が~local~driveとは異なる,~remoteの~driveや~mountされた~driveに特に有用になる)と, ~file読取り中に起こり得る`~error条態$を監視するときとで,別々の~code-blockを利用できるようになる。 例で示す: ◎ 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. 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.
次の例では[ 進捗, ~error, 成功 ]の,それぞれの条態に応じて、別々の~code-blockが取扱う。 ◎ In the example below, different code blocks handle progress, error, and success conditions.
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を終了し~MUSTことを意味する。 この仕様で定義される`非同期~読取り~method$は、当の~algoが終了される前に呼び出し元に戻ることがあり、また, `abort()$m 呼び出しにより終了され得る。 ◎ 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( %a, %b ) / min( %a, %b ) ]は、 `WebIDL$r の定義に従い %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@ は、時刻 00:00:00 UTC 1970 年 1 月 1 日( 1970-01-01T00:00:00Z ISO 8601 )を指す。 これは、 `ECMA-262$r においては,概念的な 時刻 “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].
【この訳に固有の表記規約】
この訳の,~algoや定義の記述に利用されている各種記号( ~LET, ~IF, ~THROW, 此れ, 等々)の意味や定義の詳細は,~SYMBOL_DEF_REFを~~参照されたし。
`~Blob@ とは、 `Blob$I ~interfaceを実装する~objの略記である(したがって, `File$I ~interfaceを実装する~objも含まれる)。
原文が参照している `MIMESNIFF$r の用語には、今や,廃された/改称されたものもある。 この訳では、その現在の仕様に揃うように,手を加えている — 例えば,原文の “media type” に代えて、 “`~MIME型$( MIME type )” を利用している。
3. `Blob^I ~interfaceと~binary~data
各 `~Blob$は、次のものを内部的に持つ:
- `参照~byte列@
- ~objが自身の~dataとして参照する`~byte列$。 ~objの `size$m 属性は,`参照~byte列$の総~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.
- `~snapshot状態@
- `参照~byte列$が下層~storageから得られるものである場合にのみ,その~storageの状態を反映するものとして,持た~MUST。 `~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.
[`Blob$mC(optional sequence<`BlobPart$I> `blobParts$V, optional `BlobPropertyBag$I `options$V), `Exposed$=(Window,Worker), `Serializable$] interface `Blob@I { readonly attribute unsigned long long `size$m; readonly attribute `DOMString$I `type$m; /* `Blob^I から~byte範囲の~chunkを切出す ◎ slice Blob into byte-ranged chunks */ Blob slice( [`Clamp$] optional long long `start$V, [`Clamp$] optional long long `end$V, optional `DOMString$I `contentType$V ); }; enum `EndingType$I { `transparent@l, `native@l }; dictionary `BlobPropertyBag@I { `DOMString$I `type$dm = ""; `EndingType$I `endings$dm = `transparent$l; }; typedef (`BufferSource$I or `Blob$I or USVString) `BlobPart@I;
`Blob$I ~objは、`直列化-可能$である: ◎ Blob objects are serializable objects.\
-
その`直列化~手続き$は、所与の ( %値, %直列形 ) に対し,次を走らす: ◎ Their serialization steps, given value and serialized, are:
- %直列形 . `SnapshotState^sl ~SET %値 の`~snapshot状態$ ◎ Set serialized.[[SnapshotState]] to value’s snapshot state.
- %直列形 . `ByteSequence^sl ~SET %値 の下層の~byte列 ◎ Set serialized.[[ByteSequence]] to value’s underlying byte sequence.
-
その`逆直列化~手続き$は、所与の ( %値, %直列形 ) に対し,次を走らす: ◎ Their deserialization step, given serialized and value, are:
- %値 の`~snapshot状態$ ~SET %直列形 . `SnapshotState^sl ◎ Set value’s snapshot state to serialized.[[SnapshotState]].
- %値 の下層の~byte列 ~SET %直列形 . `ByteSequence^sl ◎ Set value’s underlying byte sequence to serialized.[[ByteSequence]].
3.1. ~Blob構築子
`Blob(blobParts, options)@m の被呼出時には、次を走らせ~MUST ◎ The Blob() constructor can be invoked with zero or more parameters. When the Blob() constructor is invoked, user agents must run the following steps:
- %種別 ~LET 空~文字列 ◎ ↓
- %~byte列 ~LET 0 ~byteの~data ◎ ↓ ◎ If invoked with zero parameters, return a new Blob object consisting of 0 bytes, with size set to 0, and with type set to the empty string.
- ~IF[ %blobParts は与えられている ] ⇒ %~byte列 ~LET `~blobを成す各部位を処理する$( `blobParts$V, `options$V ) ◎ Let bytes be the result of processing blob parts given blobParts and options.
- ~IF[ `options$V に `type$dm ~member %m は`在する$ ]~AND[ %m の値 %v を成すどの文字も 範囲 { `0020^U 〜 `007E^U } に入る ] ⇒ %種別 ~SET `~ASCII小文字~化する$( %v ) ◎ If the type member of the optional options argument is provided and is not the empty string, run the following sub-steps: • Let t be the type dictionary member. If t contains any characters outside the range U+0020 to U+007E, then set t to the empty string and return from these substeps. • Convert every character in t to ASCII lowercase.
-
~RET 次のように初期化された,新たな `Blob$I ~obj ⇒# `参照~byte列$ ~SET %~byte列, `size$m ~SET %~byte列 の長さ, `type$m ~SET %種別 ◎ Return a Blob object referring to bytes as its associated byte sequence, with its size set to the length of bytes, and its type set to the value of t from the substeps above.
3.1.1. 構築子に渡す引数
`Blob()$m 構築子は、次を引数に呼出せる: ◎ The Blob() constructor can be invoked with the parameters below:
- `blobParts@V ◎ A blobParts sequence
- 任意の要素~数からなる~IDL連列~型の引数であって、その各~要素ごとに,次の いずれかの型の値をとり得る ⇒ `BufferSource$I / `Blob$I / `DOMString$I ◎ which takes any number of the following types of elements, and in any order: • BufferSource elements. • Blob elements. • USVString elements.
- `options@V ◎ An optional BlobPropertyBag
-
この `BlobPropertyBag$I 辞書~型~引数(省略可)は、次の~memberを持つ: ◎ which takes these optional members:
- `type@dm
- `~Blob$の~MIME型を表現する,~ASCII小文字に符号化された文字列。 この~memberに対する規定は、 `Blob^I 構築子 節にて与えられる。 ◎ type, the ASCII-encoded string in lower case representing the media type of the Blob. Normative conditions for this member are provided in the §3.1 Constructors.
- `endings@dm
- とり得る値は、既定の `transparent$l, または `native$l 。 ◎ endings, an enum which can take the values "transparent" or "native".\
- `native$l に設定された場合、 `blobParts$V 内の `USVString^I %S は,次の結果にされることになる ⇒ `~native行末に変換する$( %S ) ◎ By default this is set to "transparent". If set to "native", line endings will be converted to native in any USVString elements in blobParts.
- 【 この引数が省略された場合、 `WebIDL$r に従って,空の辞書~値が渡されたものと見なされ、各~memberは既定の値をとることになる。 】
`~blobを成す各部位を処理する@ ときは、所与の ( 一連の `BlobPart$I 値が成す連列 %parts, `BlobPropertyBag$I 型の値 %options ) に対し,次を走らす: ◎ To process blob parts given a sequence of BlobPart's parts and BlobPropertyBag options, run the following steps:
- %~byte列 ~LET 空`~byte列$ ◎ Let bytes be an empty sequence of bytes.
-
%parts を成す~EACH ( %e ) に対し,順に ⇒ %~byte列 に[ %e の型に応じて 次の下位手続きを走らせた結果 ]を付加する: ◎ For each element in parts:
- `USVString^I ◎ If element is a USVString, run the following substeps:
-
- ~IF[ %options の `endings$dm ~member ~EQ `native$l ] ⇒ %e ~SET `~native行末に変換する$( %e ) ◎ Let s be element. ◎ If the endings member of options is "native", set s to the result of converting line endings to native of element.
- ~RET `~UTF-8符号化する$( %e ) ◎ Append the result of UTF-8 encoding s to bytes.
- 注記: ~Unicode文字~並びに変換する~algo `WebIDL$r は、`~JS文字列$内の対を成さない(従って妥当でない)`~surrogate$を, `FFFD^U 置換文字に置換する。 そのため、 `Blob$I 構築子においては,文字~並びの喪失や並び替わりによる何らかの~data欠損も生じ得る。 ◎ Note: The algorithm from WebIDL [WebIDL] replaces unmatched surrogates in an invalid utf-16 string with U+FFFD replacement characters. Scenarios exist when the Blob constructor may result in some data loss due to lost or scrambled character sequences.
- `BufferSource$I
- ~RET %e が保持している`~byte列の複製を取得-$した結果 ◎ If element is a BufferSource, get a copy of the bytes held by the buffer source, and append those bytes to bytes.
- `~Blob$
- ~RET %e が表現する~byte列 ◎ If element is a Blob, append the bytes it represents to bytes.
- %e の `type$m 属性は無視され、返される`~Blob$の `type$m には影響しない。 ◎ Note: The type of the Blob array element is ignored and will not affect type of returned Blob object.
- ~RET %~byte列 ◎ Return bytes.
`~native行末に変換する@ ときは、所与の ( `文字列$ %s ) に対し,次を走らす: ◎ To convert line endings to native in a string s, run the following steps:
- %CR ~LET `文字$ `000D^U CR ◎ ↓
- %LF ~LET `文字$ `000A^U LF ◎ ↓
- %~native行末 ~LET [ 下層の~platform規約は 改行文字を[ %CR, %LF ]並びとして表現するならば その並び / ~ELSE_ %LF のみ ]が成す文字列 ◎ Let native line ending be be the code point U+000A LF. ◎ If the underlying platform’s conventions are to represent newlines as a carriage return and line feed sequence, set native line ending to the code point U+000D CR followed by the code point U+000A LF.
- %結果 ~SET 空`文字列$ ◎ Set result to the empty string.
- %位置 ~LET %s の先頭を指している`位置~変数$ ◎ Let position be a position variable for s, initially pointing at the start of s.
-
~WHILE %位置↗ ~NEQ ε ◎ *不要 Let token be the result of collecting a sequence of code points that are not equal to U+000A LF or U+000D CR from s given position. ◎ Append token to result. ◎ While position is not past the end of s:
-
~IF[ %位置↗ ~IN { %CR, %LF } ]:
- %結果 に %~native行末 を付加する
- ~IF[ %位置↗ ~EQ %CR ]~AND[ ( %位置 ~PLUS 1 )↗ ~EQ %LF ] ⇒ %位置 ~INCBY 1
- %位置 ~INCBY 1
- %結果 に次の結果を付加する ⇒ %s 内の %位置 から[ %LF, %CR ]でない`符号位置~並びを収集する$ ◎ Let token be the result of collecting a sequence of code points that are not equal to U+000A LF or U+000D CR from s given position. ◎ Append token to result.
-
- ~RET %結果 ◎ Return result.
構築子の用例: ◎ Examples of constructor usage follow.
/* 新たな `Blob^I ~objを作成する ◎ Create a new Blob object */ var %a = new Blob(); /* 1024 ~byteの `ArrayBuffer^I を作成する ◎ Create a 1024-byte ArrayBuffer */ /* ~bufferは `File^I 読取りからも得られる ◎ 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]);
3.2. 属性
- `size@m
- `参照~byte列$の~sizeを~byte数で返す。 ◎ size, of type unsigned long long, readonly ◎ Returns the size of the byte sequence in number of bytes.\
- 取得子は、次を返さ~MUST ⇒ [ `FileReader$I / `FileReaderSync$I ]~objにより読取られた,総~byte数 ◎ On getting, conforming user agents must return the total number of bytes that can be read by a FileReader or FileReaderSync object, or 0 if the Blob has no bytes to be read.
- `type@m
- `~Blob$の~MIME型を表現する,~ASCII小文字に符号化された文字列。 ◎ type, of type DOMString, readonly ◎ The ASCII-encoded string in lower case representing the media type of the Blob.\
-
取得子は、次を返さ~MUST:
- ~MIME型を決定できるならば、[ ~byte列に変換した結果が`構文解析-可能な~MIME型$になる ]ような,~ASCII小文字に符号化された文字列
- 他の場合は、空~文字列(~byte列に変換されたときに 0 ~byteになる)
- この属性は、~Web~app自身からも[ 構築子/ `slice()$m ]の~callを通して設定できる。 これらの場合に適用される更なる規定は、[ `Blob^I 構築子 節, `File^I 構築子 節 / `slice()^m ~method 節 ]にて与えられる。
- ~UAは、 `~Blob$の `type$m を,とりわけ `参照~byte列$が~disk上の~file由来のものである場合に 決定できる。 この場合に適用される更なる規定は、`~file型~指針$にて与えられる。 ◎ The type attribute can be set by the web application itself through constructor invocation and through the slice() call; in these cases, further normative conditions for this attribute are in §3.1 Constructors, §4.1 Constructor, and §3.3.1 The slice method respectively. User agents can also determine the type of a Blob, especially if the byte sequence is from an on-disk file; in this case, further normative conditions are in the file type guidelines.
- 注記: `~Blob$の `type$m は、それを表現している~ASCIIに符号化された文字列を~byte列に変換した結果を `~MIME型の構文解析-$~algoに渡した結果が `失敗^i でないとき, `構文解析-可能な~MIME型@† であるものと見なされる。 ◎ Note: The type t of a Blob is considered a parsable MIME type, if performing the parse a MIME type algorithm to a byte sequence converted from the ASCII-encoded string representing the Blob object’s type does not return undefined.
- 【† 原文のこの用語は,実際には `MIMESNIFF$r を参照しているが、その用語は,今や廃されている。 おそらく,この用語を利用している箇所は、`妥当な~MIME型$を利用するべきであろう。 】
- 注記: `type$m 属性は、`符号化法を決定-$するとき, および `~blob~URL$を`~fetch$する際に `Content-Type^h ~headerを決定するとき ◎ Note: Use of the type attribute informs the encoding determination and determines the Content-Type header when fetching blob URLs.
3.3. ~methodと引数
- `slice(start, end, contentType)@m
-
この~method(引数はいずれも省略可)は、次のようにされた新たな `Blob$I ~objを返す:
- その`参照~byte列$は、此れの`参照~byte列$の中の,[ `start@V 引数から `end@V 引数の直前まで ]の範囲( 0 が最初の~byteを指す)を成す~byte列。
- その `type$m 属性は、 `contentType@V 引数で与えられる — それは、 `Blob^I の~MIME型を表現する。
-
被呼出時には、次に従って動作し~MUST: ◎ It must act as follows:
- %size ~LET 此れの`参照~byte列$の総~byte数 ◎ ↓
-
%start ~SET `start$V に応じて,次で与えられる値:
- 省略時は 0
- 負の場合は max( ( %size + `start$V ), 0)
- 他の場合は min( `start$V, %size )
-
%end ~SET `end$V に応じて,次で与えられる値:
- 省略時は %size
- 負の場合は max( ( %size + `end$V ), 0 )
- 他の場合は min( `end$V, %size )
- %内容~型 ~LET 空~文字列 ◎ ↓
- ~IF[ `contentType$V は与えられている ]~AND[ `contentType$V を成すどの文字も 範囲 { `0020^U 〜 `007E^U } に入る ] ⇒ %内容~型 ~SET `~ASCII小文字~化する$( `contentType$V ) ◎ The optional contentType parameter is used to set the ASCII-encoded string in lower case representing the media type of the Blob. User agents must process the slice with contentType normalized according to the following: ◎ If the contentType parameter is not provided, let relativeContentType be set to the empty string. ◎ Else let relativeContentType be set to contentType and run the substeps below: ◎ If relativeContentType contains any characters outside the range of U+0020 to U+007E, then set relativeContentType to the empty string and return from these substeps. ◎ Convert every character in relativeContentType to ASCII lowercase.
- %span ~LET max( ( %end − %start ), 0 ) ◎ Let span be max((relativeEnd - relativeStart), 0).
- %data ~LET 此れの`参照~byte列$の中の,~byte位置 %start から連続する %span 個の`~byte列$ ◎ ↓
- ~RET 次のように初期化された,新たな `Blob$I ~obj ⇒# `参照~byte列$ ~SET %data, `size$m 属性 ~SET %span, `type$m 属性 ~SET %内容~型 ◎ Return a new Blob object S with the following characteristics: • S refers to span consecutive bytes from O, beginning with the byte at byte-order position relativeStart. • S.size = span. • S.type = relativeContentType.
-
種々の `slice()$m ~call例 — この例では、 `Blob$I ~interfaceを継承する `File$I ~interfaceを利用している: ◎ The examples below illustrate the different types of slice() calls possible. Since the File interface inherits from the Blob interface, examples are based on the use of the File interface.
/* 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列$が~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にとって実装するのは自明でない要件であるため、 “〜し~MUST” ではなく, “〜する~SHOULD” とされている `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を参照している場合、~UAは,~objの `type$m 属性の取得子が[ 以下に与える `~file型~指針@ に従うような,~MIME型 ]を返すようにし~MUST: ◎ 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になる)
- [ `~Blob$の `type$m ~EQ `text/plain^l ]の場合 ⇒ ~MIME型の[ `~parameter~map$ `MIMESNIFF$r にあたる部位 ]には、~charset~parameterを付加しないこと。 ◎ 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.
[`File$mC( sequence<`BlobPart$I> `fileBits$V, `USVString$I `fileName$V, optional `FilePropertyBag$I `fileOptions$V ), `Exposed$=(Window,Worker), `Serializable$] interface `File@I : `Blob$I { readonly attribute `DOMString$I `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:
- %直列形 . `SnapshotState^sl ~SET %値 の`~snapshot状態$ ◎ Set serialized.[[SnapshotState]] to value’s snapshot state.
- %直列形 . `ByteSequence^sl ~SET %値 の下層の~byte列 ◎ Set serialized.[[ByteSequence]] to value’s underlying byte sequence.
- %直列形 . `Name^sl ~SET %値 の `name$m 属性の値 ◎ Set serialized.[[Name]] to the value of value’s name attribute.
- %直列形 . `LastModified^sl ~SET %値 の `lastModified$m 属性の値 ◎ Set serialized.[[LastModified]] to the value of value’s lastModified attribute.
-
その`逆直列化~手続き$は、所与の ( %値, %直列形 ) に対し,次を走らす: ◎ Their deserialization steps, given value and serialized, are:
- %値 の`~snapshot状態$ ~SET %直列形 . `SnapshotState^sl ◎ Set value’s snapshot state to serialized.[[SnapshotState]].
- %値 の下層の~byte列 ~SET %直列形 . `ByteSequence^sl ◎ Set value’s underlying byte sequence to serialized.[[ByteSequence]].
- %値 の `name$m 属性~値 ~SET %直列形 . `Name^sl に初期化する ◎ Initialize the value of value’s name attribute to serialized.[[Name]].
- %値 の `lastModified$m 属性~値 ~SET %直列形 . `LastModified^sl に初期化する ◎ Initialize the value of value’s lastModified attribute to serialized.[[LastModified]].
4.1. `File^I の構築子
- `File(fileBits, fileName, fileOptions)@m
- この構築子は、 %fileOptions 辞書~引数(省略可)を利用するかどうかに応じて, 2 個または 3 個の引数で呼出される。 ◎ The File constructor is invoked with two or three parameters, depending on whether the optional dictionary parameter is used.\
-
被呼出時には、次を走らせ~MUST: ◎ When the File() constructor is invoked, user agents must run the following steps:
- %~byte列 ~LET `~blobを成す各部位を処理する$( `fileBits$V , `fileOptions$V ) ◎ Let bytes be the result of processing blob parts given fileBits and options.
-
%名前 ~LET `fileName$V 引数を複製した結果の中の各 `002F^U ( `/^l ) を `003A^U ( `:^l ) に置換した結果 ◎ Let n be a new string of the same size as the fileName argument to the constructor. Copy every character from fileName to n, replacing any "/" character (U+002F SOLIDUS) with a ":" (U+003A COLON).
注記: ~file名に用いられる規約は、下層の~OS~file~system間で異なる — 構築された~fileに対する UTF-16 の義務付けは、~file名が`~byte列$に変換されたときの多義性を起こり難くする。 ◎ Note: Underlying OS filesystems use differing conventions for file name; with constructed files, mandating UTF-16 lessens ambiquity when file names are converted to byte sequences.
- %種別 ~LET 空~文字列 ◎ ↓
- %日時 ~LET `Unix Epoch$ から経過したミリ秒数( `Date.now()^m `ECMA-262$r と等価) ◎ ↓
- ~IF[ `fileOptions$V に `type$dm ~member %m は`在する$ ]~AND[ %m の値 %v を成すどの文字も 範囲 { `0020^U 〜 `007E^U } に入る ] ⇒ %種別 ~SET `~ASCII小文字~化する$( %v ) ◎ *不要 If the optional FilePropertyBag dictionary argument is used, then run the following substeps: ◎ If the type member is provided and is not the empty string, let t be set to the type dictionary member. If t contains any characters outside the range U+0020 to U+007E, then set t to the empty string and return from these substeps. ◎ Convert every character in t to ASCII lowercase.
-
~IF[ `fileOptions$V に `lastModified$dm ~memberは`在する$ ] ⇒ %日時 ~SET その値 ◎ If the lastModified member is provided, let d be set to the lastModified dictionary member. If it is not provided, set d to the current date and time represented as the number of milliseconds since the Unix Epoch (which is the equivalent of Date.now() [ECMA-262]).
注記: `ECMA-262$r `Date$I ~objは, `Unix Epoch$ から経過したミリ秒数を表現する `long long^c 値に変換されるので、 `lastModified$dm ~member値に `Date^I ~objを渡すこともできる。 ◎ Note: Since ECMA-262 Date objects convert to long long values representing the number of milliseconds since the Unix Epoch, the lastModified member could be a Date object [ECMA-262].
- ~RET 次のように初期化された,新たな `File$I ~obj ⇒# `参照~byte列$ ~SET %~byte列, `size$m ~SET %~byte列 の総~byte数, `name$m ~SET %名前, `type$m ~SET %種別, `lastModified$m ~SET %日時 ◎ Return a new File object F such that: • F refers to the bytes byte sequence. • F.size is set to the number of total bytes in bytes. • F.name is set to n. • F.type is set to t. • F.lastModified is set to d.
4.1.1. 構築子に渡す引数
`File()$m 構築子は次の引数を伴って呼出され得る: ◎ The File() constructor can be invoked with the parameters below:
- `fileBits@V
- `blobParts$V と同じ。 ◎ A fileBits sequence which takes any number of the following elements, and in any order: ◎ BufferSource elements. ◎ Blob elements, which includes File elements. ◎ USVString elements.
- `fileName@V
- ~fileの名前を表現する `USVString$I 型の文字列。 この引数に対する規定は, `File^I 構築子 節 にて与えられる。 ◎ A USVString parameter representing the name of the file; normative conditions for this constructor parameter can be found in §4.1 Constructor.
- `fileOptions@V ◎ An optional FilePropertyBag dictionary
-
この `FilePropertyBag$I 辞書~型~引数(省略可)は、 `BlobPropertyBag$I の~memberに加えて,次の~memberを持つ(いずれも省略可): ◎ which in addition to the members of BlobPropertyBag takes one member:
- `lastModified@dm
- ~fileの更新日を表現する, `long long^c 型~値。 この~memberに対する規定は, `File^I 構築子 節 にて与えられる。 ◎ An optional lastModified member, which must be a long long; normative conditions for this member are provided in §4.1 Constructor.
- 【 `options$V と同様に、この引数も,構築子を呼出すときに省略された場合、空の辞書~値が渡されたものと見なされる。 】
- 【 原文の引数~名は %options だが、 `Blob()$m 構築子の同じ名前の引数と紛らわしいので,名前を違えている。 】
4.2. 属性
- `name@m
- ~fileの名前。 ◎ name, of type DOMString, readonly
- 取得子は、~fileの名前を文字列として返さ~MUST。 ~file名には,下層の~OS~file~system間でいくつもの規約があるが、これは~path情報を持たない単なる~fileの名前である。 ~UAは、取得-時に この情報を可用にできない場合は,空~文字列を返さ~MUST。 ◎ The name of the file. On getting, this must return the name of the file as a string. There are numerous file name variations and conventions used by different underlying OS file systems; this is merely the name of the file, without path information. On getting, if user agents cannot make this information available, they must return the empty string.\
- 構築子を用いて作成された `File$I ~objにおける,この属性に適用される更なる規定は、 `File^I 構築子 節 にて与えられる。 ◎ If a File object is created using a constructor, further normative conditions for this attribute are found in §4.1 Constructor.
- `lastModified@m
- ~fileの最終更新日。 ◎ lastModified, of type long long, readonly
- 取得子は、次を返さ~MUST ⇒ [ この情報を可用にできるならば、 ~fileの最終更新日 / 知り得ない場合は現在の日時( `Date.now()^m `ECMA-262$r に等価) ]を表す[ `Unix Epoch$ から経過したミリ秒数による `long long^I 型の値 ] ◎ The last modified date of the file. On getting, if user agents can make this information available, this must return a long long set to the time the file was last modified as the number of milliseconds since the Unix Epoch. If the last modification date and time are not known, the attribute must return the current date and time as a long long representing the number of milliseconds since the Unix Epoch; this is equivalent to Date.now() [ECMA-262].\
- 構築子を用いて作成された `File$I ~objにおける,この属性に適用される更なる規定は、 `File^I 構築子 節 にて与えられる。 ◎ If a File object is created using a constructor, further normative conditions for this attribute are found in §4.1 Constructor.
`File$I ~interfaceは、 `FileList$I 型の属性を公開する~objにて可用にされる。 その種の~objは~HTML `HTML$r にて定義されている。 `File$I ~objは、 `Blob$I を継承する変異-不能な~objであり,`読取り演算$が起動された時点で~memory内に読取り可能な~file~dataを表現する。 ~UAは、読取り中に~fileが存在しなくなっていた場合には,`読取り~error$とし~MUST — すなわち:
- ( Web Worker `WORKERS$r の下で) `FileReaderSync$I が用いられている場合は `NotFoundError$E 例外を`投出$する。
- 他の場合は、[ `error$m 属性は `NotFoundError$E 例外を返す ]ようにした上で `error$et `~eventを発火する$
下の例では、~file~objからの~metadataが解る様に表示された上で,名前と最終更新日が伴われた `File$I ~objが作成される: ◎ In the examples below, metadata from a file object is displayed meaningfully, and a file object is created with a name and a last modified date.
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を表現する。 ◎ This interface is a list of File objects.
[`Exposed$=(Window,Worker), `Serializable$] interface `FileList@I { getter `File$I? item(unsigned long `index$V); readonly attribute unsigned long `length$m; };
`FileList$I ~objは、`直列化-可能$である: ◎ FileList objects are serializable objects.\
-
その`直列化~手続き$は、所与の ( %値, %直列形 ) に対し,次を走らす: ◎ Their serialization steps, given value and serialized, are:
- %直列形 . `Files^sl ~SET 空`~list$ ◎ Set serialized.[[Files]] to an empty list.
- %値 内の~EACH( %~file ) に対し ⇒ %直列形 . `Files^sl に %~file の`下位直列化$を`付加する$ ◎ For each file in value, append the sub-serialization of file to serialized.[[Files]].
-
その`逆直列化~手続き$は、所与の ( %値, %直列形 ) に対し,次を走らす: ◎ Their deserialization step, given serialized and value, are:
- %直列形 . `Files^sl 内の~EACH( %~file ) に対し ⇒ %~file の`下位逆直列化$を %値 に追加する ◎ For each file of serialized.[[Files]], add the sub-deserialization of file to value.
~sampleにおいては、概して,~form内の `<input type="file">^e 要素への DOM ~access, および選択された~fileへの~accessが含められる。 ◎ Sample usage typically involves DOM access to the <input type="file"> element within a form, and then accessing selected files.
/* `uploadData^c は `form$e 要素 / `fileChooser^c は `type='file'^c の `input$e 要素 ◎ 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 */ }
- `length@m
- 取得子は、次を返さ~MUST ⇒ 此れが含んでいる `File$I ~objの総数(なければ 0 になる) ◎ Attributes ◎ length, of type unsigned long, readonly ◎ must return the number of files in the FileList object. If there are no files, this attribute must return 0.
- `item(index)@m
- 被呼出時には、[ `index$V ~IN { 此れが`~supportする~prop~index$ } ならば 此れの中の %index 番の `File$I ~obj / ~ELSE_ ~NULL ]を返さ~MUST。 ◎ Methods and Parameters ◎ must return the indexth File object in the FileList. If there is no indexth File object in the FileList, then this method must return null.
- `index@V 引数は、 `FileList$I における `File$I ~objの位置を指し,値 0 が最初の~fileを指すとする。 `FileList$I ~obj %O が`~supportする~prop~index$は、 0 以上[ %O が含んでいる `File$I ~objの総数 ]未満とする。 ◎ index must be treated by user agents as value for the position of a File object in the FileList, with 0 representing the first file. Supported property indices are the numbers in the range zero to one less than the number of File objects represented by the FileList object. If there are no such File objects, then there are no supported property indices.
注記: `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の読取
6.1. 読取り演算
この節では、この仕様の~methodから呼出される`読取り演算$の~algoを定義する。 読取り演算には,次のものが渡され、~byte~streamとして読取られた`~byte列$を返すか,`失敗事由$を伴って失敗する:
- `~Blob$
- `同期~flag@ — 演算は、この値に応じて[ ~ON ならば同期的 / ~OFF (既定)ならば非同期的 ]に行われる。
`読取り演算@ を遂行するときは、所与の ( `~Blob$ %blob, `同期~flag$ %同期~flag ) に対し,次を走らす: ◎ To perform a read operation on a Blob and the synchronous flag, run the following steps:
- %本体 ~LET 新たな `本体$
- %本体 の`総~byte数$ ~SET %blob の `size$m
- ~IF[ %同期~flag ~EQ ~OFF ] ⇒ ~RET — ただし,この手続きは並列的に継続する
-
~WHILE[ %blob からすべての~byteを読取り尽くしていない ]:
- %~byte列 ~LET %blob から`~chunk$の読取を試みた結果の~byte列
-
~IF[ 前~段にて`読取り~error$が生じた ]:
- %本体 の~error~flag ~SET ~ON 【この~flagは `Fetch$r 仕様から削除された — `~streamを~errorにする$?】
- ~RET — `失敗事由$も伴わせて`終了-$する
- %本体 に %~byte列 を~pushする
- %本体 の`伝送-済み~byte数$に %~byte列 の~byte数を加算する
- ~IF[ %同期~flag ~EQ ~ON ] ⇒ ~RET %本体
-
Let s be a a new body, b be the Blob to be read from, and bytes initially set to an empty byte sequence. Set the length on s to the size of b. While there are still bytes to be read in b, perform the following substeps:
-
If the synchronous flag is set, follow the steps below:
-
Let bytes be the byte sequence that results from reading a chunk from b. If a file read error occurs reading a chunk from b, return s with the error flag set, along with a failure reason, and terminate this algorithm.
Note: Along with returning failure, the synchronous part of this algorithm must return the failure reason that occurred for throwing an exception by synchronous methods that invoke this algorithm with the synchronous flag set.
- If there are no errors, push bytes to s, and increment s’s transmitted [Fetch] by the number of bytes in bytes. Reset bytes to the empty byte sequence and continue reading chunks as above.
- When all the bytes of b have been read into s, return s and terminate this algorithm.
-
- Otherwise, the synchronous flag is unset. Return s and process the rest of this algorithm asynchronously.
-
Let bytes be the byte sequence that results from reading a chunk from b. If a file read error occurs reading a chunk from b, set the error flag on s, and terminate this algorithm with a failure reason.
Note: The asynchronous part of this algorithm must signal the failure reason that occurred for asynchronous error reporting by methods expecting s and which invoke this algorithm with the synchronous flag unset.
- If no file read error occurs, push bytes to s, and increment s’s transmitted [Fetch] by the number of bytes in bytes. Reset bytes to the empty byte sequence and continue reading chunks as above.
所与の`~Blob$ %blob に対し, `注釈付き~task読取り演算@ を遂行するときは、[ `同期~flag$ ~SET ~OFF ]の下で %blob に対する`読取り演算$ %演算 を遂行した上で,以下に従う: ◎ To perform an annotated task read operation on a Blob b, perform the steps below: ◎ Perform a read operation on b with the synchronous flag unset, along with the additional steps below.
- %演算 が`失敗事由$を伴って終了したときは ⇒ その`失敗事由$で `読取り~errorを処理する@ ための`~taskを~queueする$ ◎ If the read operation terminates with a failure reason, queue a task to process read error with the failure reason and terminate this algorithm.
-
%演算 の間に最初の`~chunk$が %body に~pushされるとき†は ⇒ `読取りを開始する@ ための`~taskを~queueする$。 ◎ When the first chunk is being pushed to the body s during the read operation, queue a task to process read.
【† “being pushed” — ~pushされる直前なのか?した直後なのか?。 原文の記述からは、`読取りを開始する$ための~task( `loadstart$et )抜きで`読取り~errorを処理する$ 可能性も排除できない。 】
-
次に該当する各~時点に `読取り~dataを処理する@ ための`~taskを~queueする$:
- (A) 最初に %演算 により %body に 1 個以上の`~chunk$が読取られたとき
- %blob から読取る`~chunk$が尽きたとき
- (A) の時点から[ `~chunk$が読取られるごと, または毎 50ms ごとの, 少ない方の頻度 ]の各時点
- %演算 により, %blob からすべての`~chunk$が %body に読取られたときは ⇒ `読取り完了@ 用の`~taskを~queueする$ ◎ When all of the chunks from b are read into the body s from the read operation, queue a task to process read EOF.
これらの~taskには,同じ`~file読取~task源$を利用すること。 ◎ Use the file reading task source for all these tasks.
6.2. ~file読取~task源
この仕様は、 `~file読取~task源@ と呼ばれる,新たな汎用`~task源$を定義する。 それは、この仕様にて、`~Blob$に結び付けられている~byte列を読取るために,`~queueされ$る~task ]すべてから利用される。 それはまた、~binary~dataの非同期的な読取に呼応して誘発される特色機能 【~eventなど】 用にも利用される。 ◎ This specification defines a new generic task source called the file reading task source, which is used for all tasks that are queued in this specification to read byte sequences associated with Blob and File objects. It is to be used for features that trigger in response to asynchronously reading binary data.
6.3. `FileReader^I ~API
[`FileReader$mC, `Exposed$=(Window,Worker)] interface `FileReader@I: `EventTarget$I { /* `非同期~読取り~method$ ◎ async read methods */ void `readAsArrayBuffer$m(`Blob$I `blob$V); void `readAsBinaryString$m(`Blob$I `blob$V); void `readAsText$m(`Blob$I `blob$V, optional `DOMString$I `label$V); void `readAsDataURL$m(`Blob$I `blob$V); void `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$I or `ArrayBuffer$I)? `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; };
6.3.1. 構築子
- `FileReader()@m
- この構築子の被呼出時には、新たな `FileReader$I ~objを返さ~MUST。 ◎ When the FileReader() constructor is invoked, the user agent must return a new FileReader object.
- この構築子は、大域~objが[ `Window$I / `WorkerGlobalScope$I ]~objで表現される環境においては,可用にされ~MUST。 ◎ In environments where the global object is represented by a Window or a WorkerGlobalScope object, the FileReader constructor must be available.
6.3.2. ~event~handler内容~属性
~UAは、 `FileReader$I の DOM 属性として,次の`~event~handler内容~属性$(およびそれらに対応する`~event~handler ~event型$ )を~supportし~MUST: ◎ The following are the event handler content attributes (and their corresponding event handler event types) that user agents must support on FileReader as DOM attributes:
`~event~handler内容~属性$ | `~event~handler ~event型$ |
---|---|
`onloadstart@m | `loadstart$et |
`onprogress@m | `progress$et |
`onabort@m | `abort$et |
`onerror@m | `error$et |
`onload@m | `load$et |
`onloadend@m | `loadend$et |
6.3.3. `FileReader^I の状態
`FileReader$I ~objは 3 種の状態をとり得る: ◎ The FileReader object can be in one of 3 states.\
- `readyState@m
-
取得子は、此れの現在の状態を次のいずれかの値として返さ~MUST: ◎ The readyState attribute, on getting, must return the current state, which must be one of the following values:
- `EMPTY@m (数値 0 )
- 此れは構築~済みであるが、まだ読取り待ちは生じていない。 `読取り~method$はまだ一度も~callされていない。 ◎ The FileReader object has been constructed, and there are no pending reads. None of the read methods have been called.\
- これが、いずれかの`読取り~method$が~callされるまでの,新たに創出された `FileReader$I ~objにおける既定の状態である。 ◎ This is the default state of a newly minted FileReader object, until one of the read methods have been called on it.
- `LOADING@m (数値 1 )
- `~Blob$は読取り中の状態にある。 `読取り~method$のいずれかが処理されていて,読取りにまだ~errorは生じていない。 ◎ A File or Blob is being read. One of the read methods is being processed, and no error has occurred during the read.
- `DONE@m (数値 2 )
- `~Blob$の全体が~memory内に読取られたか, または `読取り~error$が生じたか, または 読取りが `abort()$m により中止されている。 此れはそれ以降は`~Blob$の読取を行わない。 この状態にある場合、少なくともいずれかの`読取り~method$が,此れ上で~callされている。 ◎ The entire File or Blob has been read into memory, OR a file read error occurred, OR the read was aborted using abort(). The FileReader is no longer reading a File or Blob. If readyState is set to DONE it means at least one of the read methods have been called on this FileReader.
6.3.4. `File^I/`Blob^I の読取
`FileReader$I ~interfaceには、~fileを非同期的に~memory内に読取る数種の `非同期~読取り~method@ — `readAsArrayBuffer()$m, `readAsBinaryString()$m, `readAsText()$m, `readAsDataURL()$m — が可用にされている。 これらの読取り~methodが,同じ `FileReader$I ~objに対し同時並行的に重ねて~callされた場合、~UAは[ `readyState$m ~EQ `LOADING$m ]の間に生じたどの読取り~methodに対しても, `InvalidStateError$E を`投出$し~MUST。 ◎ The FileReader interface makes available several asynchronous read methods—readAsArrayBuffer(), readAsBinaryString(), 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 on any of the read methods that occur when readyState = LOADING.
`FileReaderSync$I も,類似する数種の`同期~読取り~method$を可用にする。 これらの同期/非同期の読取り~methodは、併せて, `読取り~method@ と総称される。 ◎ (FileReaderSync makes available several synchronous read methods. Collectively, the sync and async read methods of FileReader and FileReaderSync are referred to as just read methods.)
6.3.4.1. `result^m 属性
- `result@m
- 此れに対し~callされた`読取り~method$に応じて, および~errorが生じた場合はその~errorに応じて、[ `DOMString$I, `ArrayBuffer$I, ~NULL ]のいずれかになる。 ◎ ↓
-
取得子は、次の手続きの結果で与えられる`~Blob$の~dataを返さ~MUST: ◎ On getting, the result attribute returns a Blob's data as a DOMString, or as an ArrayBuffer, or null, depending on the read method that has been called on the FileReader, and any errors that may have occurred. ◎ The list below is normative for the result attribute and is the conformance criteria for this attribute:
- ~IF[ 此れの `readyState$m ~EQ `EMPTY$m (まだ此れ上に`読取り~method$は~callされていない) ] ⇒ ~RET ~NULL ◎ On getting, if the readyState is EMPTY (no read method has been called) then the result attribute must return null.
- ~IF[ `~Blob$の読取に~errorが生じていた ] ⇒ ~RET ~NULL (利用されている`読取り~method$にかかわらず) ◎ On getting, if an error in reading the File or Blob has occurred (using any read method) then the result attribute must return null.
-
~RET 此れ上で~callされた`読取り~method$に応じて,次で与えられる値: ◎ ↓
- `readAsDataURL()$m
- `~Blob$の~dataを`~data_URL$に符号化した結果の `DOMString$I ◎ On getting, if the readAsDataURL() read method is used, the result attribute must return a DOMString that is a Data URL [RFC2397] encoding of the File or Blob's data.
- `readAsBinaryString()$m
- 次の結果を表現する `DOMString$I ⇒ `同型に復号する$( `~Blob$の~data ) ◎ On getting, if the readAsBinaryString() read method is called and no error in reading the File or Blob has occurred, then the result attribute must return a DOMString representing the File or Blob's data as a binary string, in which every byte is represented by a code unit of equal value [0...255].
- `readAsText()$m
- `~Blob$の~dataを表現する~text文字列。 この文字列は`符号化法を決定-$した結果の形式の下で, `DOMString$I として~memory内に`復号-$されるべきである。 ◎ 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 as a DOMString.
- `readAsArrayBuffer()$m
- `~Blob$の~dataを表現する `ArrayBuffer$I ~obj。 ◎ 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 object.
6.3.4.2 〜 5. 各種 非同期~読取り~method
【 この訳では、各種 `非同期~読取り~method$の定義を,この節の中で一括して与える(原文では,~methodごとに個別に定義されているが、それらの大部分の記述は重複しているので)。 】
6.3.4.2. The readAsDataURL() method
When the readAsDataURL(blob) method is called, the user agent must run the steps below.
- If readyState = LOADING throw an InvalidStateError exception and terminate this algorithm.
- Otherwise set readyState to LOADING.
- Initiate an annotated task read operation using the blob argument as input and handle tasks queued on the file reading task source per below.
- To process read error with a failure reason, proceed to §6.3.4.6 Error Steps.
- To process read fire a progress event called loadstart at the context object.
- To process read data fire a progress event called progress at the context object.
-
To process read EOF run these substeps:
- Set readyState to DONE.
-
Set the result attribute to the body returned by the read operation as a DataURL [RFC2397]; on getting, the result attribute returns the blob as a Data URL [RFC2397].
- Use the blob’s type attribute as part of the Data URL if it is available in keeping with the Data URL specification [RFC2397].
- If the type attribute is not available on the blob return a Data URL without a media-type. [RFC2397]. Data URLs that do not have media-types [RFC2046] must be treated as plain text by conforming user agents. [RFC2397].
- Fire a progress event called load at the context object.
- Unless readyState is LOADING fire a progress event called loadend at the context object. If readyState is LOADING do NOT fire loadend at the context object.
- Terminate this algorithm.
6.3.4.3. The readAsText() method
The readAsText() method can be called with an optional parameter, label, which is a DOMString argument that represents the label of an encoding [Encoding]; if provided, it must be used as part of the encoding determination used when processing this method call.
When the readAsText(blob, label) method is called, the user agent must run the steps below.
- If readyState = LOADING throw an InvalidStateError and terminate this algorithm.
- Otherwise set readyState to LOADING.
- Initiate an annotated task read operation using the blob argument as input and handle tasks queued on the file reading task source per below.
- To process read error with a failure reason, proceed to the §6.3.4.6 Error Steps.
- To process read fire a progress event called loadstart at the context object.
- To process read data fire a progress event called progress at the context object.
-
To process read EOF run these substeps:
- Set readyState to DONE.
- Set the result attribute to the body returned by the read operation, represented as a string in a format determined by the encoding determination.
- Fire a progress event called load at the context object.
- Unless readyState is LOADING fire a progress event called loadend at the context object. If readyState is LOADING do NOT fire loadend at the context object.
- Terminate this algorithm.
6.3.4.4. The readAsArrayBuffer() method
When the readAsArrayBuffer(blob) method is called, the user agent must run the steps below.
- If readyState = LOADING throw an InvalidStateError exception and terminate this algorithm.
- Otherwise set readyState to LOADING.
-
Initiate an annotated task read operation using the blob argument as input and handle tasks queued on the file reading task source per below.
- To process read error with a failure reason, proceed to the §6.3.4.6 Error Steps.
- To process read fire a progress event called loadstart at the context object.
- To process read data fire a progress event called progress at the context object.
-
To process read EOF run these substeps:
- Set readyState to DONE.
- Set the result attribute to the body returned by the read operation as an ArrayBuffer object.
- Fire a progress event called load at the context object.
- Unless readyState is LOADING fire a progress event called loadend at the context object. If readyState is LOADING do NOT fire loadend at the context object.
- Terminate this algorithm.
6.3.4.5. The readAsBinaryString() method
When the readAsBinaryString(blob) method is called, the user agent must run the steps below.
- If readyState = LOADING throw an InvalidStateError exception and terminate this algorithm.
- Otherwise set readyState to LOADING.
-
Initiate an annotated task read operation using the blob argument as input and handle tasks queued on the file reading task source per below.
- To process read error with a failure reason, proceed to the §6.3.4.6 Error Steps.
- To process read fire a progress event called loadstart at the context object.
- To process read data fire a progress event called progress at the context object.
-
To process read EOF run these substeps:
- Set readyState to DONE
- Set the result attribute to the body returned by the read operation as a binary string.
- Fire a progress event called load at the context object.
- Unless readyState is LOADING fire a progress event called loadend at the context object. If readyState is LOADING do NOT fire loadend at the context object.
- Terminate this algorithm.
- `readAsDataURL(blob)@m
- `readAsText(blob, label)@m
- `readAsArrayBuffer(blob)@m
- `readAsBinaryString(blob)@m
-
これらの~methodの被呼出時には、次を走らせ~MUST:
- ~IF[ `readyState$m ~EQ `LOADING$m ] ⇒ ~THROW `InvalidStateError$E ◎ If readyState = LOADING throw an InvalidStateError exception and terminate this algorithm.
- `readyState$m ~SET `LOADING$m ◎ Otherwise set readyState to LOADING.
-
`blob$V 引数に対する`注釈付き~task読取り演算$を起動する — その演算により`~file読取~task源$から`~queueされ$た~taskは、以下に従って,取扱う: ◎ Initiate an annotated task read operation using the blob argument as input and handle tasks queued on the file reading task source per below.
- `読取り~errorを処理する$ときは ⇒ その`失敗事由$を与える下で,`~error手続き$を続行する ◎ To process read error with a failure reason, proceed to the §6.3.4.6 Error Steps.
- `読取りを開始する$ときは ⇒ `進捗~eventを発火する$( 此れ, `loadstart$et ) ◎ To process read fire a progress event called loadstart at the context object.
- `読取り~dataを処理する$ときは ⇒ `進捗~eventを発火する$( 此れ, `progress$et ) ◎ To process read data fire a progress event called progress at the context object.
-
`読取り完了$時には: ◎ To process read EOF run these substeps:
- `readyState$m ~SET `DONE$m ◎ Set readyState to DONE.
-
此れの `result$m 属性 ~SET ~methodの~~種類に応じて, `読取り演算$による結果の`本体$を以下に与える表現にした結果:
- `readAsDataURL()^m
-
次に従うような`~data_URL$による表現:
- `blob$V の `type$m 属性を`~data_URL$の~MIME型の部分に利用できる場合は、~data_URL仕様 `RFC2397$r に従って,それを利用する。
- 他の場合: `~data_URL$は~MIME型を伴わない。 ~UAは、~MIME型を伴わない`~data_URL$を,素の~text( `text/plain^l )として扱わ~MUST。
- `readAsText()^m
- [ `label$V 引数(省略可)から`符号化法を決定-$して得られる形式 ]の文字列による表現 ◎ Set the result attribute to the body returned by the read operation, represented as a string in a format determined by the encoding determination.
- `readAsArrayBuffer()^m
- `ArrayBuffer$I ~objによる表現 ◎ Set the result attribute to the body returned by the read operation as an ArrayBuffer object.
- `readAsBinaryString()^m
- ~binary文字列による表現 ◎ Set the result attribute to the body returned by the read operation as a binary string.
- `進捗~eventを発火する$( 此れ, `load$et ) ◎ Fire a progress event called load at the context object.
-
~IF[ `readyState$m ~NEQ `LOADING$m ] ⇒ `進捗~eventを発火する$( 此れ, `loadend$et ) ( `readyState$m ~EQ `LOADING$m のときは, `loadend$et を発火しないこと) ◎ Unless readyState is LOADING fire a progress event called loadend at the context object. If readyState is LOADING do NOT fire loadend at the context object.
【 この下位手続きの最初の段で `DONE$m にされているにもかかわらず, “`LOADING$m でない” の条件がある理由は、 `load$et の発火により呼出された~event~handlerにより, `readyState$m が変更され得るため(~event不変則節を参照)。 】
注記: `readAsBinaryString()$m よりも `readAsArrayBuffer()$m の利用が選好される — 前者は後方互換性のために供されている。 ◎ The use of readAsArrayBuffer() is preferred over readAsBinaryString(), which is provided for backwards compatibility.
6.3.4.6. ~error手続き
所与の `FileReader$I ~obj %reader に対し,`失敗事由$で`読取り~errorを処理する$手続きは、次で与えられる: ◎ These error steps are to process read error with a failure reason.
- %reader の `readyState$m 属性 ~SET `DONE$m ◎ ↓
- %reader の `result$m 属性 ~SET ~NULL ◎ Set the context object’s readyState to DONE and result to null if it is not already set to null.
- %reader の `error$m 属性 ~SET `失敗事由$に対応する `DOMException$I ~obj ◎ ↓
- `進捗~eventを発火する$( %reader, `error$et ) ◎ Set the error attribute on the context object; on getting, the error attribute must be a a DOMException object that corresponds to the failure reason. Fire a progress event called error at the context object.
- ~IF %reader の `readyState$m ~NEQ `LOADING$m ] ⇒ `進捗~eventを発火する$( %reader, `loadend$et ) ( ~EQ `LOADING$m のときには `loadend$et を発火しないこと) ◎ Unless readyState is LOADING, fire a progress event called loadend at the context object. If readyState is LOADING do NOT fire loadend at the context object.
- (この~algoを呼び出した)`読取り~method$は,`終了-$させる ◎ Terminate the algorithm for any read method.
6.3.4.7. `abort()^m ~method
- `abort()@m
-
被呼出時には、次を走らせ~MUST: ◎ When the abort() method is called, the user agent must run the steps below:
- ~IF[ `readyState$m ~IN { `EMPTY$m, `DONE$m } ] ⇒# `result$m ~SET ~NULL; ~RET ◎ If readyState = EMPTY or if readyState = DONE set result to null and terminate this algorithm.
- ~IF[ `readyState$m ~EQ `LOADING$m ] ⇒# `readyState$m ~SET `DONE$m; `result$m ~SET ~NULL ◎ If readyState = LOADING set readyState to DONE and result to null.
- 此れに提携して`~queueされ$ている すべての`~task$を、`~file読取~task源$から除去する ◎ If there are any tasks from the context object on the file reading task source in an affiliated task queue, then remove those tasks from that task queue.
- `読取り~method$が処理-中であれば、それを`終了-$させる ◎ Terminate the algorithm for the read method being processed.
- `進捗~eventを発火する$( 此れ, `abort$et ) ◎ Fire a progress event called abort.
- `進捗~eventを発火する$( 此れ, `loadend$et ) ◎ Fire a progress event called loadend.
6.3.4.8. `blob^V 引数
各種 `読取り~method$, および `URL.createObjectURL()$m は、`~Blob$を引数にとる。 この節ではこの引数を定義する。 ◎ The asynchronous read methods, the synchronous read methods, and URL.createObjectURL() take a Blob parameter. This section defines this parameter.
- `blob@V
-
これは`~Blob$であり、次のいずれかへの参照で~MUST:
- `FileList$I ~objの中の,ある `File$I ~obj
- 下層の~OS~file~systemから得られたものではない `Blob$I ~obj
6.4. 符号化法の決定-法
`readAsText()$m `読取り~method$を用いて`~Blob$を読取る際に、 `符号化法を決定-@ するときは、次の手続きに従わ~MUST: ◎ When reading Blob objects using the readAsText() read method, the following encoding determination steps must be followed:
- %符号化法 ~SET `失敗^i ◎ Let encoding be null.
- ~IF[ `label@V 引数は与えられている ] ⇒ %符号化法 ~SET `~labelから符号化法を取得する$( `label$V 引数 ) ◎ If the label argument is present when calling the method, set encoding to the result of the getting an encoding from label. ◎ If the getting an encoding steps above return failure, then set encoding to null.
-
~IF[ %符号化法 ~EQ `失敗^i ]~AND[ `blob$V 引数に `type$m 属性は在る ]~AND[ その属性は Charset Parameter `RFC2046$r を利用している ] ⇒ %符号化法 ~SET `~labelから符号化法を取得する$( Charset Parameter の中の`符号化法~label$を成す部分 )
`blob$V の `type$m 属性の値が `text/plain;charset=utf-8^samp ならば、結果の~labelは `utf-8^l になる。 ~UAは、 Charset Parameter を構文解析して,`符号化法~label$を成す部位を取り出さ~MUSTことに注意。
◎ If encoding is null, and the blob argument’s type attribute is present, and it uses a Charset Parameter [RFC2046], set encoding to the result of getting an encoding for the portion of the Charset Parameter that is a label of an encoding. ◎ If blob has a type attribute of text/plain;charset=utf-8 then getting an encoding is run using "utf-8" as the label. Note that user agents must parse and extract the portion of the Charset Parameter that constitutes a label of an encoding. ◎ If the getting an encoding steps above return failure, then set encoding to null. - ~IF[ %符号化法 ~EQ `失敗^i ] ⇒ %符号化法 ~SET `~UTF-8$ ◎ If encoding is null, then set encoding to utf-8.
- ~RET `~Unicodeに復号する$( %符号化法, `blob$V ) — [ `FileReader$I ~objの `result$m 属性の取得子 ], および[ `FileReaderSync$I ~objの同期的 `readAsText^m ~method ]においては、 %符号化法 形式による文字列を返すようにする。 ◎ Decode this blob using fallback encoding encoding, and return the result. On getting, the result attribute of the FileReader object returns a string in encoding format. The synchronous readAsText() method of the FileReaderSync object returns a string in encoding format.
6.5. ~event
この仕様に定義される すべての~eventは, `FileReader$I ~objをその~targetにし~MUST。 ◎ The FileReader object must be the event target for all events in this specification.
`進捗~eventを発火する@ ときは、所与の ( %~target, %~event名 ) に対し,次を走らせ~MUST ⇒ %~target に向けて,名前 %~event名 の`~eventを発火する$ — `ProgressEvent$I を利用して ( `DOM$r による定義により,~eventの `bubbles^m, `cancelable^m 両~属性とも ~F になる) ◎ When this specification says to fire a progress event called e (for some ProgressEvent e at a given FileReader reader as the context object), the following are normative: • The progress event e does not bubble. e.bubbles must be false [DOM] • The progress event e is NOT cancelable. e.cancelable must be false [DOM]
6.5.1. ~event要覧
次の表に、 `FileReader$I ~objに向けて`発火-$される~eventを挙げる — どれも, `ProgressEvent$I ~interfaceを利用する: ◎ The following are the events that are fired at FileReader objects.
~event名 | 発火-時機 |
---|---|
`loadstart@et | 読取りが開始されるとき。 ◎ When the read starts. |
`progress@et | `blob$V 読取り中(および復号-中)の間 ◎ While reading (and decoding) blob |
`abort@et | 読取りが中止されたとき。 例えば `abort()$m ~methodが呼出されたとき。 ◎ When the read has been aborted. For instance, by invoking the abort() method. |
`error@et | 読取りが失敗したとき(`読取り~error$を見よ)。 ◎ When the read has failed (see file read errors). |
`load@et | 読取りが成功裡に完了したとき。 ◎ When the read has successfully completed. |
`loadend@et | 要請が完了したとき(成功/失敗のいずれでも)。 ◎ When the request has completed (either in success or failure). |
6.5.2. ~event不変則の要約
~INFORMATIVEこの仕様で与えられる非同期`読取り~method$に対する~eventの発火には、次の不変則が成り立つ: ◎ The following are invariants applicable to event firing for a given asynchronous read method in this specification:
-
一度 `loadstart$et が発火された後、対応する `loadend$et が読取り完了~時に発火される。 ただし、次のいずれかに該当する場合を除く: ◎ Once a loadstart has been fired, a corresponding loadend fires at completion of the read, UNLESS any of the following are true:
- `abort()$m により`読取り~method$が取消され,新たに`読取り~method$が呼出された場合 ◎ the read method has been cancelled using abort() and a new read method has been invoked
- `load$et ~eventに対する~event~handler関数が,新たな読取りを起動させた場合 ◎ the event handler function for a load event initiates a new read
- `error$et ~eventに対する~event~handler関数が,新たな読取りを起動させた場合 ◎ the event handler function for a error event initiates a new read.
注記: 2 つの~event `loadstart$et と `loadend$et は、一対一の組にされるわけではない。 ◎ Note: The events loadstart and loadend are not coupled in a one-to-one manner.
“読取りの連鎖”,すなわち “最初の” 読取り処理は継続しつつ,~event~handlerの中で別の読取りを起動する例を示す: ◎ This example showcases "read-chaining": initiating another read from within an event handler while the "first" read continues processing.
/* 次の類いの~codeにおいて … ◎ In code of the sort... */ %reader.readAsText(%file); %reader.onload = function(){%reader.readAsText(%alternateFile);} ..... /* … 最初の読取りに対しては `loadend^et ~eventは発火されては~MUST_NOT ◎ ... the loadend event must not fire for the first read */ %reader.readAsText(%file); %reader.abort(); %reader.onabort = function(){%reader.readAsText(%updatedFile);} /* … 最初の読取りに対しては `loadend^et ~eventは発火されては~MUST_NOT ◎ ... the loadend event must not fire for the first read */
- `blob$V が~memory内に完全に読取られた時点で `progress$et ~eventが 1 回 発火されることになる。 ◎ One progress event will fire when blob has been completely read into memory.
- `loadstart$et より前に `progress$et ~eventが発火されることはない。 ◎ No progress event fires before loadstart.
- `abort$et, `load$et, `loadend$et の,どの発火-後にも `progress$et ~eventが発火されることはない。 与えられた読取りに対し,少なくとも `abort$et, `load$et, `error$et のいずれかが発火される。 ◎ No progress event fires after any one of abort, load, and error have fired. At most one of abort, load, and error fire for a given read.
- `loadend$et の後に `abort$et, `load$et, `error$et ~eventが発火されることはない。 ◎ No abort, load, or error event fires after loadend.
6.6. ~threadによる読取り
Web Workers `WORKERS$r においては `~Blob$に対する 同期的な読取り~APIも利用できる。 その種の読取り~threadが~main~threadを阻むことはない。 この節では、~workerにて利用できる同期的~APIを定義する。 ~workerには非同期~API( `FileReader$I ~obj) および 同期的~API( `FileReaderSync$I ~obj)が用意されている。 ◎ Web Workers allow for the use of synchronous File or Blob read APIs, since such reads on threads do not block the main thread. 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).
6.6.1. `FileReaderSync^I ~API
この~interfaceは `~Blob$を~memory内に同期的に読取るための `同期~読取り~method@ を供する。 ◎ This interface provides methods to synchronously read File or Blob objects into memory.
[`FileReaderSync$mC,
`Exposed$=(DedicatedWorker,SharedWorker)]
interface `FileReaderSync@I {
/*
同期的に文字列を返す
◎
Synchronously return strings
*/
`ArrayBuffer$I `readAsArrayBuffer$mS(`Blob$I `blob$V);
`DOMString$I `readAsBinaryString$mS(`Blob$I `blob$V);
`DOMString$I `readAsText$mS(`Blob$I `blob$V, optional `DOMString$I `label$V);
`DOMString$I `readAsDataURL$mS(`Blob$I `blob$V);
};
6.6.1.1. 構築子
- `FileReaderSync()@m
- この構築子の被呼出時には、新たな `FileReaderSync$I ~objを返さ~MUST。 ◎ When the FileReaderSync() constructor is invoked, the user agent must return a new FileReaderSync object.
- この構築子は、大域~objが `WorkerGlobalScope$I ~objで表現される環境においては,可用にされ~MUST。 ◎ In environments where the global object is represented by a WorkerGlobalScope object, the FileReaderSync constructor must be available.
6.6.1.2 〜 5. 各種 同期~読取り~method
【 この訳では、各種 `同期~読取り~method$の定義を,この節の中で一括して与える(原文では,~methodごとに個別に定義されているが、それらの大部分の記述は重複しているので)。 】
6.6.1.2. The readAsText() method
When the readAsText(blob, label) method is called, the following steps must be followed:
- Initiate a read operation using the blob argument, and with the synchronous flag set. If the read operation returns failure, throw the appropriate exception as defined in §7.1 Throwing an Exception or Returning an Error. Terminate this algorithm.
- If no error has occurred, return the result of the read operation represented as a string in a format determined through the encoding determination algorithm.
6.6.1.3. The readAsDataURL() method
When the readAsDataURL(blob) method is called, the following steps must be followed:
- Initiate a read operation using the blob argument, and with the synchronous flag set. If the read operation returns failure, throw the appropriate exception as defined in §7.1 Throwing an Exception or Returning an Error. Terminate this algorithm.
-
If no error has occurred, return the result of the read operation as a Data URL [RFC2397] subject to the considerations below:
- Use the blob’s type attribute as part of the Data URL if it is available in keeping with the Data URL specification [RFC2397].
- If the type attribute is not available on the blob return a Data URL without a media-type. [RFC2397]. Data URLs that do not have media-types [RFC2046] must be treated as plain text by conforming user agents. [RFC2397].
6.6.1.4. The readAsArrayBuffer() method
When the readAsArrayBuffer(blob) method is called, the following steps must be followed:
- Initiate a read operation using the blob argument, and with the synchronous flag set. If the read operation returns failure, throw the appropriate exception as defined in §7.1 Throwing an Exception or Returning an Error. Terminate this algorithm.
- ◎ If no error has occurred, return the result of the read operation as an ArrayBuffer.
6.6.1.5. The readAsBinaryString() method
When the readAsBinaryString(blob) method is called, the following steps must be followed:
- Initiate a read operation using the blob argument, and with the synchronous flag set. If the read operation returns failure, throw the appropriate exception as defined in §7.1 Throwing an Exception or Returning an Error. Terminate this algorithm.
- If no error has occurred, return the result of the read operation as an binary string.
- `readAsDataURL(blob)@mS
- `readAsText(blob, label)@mS
- `readAsArrayBuffer(blob)@mS
- `readAsBinaryString(blob)@mS
-
これらの~methodの被呼出時には、次を走らせ~MUST: ◎ When the readAsArrayBuffer(blob) method is called, the following steps must be followed:
- %本体 ~SET `blob$V を引数に[ `同期~flag$ ~SET ~ON ]の下で,`読取り演算$を行った結果 ◎ Otherwise, initiate a read operation using the blob argument, and with the synchronous flag set. If the read operation returns failure, throw the appropriate exception as defined in §7.1 Throwing an Exception or Returning an Error. Terminate this algorithm.
- ~IF[ 前~段の`読取り演算$が`失敗事由$を伴って終了した ] ⇒ ~THROW 失敗事由に適切な例外 ◎ ↑
-
~RET ~methodの~~種類に応じて, %本体 を次で与えられる表現にした結果:
- `readAsText()^m
- `label$V 引数(省略可)から`符号化法を決定-$して得られる形式による文字列
- `readAsDataURL()^m
-
下記に従うような`~data_URL$
- ~data_URL仕様 `RFC2397$r に従う形で, `blob$V の `type$m 属性を`~data_URL$の~MIME型の部分に利用できる場合は、そのようにする。
- 他の場合: `~data_URL$は~MIME型を伴わないとする。 ~UAは、~MIME型を伴わない`~data_URL$を,素の~text( `text/plain^l )として扱わ~MUST。
- `readAsArrayBuffer()^m
- `ArrayBuffer$I ~obj
- `readAsBinaryString()^m
- ~binary文字列
注記: `readAsBinaryString()$mS よりも `readAsArrayBuffer()$mS の利用が選好される — 前者は後方互換性のために供されている。 ◎ The use of readAsArrayBuffer() is preferred over readAsBinaryString(), which is provided for backwards compatibility.
7. ~errorと例外
`読取り~error@ は下層の~file~systemから~fileを読取る際に生じ得る。 起こり得る~errorのいくつかを下に挙げる。 これらは 参考 である。 ◎ File read errors can occur when reading files from the underlying filesystem. The list below of potential error conditions is informative.
- ~accessされている `~Blob$ 【の参照~先の~data】 は、`非同期~読取り~method$や`同期~読取り~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$は読取れない可能性もある。 これは、 `~Blob$への参照が獲得された後に~permissionの問題が生じたときに起こり得る(例えば他の~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内での利用を安全でないものと定めても~MAY。 ~disk上の~fileは 元々の~file選択から変化し得るので、読取り結果は無効なものになり得る。 加えて、一部の~fileや~directory構造は,下層の~file~systemにおいて制約されていることもある。 例えば それらからの読取りは,保安~違反と見なされ得る。 保安~上の考慮点, `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.
7.1. 例外の投出/返される~error
この節は規定とする。 ◎ This section is normative.
`~error条態$は`~Blob$の読取り中に生じ得る。 ◎ Error conditions can arise when reading a File or a Blob.
`読取り演算$は、`~Blob$の読取~中における`~error条態$により終了し得る。 `読取り演算$を失敗させる, あるいは `読取り~errorを処理する$ための`~taskを~queueする$ような,個々の`~error条態$は、 `失敗事由@ と呼ばれる。 ◎ The read operation can terminate due to error conditions when reading a File or a Blob; the particular error condition that causes a read operation to return failure or queue a task to process read error is called a failure reason.
- `同期~読取り~method$に対しては、ある`失敗事由$により~errorが生じた場合、下の一覧に挙げる型の例外が`投出$される。 ◎ Synchronous read methods throw exceptions of the type in the table below if there has been an error owing to a particular failure reason.
- `非同期~読取り~method$に対しては、 `FileReader$I ~objの `error@m 属性が利用される。 それは、[ ある`失敗事由$により~errorが生じた場合は,下の一覧の中で最も適切な名前の `DOMException$I ~obj / ~ELSE_ ~NULL ]を返さ~MUST。 ◎ Asynchronous read methods use the error attribute of the FileReader object, which must return a DOMException object of the most appropriate type from the table below if there has been an error owing to a particular failure reason, or otherwise return null.
~error名 ◎ Type | `失敗事由$とその説明 ◎ Description and Failure Reason |
---|---|
`NotFoundError$E |
次に該当する`失敗事由$に対しては、この型の例外が利用され~MUST:
|
`SecurityError$E |
次に該当する`失敗事由$に対しては、この型の例外が利用されて~MAY:
これは、他の `失敗事由$に該当しない状況に利用される保安~上の~errorである。 ◎ If: it is determined that certain files are unsafe for access within a Web application, this is the UnsafeFile failure reason. ◎ it is determined that too many read calls are being made on File or Blob resources, this is the TooManyReads failure reason. ◎ For asynchronous read methods the error attribute may return a SecurityError exception and synchronous read methods may throw a SecurityError exception. ◎ This is a security error to be used in situations not covered by any other failure reason. |
`NotReadableError$E |
次に該当する`失敗事由$に対しては、この型の例外が利用され~MUST:
|
8. `Blob^I / `File^I への~URL参照
この節では`~Blob$を指すために利用される`~URL$の`~scheme$urlを定義する。 ◎ This section defines a scheme for a URL used to refer to Blob objects (and File objects).
注記: `MEDIA-SOURCE$r などの他の仕様は、他の型の~objも指すために,この~schemeを拡張する。 ◎ Note: other specifications, such as [MEDIA-SOURCE] extend this scheme to also refer to other types of objects.
8.1. 序論
~INFORMATIVE`~blob~URL$は、 `blob:http://example.com/550e8400-e29b-41d4-a716-446655440000^c の様な~URLである。 これは、`img$e 要素などの,[ ~~普通の~URLを利用するように設計された他の~Web~platform~API ]に`~Blob$を統合することを可能化する。 `~blob~URL$は、~navigateするときや, ~localに生成された~dataの~downloadを誘発するときにも利用できる。 ◎ Blob (or object) URLs are URLs like blob:http://example.com/550e8400-e29b-41d4-a716-446655440000. This enables integration of Blobs and Files with other Web Platform APIs that are only designed to be used with URLs, such as the img element. Blob URLs can also be used to navigate to as well as to trigger downloads of locally generated data.
この目的で `URL$I ~interfaceには 2 つの静的~method — `createObjectURL(blob)$m, `revokeObjectURL(url)$m — が公開される。 前者は `~URL$から `Blob$I への対応付けを作成し,後者は その対応付けを破棄する。 対応付けが存在する限り, `Blob$I は~garbage収集できないので、参照が不要になり次第 ~URLを破棄するよう,【作者は】注意しておく必要がある。 どの`~blob~URL$も、それを作成した大域~objが消去るに伴い,破棄される。 ◎ For this purpose two static methods are exposed on the URL interface, createObjectURL(blob) and revokeObjectURL(url). The first method creates a mapping from a URL to a Blob, and the second method revokes said mapping. As long as the mapping exist the Blob can’t be garbage collected, so some care must be taken to revoke the URL as soon as the reference is no longer needed. All URLs are revoked when the global that created the URL itself goes away.
8.2. ~model
各~UAは、 `~blob~URL~store@ を保守し~MUST — それは`~map$であり、それを成す各~entryは:
-
`~blob~URL@ を`~key$mapとする。 それは、`妥当な~URL文字列$であって,それを`~URL構文解析-$した結果の`~URL$は次をすべて満たすものである:
- `~scheme$url ~EQ `blob^l
- `~host$urlは空である
- `~path$urlは[ 自身も`妥当な~URL文字列$である 1 個の要素 ]のみからなる
-
`~blob~URL~entry@ を`値$mapとする。 それは、次のものからなる組である:
- `~obj@bU
- 概して `Blob$I であるが、他の仕様は,これを他の型の~objを指すよう拡張できる。
- `環境@bU
- `環境~設定群~obj$。
`新たな~blob~URLを生成する@ ときは、次を走らす: ◎ To generate a new blob URL, run the following steps:
- %直列形 ~LET `生成元を直列化する$( `現在の設定群~obj$の`生成元$enV ) ◎ Let result be the empty string. ◎ Append the string "blob:" to result. ◎ Let settings be the current settings object ◎ Let origin be settings’s origin. ◎ Let serialized be the ASCII serialization of origin.
- ~IF[ %直列形 ~EQ `null^l ] ⇒ %直列形 ~SET 実装により定義される値 ◎ If serialized is "null", set it to an implementation-defined value.
- ~RET 次を順に連結した結果 ⇒# 文字列 `blob:^l, %直列形, `0024^U SOLIDUS ( `/^c ), ~UUID `RFC4122$r を文字列として生成した結果 ◎ Append serialized to result. ◎ Append U+0024 SOLIDUS (/) to result. ◎ Generate a UUID [RFC4122] as a string and append it to result. ◎ Return result.
この~algoにより生成できる~blob~URLの例 ⇒ `blob:https://example.org/9115d58c-bcda-ff47-86e5-083e9a2153041^c ◎ An example of a blob URL that can be generated by this algorithm is blob:https://example.org/9115d58c-bcda-ff47-86e5-083e9a2153041.
`~blob~URL~storeに~entryを追加する@ ときは、所与の ( %~obj ) に対し,次を走らす: ◎ To add an entry to the blob URL store for a given object, run the following steps:
- %~url ~LET `新たな~blob~URLを生成する$ ◎ Let store be the user agent’s blob URL store. ◎ Let url be the result of generating a new blob URL.
- ~UAの`~blob~URL~store$[ %~url ] ~SET 次のようにされた,新たな`~blob~URL~entry$ ⇒# `~obj$bU ~SET %~obj, `環境$bU ~SET `現在の設定群~obj$ ◎ Let entry be a new blob URL entry consisting of object and the current settings object. ◎ Set store[url] to entry.
- ~RET %~url ◎ Return url.
`~blob~URL~storeから~entryを除去する@ ときは、所与の ( %~url ) に対し,次を走らす: ◎ To remove an entry from the blob URL store for a given url, run the following steps:
- %~url文字列 ~LET `~URLを直列化する$( %~url ) ◎ Let store be the user agent’s blob URL store; ◎ Let url string be the result of serializing url.
- ~UAの`~blob~URL~store$[ %~url文字列 ] ~SET ε ◎ Remove store[url string].
8.2.1. ~blob~URL用の参照解決~model
【 参照解決( dereference ) — 参照を参照-先の~dataに解決する。 】
`~blob~URLを解決する@ ときは、所与の ( `~URL$ %~url ) に対し,次を走らす: ◎ To resolve a blob URL given a url (a URL), run the following steps:
- ~Assert: %~url の`~scheme$url ~EQ `blob^l ◎ Assert: url’s scheme is "blob".
- %~url文字列 ~LET `~URLを直列化する$( %~url, `素片は除外する^i ) ◎ Let store be the user agent’s blob URL store. ◎ Let url string be the result of serializing url with the exclude fragment flag set.
- ~RET [ 次の結果 ~NEQ ε ならば それ / ~ELSE_ `失敗^i ] ⇒ ~UAの`~blob~URL~store$[ %~url文字列 ] ◎ If store[url string] exists, return store[url string]; otherwise return failure.
`~blob~URL$用の[ 構文解析する/~fetchする ]~modelに対する更なる要件は、 `URL$r, `Fetch$r 仕様に定義される。 ◎ Futher requirements for the parsing an fetching model for blob URLs are defined in the [URL] and [Fetch] specifications.
8.2.2. ~blob~URLの生成元
`~blob~URLの生成元を解決する@ ときは、所与の ( `~URL$ %~url ) に対し,次を走らす: ◎ To resolve the origin of a blob URL given a url (a URL), run the following steps:
- ~Assert: %~url の`~scheme$url ~EQ `blob^l ◎ Assert: url’s scheme is "blob".
- %~entry ~LET `~blob~URLを解決する$( %~url ) ◎ Let entry be the result of resolving url.
- ~IF[ %~entry ~NEQ `失敗^i ] ⇒ ~RET %~entry の`環境$bUの`生成元$enV ◎ If entry is not failure, return entry’s environment's origin.
- %入子の~url ~LET `~URL構文解析する$( %~url の`~path$url[0] ) ◎ Let nested url be the result of parsing url’s path[0].
- ~IF[ %入子の~url ~NEQ `失敗^i ] ⇒ ~RET 新たな`不透明な生成元$ ◎ Return a new opaque origin, if nested url is failure,\
- ~RET %入子の~url の`生成元$url ◎ and nested url’s origin otherwise.
注記: この~algoの効果により,~blob~URLは、破棄されるまでは,その生成元と~URLを作成した環境のそれとは常に同じになる。 ~URLが破棄された場合、生成元の直列化は,~blob~URLを作成した環境の生成元の直列化と依然として同じであり続けるが、不透明な生成元に対しては生成元~自身と別個になるかもしれない。 ~blob~URLは,破棄されて以降はどうやっても解決-/~fetchできなくなるので、この相違は、観測-可能にならないが。 ◎ Note: The effect of this algorithm is that the origin of a blob URL is always the same as that of the environment that created the URL, as long as the URL hasn’t been revoked yet. If the URL was revoked the serialization of the origin will still remain the same as the serialization of the origin of the environment that created the blob URL, but for opaque origins the origin itself might be distinct. This difference isn’t observable though, since a revoked blob URL can’t be resolved/fetched anymore anyway.
`URL$r 仕様は、~URLが最初に構文解析されるとき,~blob~URLの生成元を解決する際に,この~algoを指すよう更新されるべきである。 これは、 issue #63, whatwg/url#127 にて追跡されている。 ◎ The [URL] spec should be updated to refer to this algorithm to resolve the origin of a blob URL when the URL is first parsed. This is tracked in issue #63 and in whatwg/url#127.
8.2.3. ~blob~URLの存続期間
この仕様は、`文書~unload時の片付け手続き$を,所与の ( `文書$ %文書 ) に対し 次を走らすように拡張する: ◎ This specification extends the unloading document cleanup steps with the following steps:
- ~UAの`~blob~URL~store$から,次を満たす~entryをすべて除去する ⇒ `値$mapの`環境$bU ~EQ %文書 に`関連する設定群~obj$ ◎ Let environment be the Document's relevant settings object. ◎ Let store be the user agent’s blob URL store; ◎ Remove from store any entries for which the value's environment is equal to environment.
~workerの~unload時にも,似たような~hookを与える必要がある。 ◎ This needs a similar hook when a worker is unloaded.
8.3. ~blob~URLの作成-法と破棄-法
`~blob~URL$は, `URL$I ~objに公開される静的~methodを用いて作成され, 破棄される。 `~blob~URL$を破棄する( revoke する)ことにより、それが参照する資源と`~blob~URL$は切り離される。 破棄-後に参照解決が~~試みられた場合、~UAは`~network~error$が生じたかのように動作し~MUST。 この節では、 URL 仕様 `URL$r に対する追加の~interface, および `~blob~URL$の作成/破棄~用の~methodについて述べる。 ◎ Blob URLs are created and revoked using static methods exposed on the URL object. Revocation of a blob URL decouples the blob URL from the resource it refers to, and if it is dereferenced after it is revoked, user agents must act as if a network error has occurred. This section describes a supplemental interface to the URL specification [URL] and presents methods for blob URL creation and revocation.
[`Exposed$=(Window,DedicatedWorker,SharedWorker)] partial interface `URL$I { static `DOMString$I `createObjectURL$m(`Blob$I `blob$V); static void `revokeObjectURL$m(`DOMString$I %url); };
- `createObjectURL(blob)@m
- この静的~methodは、次の結果を返さ~MUST ⇒ `~blob~URL~storeに~entryを追加する$( %blob ) ◎ The createObjectURL(blob) static method must return the result of adding an entry to the blob URL store for blob.
- `revokeObjectURL(url)@m
-
この静的~methodの被呼出時には、次を走らせ~MUST: ◎ The revokeObjectURL(url) static method must run these steps:
- %~url~record ~LET `~URL構文解析する$( %~url ) ◎ Let url record be the result of parsing url.
- ~IF[ %~url~record の`~scheme$url ~NEQ `blob^ ] ⇒ ~RET ◎ If url record’s scheme is not "blob", return.
- %生成元 ~LET `~blob~URLの生成元を解決する$( %~url~record ) ◎ Let origin be the result of resolving the origin of url record.
- %設定群 ~LET `現在の設定群~obj$ ◎ Let settings be the current settings object.
- ~IF[ ( %生成元, %設定群 の`生成元$enV ) は`同一生成元$でない ] ⇒ ~RET ◎ If origin is not same origin with settings’s origin, return.
- `~blob~URL~storeから~entryを除去する$( %~url ) ◎ Remove an entry from the Blob URL Store for url.
- 注記: これは,登録されていない~URLを破棄しようと試みたときには、~errorを投出することなく,黙って失敗することを意味する。 これが起きたときには、~UAは,~error~consoleに~messageを表示することもできる。 ◎ Note: This means that rather than throwing some kind of error, attempting to revoke a URL that isn’t registered will silently fail. User agents might display a message on the error console is this happens.
- 注記: 破棄された %~url を参照解決しようと試みた場合、`~network~error$になる。 %~url が破棄される前に開始された要請は、依然として成功するべきである。 ◎ Note: Attempts to dereference url after it has been revoked will result in a network error. Requests that were started before the url was revoked should still succeed.
次の例の %window1, %window2 は、別々であるが`同一生成元$であるとする — %window2 は、 %window1 の内側にある `iframe$e にもなり得る。 ◎ In the example below, window1 and window2 are separate, but in the same origin; window2 could be an iframe inside window1.
%myurl = %window1.URL.createObjectURL(%myblob); %window2.URL.revokeObjectURL(%myurl);
~UAが有する大域`~blob~URL~store$は一つだけなので、ある~obj~URLを それを作成しなかった異なる~windowから破棄することも可能になる。 `URL.revokeObjectURL()$m を~callすれば、[[ それ以降に %myurl を参照解決した結果は,`~network~error$になる ]かのように,~UAが動作する ]ようになることが確保される。 ◎ Since a user agent has one global blob URL store, it is possible to revoke an object URL from a different window than from which it was created. The URL.revokeObjectURL() call ensures that subsequent dereferencing of myurl results in a the user agent acting as if a network error has occurred.
8.3.1. ~blob~URLの作成と破棄の用例
`~blob~URL$は`~Blob$を`~fetch$するために利用される文字列であり,それを `URL.createObjectURL()$m を用いて創出した元の`文書$に残り続け得る( ~blob~URLの存続期間 を見よ)。 ◎ Blob URLs are strings that are used to fetch Blob objects, and can persist for as long as the document from which they were minted using URL.createObjectURL()—see §8.2.3 Lifetime of blob URLs.
この節では、説明を交えながら`~blob~URL$の作成と破棄の用例を示す。 ◎ This section gives sample usage of creation and revocation of blob URLs with explanations.
次の例では、 2 個の `img$e 要素 `HTML$r が,同じ`~blob~URL$を参照する: ◎ In the example below, two img elements [HTML] refer to the same blob URL:
%url = URL.createObjectURL(%blob); %img1.src = %url; %img2.src = %url;
次の例では、 `URL.revokeObjectURL()$m が明示的に~callされる: ◎ In the example below, URL.revokeObjectURL() is explicitly called.
var %blobURLref = URL.createObjectURL(%file); %img1 = new Image(); %img2 = new Image(); /* いずれの代入も予期される通りに機能する ◎ Both assignments below work as expected */ %img1.src = %blobURLref; %img2.src = %blobURLref; /* … body の読込みに後続して、画像が 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); }
上の例では、 1 個の`~blob~URL$に対する複数回の参照が可能になる。 `~blob~URL$文字列は,画像~objがいずれも読込まれた後に破棄されている。 `~blob~URL$の利用回数が制約されない分,柔軟性は得られるが、漏洩の可能性も高まる。 開発者は、 `URL.revokeObjectURL()$m の~callと対にするべきである。 ◎ The example above allows multiple references to a single blob URL, and the web developer then revokes the blob URL string after both image objects have been loaded. While not restricting number of uses of the blob URL offers more flexibility, it increases the likelihood of leaks; developers should pair it with a corresponding call to URL.revokeObjectURL().
9. 保安と~privacy上の考慮点
~INFORMATIVEこの仕様では、~Web内容が 下層の~file~systemから~fileを読取ることを許容し,~fileが一意な識別子を通して~accessされることの意味を与えるが、その種のものは保安~上の考慮点になる。 この仕様は、利用者との対話が主に~HTML~formの `<input type="file"/>^e 要素 `HTML$r によるものであり、 `FileReader$I ~objから読取られるすべての~fileは,最初に利用者の手により選択されたものであると見做している。 重要な保安~上の考慮点には、悪意的な~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@の防止: ~file選択の間、利用者は `<input type="file"/>^e に結びつけられた~file選択dialogにより攻撃され得る(選択しない限り,~file選択dialogが際限なく現れる “選択強制” )。 ~UAは、返される `FileList$I ~objの~sizeを 0 にすることにより,~file~accessを防止してもよい。 ◎ 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に関わる~file@: ( system-sensitive files — 例えば /usr/bin の~file, password ~file, 他の~OS~nativeの実行-可能~file)は、概して,~Web内容に曝露されるべきではなく,`~blob~URL$を通して~accessされるべきではない。 ~UAは、`同期~読取り~method$に対し `SecurityError$E 例外を`投出$してもよく, また `非同期~読取り~method$においては `SecurityError$E 例外を返してもよい。 ◎ System-sensitive files (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.
課題: この節は暫定的なものである。 後続の草案には、より多くの保安~上の考慮点が追加される事になる。 ◎ 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内で並び換えたり, 操作可能な一覧として利用者に示される。 利用者は曲を選択してその歌詞を閲覧できる。 利用者は “~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と会社の “多忙” 期間の印が付けられた予定表との~~同期を(個人情報が漏れないように)とりたいとする。 利用者は一覧から~fileを探して選択する。 text/calendar ~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は供さないが、それは HTML5 仕様にて取組まれている。 `a$e 要素の `download$a 属性 `HTML$r は、~downloadを起動させ, `File$I を指定された名前で保存する。 この~APIと `a^e 要素の `download^a 属性との組み合せにより、~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を通して何らかの入力を生成する。 しかる後、~formから,~spreadsheetに組み入れられる CSV ( Comma Separated Variables )出力が生成され,“保存…" が行われる。 生成された出力を直接的に~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から~remote~serverへ~dataを送信するための、効率的な~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との対話に入ったときは,いつでも~transactionの取消/中止-を常に行えるような形で,~UIから通知を受ける。 利用者は、いかなる~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, Anne van Kesteren 両氏からの~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, Jonas Sicking 両氏に。 ◎ Thanks to Robin Berjon and Jonas Sicking 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