index.html
85.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN' 'http://www.w3.org/TR/html4/loose.dtd'>
<html lang="en" dir="ltr">
<head>
<title>File API: Writer</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<link href="respec.css" rel="stylesheet" type="text/css" charset="utf-8"><link href="http://www.w3.org/StyleSheets/TR/W3C-WD" rel="stylesheet" type="text/css" charset="utf-8"></head>
<body style="display: inherit; "><div class="head"><p><a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a></p><h1 class="title" id="title">File API: Writer</h1><h2 id="w3c-working-draft-19-april-2011">W3C Working Draft 19 April 2011</h2><dl><dt>This version:</dt><dd><a href="http://www.w3.org/TR/2011/WD-file-writer-api-20110419/">http://www.w3.org/TR/2011/WD-file-writer-api-20110419/</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/file-writer-api/">http://www.w3.org/TR/file-writer-api/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2009/dap/file-system/file-writer.html">http://dev.w3.org/2009/dap/file-system/file-writer.html</a></dd>
<dt>Previous versions:</dt>
<dd><a href="http://www.w3.org/TR/2010/WD-file-writer-api-20101026/">http://www.w3.org/TR/2010/WD-file-writer-api-20101026/</a></dd>
<dd><a href="http://www.w3.org/TR/2010/WD-file-writer-api-20100406/">http://www.w3.org/TR/2010/WD-file-writer-api-20100406/</a></dd>
<dt>Editor:</dt><dd><a href="http://www.ofb.net/~uranium/">Eric Uhrhane</a>, <a href="http://www.google.com/">Google</a></dd>
</dl><p class="copyright"><a
href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
© 2011 <a href="http://www.w3.org/"><acronym title="World Wide Web
Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p><hr></div>
<div id="abstract" class="introductory section"><h2>Abstract</h2>
<p>
This specification defines an <acronym title="Application Programming
Interface">API</acronym> for writing to files from web applications.
This API is designed to be used in conjunction with, and depends on
definitions in, other APIs and elements on the web platform. Most
relevant among these are [<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>] and [<cite><a class="bibref" rel="biblioentry" href="#bib-WEBWORKERS">WEBWORKERS</a></cite>].
</p>
<p>
This API includes:
</p><ul>
<li> A <a href="#idl-def-BlobBuilder" class="idlType"><code>BlobBuilder</code></a> interface, which enables one to build a
<code>Blob</code> from a String.
</li><li> A <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> interface, which provides methods to write a
<code>Blob</code> to a file, and an event model to monitor the
progress of those writes.</li>
<li> A <a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a> interface, which expands on FileSaver to add
a richer set of output options.</li>
<li> A <a href="#idl-def-FileWriterSync" class="idlType"><code>FileWriterSync</code></a> interface, which provides methods to
write and modify files synchronously in a Web Worker.</li>
</ul>
<p></p>
</div><div id="sotd" class="introductory section"><h2>Status of This Document</h2><p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/.</em></p>
<p>This document represents the early consensus of the group on
the scope and features of the proposed File API: Writer. Issues and
editors notes in the document highlight some of
the points on which the group is still working and would
particularly like to get feedback.</p>
<p>This document was published by the <a href="http://www.w3.org/2008/webapps/">WebApps Working Group</a> as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to <a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a href="mailto:public-webapps-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>). All feedback is welcome.</p><p>Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>.</p></div><div id="toc" class="section"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#conformance" class="tocxref"><span class="secno">1. </span>Conformance</a></li><li class="tocline"><a href="#terminology-and-algorithms" class="tocxref"><span class="secno">2. </span>Terminology and Algorithms</a></li><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">3. </span>Introduction</a><ul class="toc"><li class="tocline"><a href="#examples" class="tocxref"><span class="secno">3.1 </span>Examples</a></li></ul></li><li class="tocline"><a href="#the-blobbuilder-interface" class="tocxref"><span class="secno">4. </span>The <code>BlobBuilder</code> interface</a><ul class="toc"><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">4.1 </span>Methods</a></li><li class="tocline"><a href="#constructor" class="tocxref"><span class="secno">4.2 </span>Constructor</a></li></ul></li><li class="tocline"><a href="#the-filesaver-interface" class="tocxref"><span class="secno">5. </span>The <span class="idlType formerLink idlType"><code>FileSaver</code></span> interface</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">5.1 </span>Attributes</a></li><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">5.2 </span>Methods</a></li><li class="tocline"><a href="#constants" class="tocxref"><span class="secno">5.3 </span>Constants</a></li><li class="tocline"><a href="#the-filesaver-constructor" class="tocxref"><span class="secno">5.4 </span>The FileSaver Constructor</a></li><li class="tocline"><a href="#the-filesaver-task-source" class="tocxref"><span class="secno">5.5 </span>The FileSaver Task Source</a></li><li class="tocline"><a href="#event-handler-attributes" class="tocxref"><span class="secno">5.6 </span>Event Handler Attributes</a></li></ul></li><li class="tocline"><a href="#the-filesaversync-interface" class="tocxref"><span class="secno">6. </span>The <code>FileSaverSync</code> interface</a></li><li class="tocline"><a href="#the-filewriter-interface" class="tocxref"><span class="secno">7. </span>The <span class="idlType formerLink idlType"><code>FileWriter</code></span> interface</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">7.1 </span>Attributes</a></li><li class="tocline"><a href="#methods-2" class="tocxref"><span class="secno">7.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#the-filewritersync-interface" class="tocxref"><span class="secno">8. </span>The <code>FileWriterSync</code> interface</a><ul class="toc"><li class="tocline"><a href="#attributes-2" class="tocxref"><span class="secno">8.1 </span>Attributes</a></li><li class="tocline"><a href="#methods-3" class="tocxref"><span class="secno">8.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#errors-and-exceptions" class="tocxref"><span class="secno">9. </span>Errors and Exceptions</a><ul class="toc"><li class="tocline"><a href="#the-fileerror-interface" class="tocxref"><span class="secno">9.1 </span>The FileError Interface</a><ul class="toc"><li class="tocline"><a href="#attributes-3" class="tocxref"><span class="secno">9.1.1 </span>Attributes</a></li><li class="tocline"><a href="#constants-1" class="tocxref"><span class="secno">9.1.2 </span>Constants</a></li></ul></li><li class="tocline"><a href="#the-fileexception-exception" class="tocxref"><span class="secno">9.2 </span>The FileException exception</a><ul class="toc"><li class="tocline"><a href="#fields" class="tocxref"><span class="secno">9.2.1 </span>Fields</a></li><li class="tocline"><a href="#constants-2" class="tocxref"><span class="secno">9.2.2 </span>Constants</a></li></ul></li><li class="tocline"><a href="#error-code-descriptions" class="tocxref"><span class="secno">9.3 </span><span>Error Code Descriptions</span></a></li></ul></li><li class="tocline"><a href="#security-considerations" class="tocxref"><span class="secno">10. </span>Security Considerations</a><ul class="toc"><li class="tocline"><a href="#basic-security-model" class="tocxref"><span class="secno">10.1 </span>Basic Security Model</a></li><li class="tocline"><a href="#write-only-files" class="tocxref"><span class="secno">10.2 </span>Write-Only Files</a></li><li class="tocline"><a href="#quotas" class="tocxref"><span class="secno">10.3 </span>Quotas</a></li><li class="tocline"><a href="#other-standard-techniques" class="tocxref"><span class="secno">10.4 </span>Other Standard Techniques</a></li></ul></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">B.1 </span>Normative references</a></li><li class="tocline"><a href="#informative-references" class="tocxref"><span class="secno">B.2 </span>Informative references</a></li></ul></li></ul></div>
<div id="conformance" class="section"><!--OddPage--><h2><span class="secno">1. </span>Conformance</h2><p>As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.</p>
<p>The key words <em class="rfc2119" title="must">must</em>, <em class="rfc2119" title="must not">must not</em>, <em class="rfc2119" title="required">required</em>, <em class="rfc2119" title="should">should</em>, <em class="rfc2119" title="should not">should not</em>, <em class="rfc2119" title="recommended">recommended</em>, <em class="rfc2119" title="may">may</em>, and <em class="rfc2119" title="optional">optional</em> in this specification are to be interpreted as described in [<cite><a class="bibref" rel="biblioentry" href="#bib-RFC2119">RFC2119</a></cite>].</p>
<p>
This specification defines conformance criteria that apply to a single
product: <a href="#dfn-user-agents" class="internalDFN">user agents</a> that implement the interfaces that it
contains.
</p>
<p>
Everything in this specification is normative except for examples and
sections marked as being informative.
</p>
<p>
The keywords <em class="rfc2119" title="must">must</em>, <em class="rfc2119" title="must not">must not</em>, <em class="rfc2119" title="required">required</em>, <em class="rfc2119" title="shall">shall</em>, <em class="rfc2119" title="shall not">shall not</em>, <em class="rfc2119" title="should">should</em>, <em class="rfc2119" title="should
not">should
not</em>, <em class="rfc2119" title="recommended">recommended</em>, <em class="rfc2119" title="may">may</em>, and <em class="rfc2119" title="optional">optional</em> in this document are to be
interpreted as described in <a href="http://www.ietf.org/rfc/rfc2119">Key words for use in RFCs to
Indicate Requirement Levels</a> [<cite><a class="bibref" rel="biblioentry" href="#bib-RFC2119">RFC2119</a></cite>].
</p>
<p>
The following conformance classes are defined by this specification:
</p><dl>
<dt><dfn id="dfn-conforming-implementation">conforming implementation</dfn></dt>
<dd>
<p>
A <dfn id="dfn-user-agent">user agent</dfn> is considered to be a conforming
implementation if it satisfies all of the must-, required- and
shall-level criteria in this specification that apply to
implementations.
</p>
</dd>
</dl>
<p></p>
</div>
<div id="terminology-and-algorithms" class="section">
<!--OddPage--><h2><span class="secno">2. </span>Terminology and Algorithms</h2>
<p>
The terms and algorithms <dfn id="dfn-event-handler-attributes">event handler attributes</dfn>, <dfn id="dfn-event-handler-event-types">event
handler event types</dfn>, <dfn id="dfn-function">Function</dfn>, <dfn id="dfn-task">task</dfn>,
<dfn id="dfn-task-source">task source</dfn>, and <dfn id="dfn-queue-a-task">queue a task</dfn> are defined by the
HTML 5 specification [<cite><a class="bibref" rel="biblioentry" href="#bib-HTML5">HTML5</a></cite>].
</p>
<p>
The term <dfn id="dfn-blob">Blob</dfn> is defined by the File API specification
[<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>].
</p>
<p>
The term <dfn id="dfn-arraybuffer">ArrayBuffer</dfn> is defined by the Typed Arrays
specification [<cite><a class="bibref" rel="biblioentry" href="#bib-TYPED-ARRAYS">TYPED-ARRAYS</a></cite>].
</p>
<p>
This specification includes algorithms (steps) as part of the definition
of methods. Conforming implementations (referred to as <dfn id="dfn-user-agents">user
agents</dfn> from here on) <em class="rfc2119" title="may">may</em> use other algorithms in the
implementation of these methods, provided the end result is the same.
</p>
</div>
<div class="informative section" id="introduction">
<!--OddPage--><h2><span class="secno">3. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
<p>
Web applications are currently fairly limited in how they can write to
files. One can present a link for download, but creating and writing
files of arbitrary type, or modifying downloaded files on their way to
the disk, is difficult or impossible. This specification defines an
API through which <a href="#dfn-user-agents" class="internalDFN">user agents</a> can permit applications to write
generated or downloaded files.
</p>
<p>
The [<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>] defined interfaces for reading files, manipulation of
<a>Blobs</a> of data, and errors raised by file accesses. This
specification extends that work with a way to construct <a>Blobs</a> and
with synchronous and asynchronous file-writing interfaces. As with
reading, writing files on the main thread should happen asynchronously
to avoid blocking UI actions. Long-running writes provide status
information through delivery of progress events.
</p>
<div id="examples" class="section">
<h3><span class="secno">3.1 </span>Examples</h3>
<p>
Here is a simple function that writes a text file, given a FileWriter:
</p>
<pre class="example sh_javascript sh_sourceCode"><span class="sh_keyword">function</span> <span class="sh_function">writeFile</span><span class="sh_symbol">(</span>writer<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
<span class="sh_keyword">function</span> <span class="sh_function">done</span><span class="sh_symbol">(</span>evt<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
<span class="sh_function">alert</span><span class="sh_symbol">(</span><span class="sh_string">"Write completed."</span><span class="sh_symbol">);</span>
<span class="sh_cbracket">}</span>
<span class="sh_keyword">function</span> <span class="sh_function">error</span><span class="sh_symbol">(</span>evt<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
<span class="sh_function">alert</span><span class="sh_symbol">(</span><span class="sh_string">"Write failed:"</span> <span class="sh_symbol">+</span> evt<span class="sh_symbol">);</span>
<span class="sh_cbracket">}</span>
<span class="sh_keyword">var</span> bb <span class="sh_symbol">=</span> <span class="sh_keyword">new</span> <span class="sh_function">BlobBuilder</span><span class="sh_symbol">();</span>
bb<span class="sh_symbol">.</span><span class="sh_function">append</span><span class="sh_symbol">(</span><span class="sh_string">"Lorem ipsum"</span><span class="sh_symbol">);</span>
writer<span class="sh_symbol">.</span>onwrite <span class="sh_symbol">=</span> done<span class="sh_symbol">;</span>
writer<span class="sh_symbol">.</span>onerror <span class="sh_symbol">=</span> error<span class="sh_symbol">;</span>
writer<span class="sh_symbol">.</span><span class="sh_function">write</span><span class="sh_symbol">(</span>bb<span class="sh_symbol">.</span><span class="sh_function">getBlob</span><span class="sh_symbol">());</span>
<span class="sh_cbracket">}</span></pre>
<p>
Here's an example of obtaining and using a <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a>:
</p>
<pre class="example sh_javascript sh_sourceCode"><span class="sh_keyword">var</span> bb <span class="sh_symbol">=</span> <span class="sh_keyword">new</span> <span class="sh_function">BlobBuilder</span><span class="sh_symbol">();</span>
bb<span class="sh_symbol">.</span><span class="sh_function">append</span><span class="sh_symbol">(</span><span class="sh_string">"Lorem ipsum"</span><span class="sh_symbol">);</span>
<span class="sh_keyword">var</span> fileSaver <span class="sh_symbol">=</span> window<span class="sh_symbol">.</span><span class="sh_function">saveAs</span><span class="sh_symbol">(</span>bb<span class="sh_symbol">.</span><span class="sh_function">getBlob</span><span class="sh_symbol">(),</span> <span class="sh_string">"test_file"</span><span class="sh_symbol">);</span>
fileSaver<span class="sh_symbol">.</span>onwriteend <span class="sh_symbol">=</span> myOnWriteEnd<span class="sh_symbol">;</span></pre>
<p></p>
</div>
</div>
<div id="the-blobbuilder-interface" class="section">
<!--OddPage--><h2><span class="secno">4. </span>The <code>BlobBuilder</code> interface</h2>
<p>
BlobBuilder description
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-BlobBuilder">[<span class="extAttr">Constructor</span>]
interface <span class="idlInterfaceID">BlobBuilder</span> {
<span class="idlMethod"> <span class="idlMethType"><a>Blob</a></span> <span class="idlMethName"><a href="#widl-BlobBuilder-getBlob">getBlob</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>in DOMString</a></span> <span class="idlParamName">contentType</span></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-BlobBuilder-append">append</a></span> (<span class="idlParam"><span class="idlParamType"><a>in DOMString</a></span> <span class="idlParamName">text</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>in DOMString</a></span> <span class="idlParamName">endings</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-BlobBuilder-append">append</a></span> (<span class="idlParam"><span class="idlParamType"><a>in Blob</a></span> <span class="idlParamName">data</span></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-BlobBuilder-append">append</a></span> (<span class="idlParam"><span class="idlParamType"><a>in ArrayBuffer</a></span> <span class="idlParamName">data</span></span>);</span>
};</span>
</pre><div id="methods" class="section"><h3><span class="secno">4.1 </span>Methods</h3><dl class="methods"><dt id="widl-BlobBuilder-append"><code>append</code></dt><dd>
<p>
Appends the supplied text to the current contents of the
<code>BlobBuilder</code>, writing it as UTF-8, converting newlines as
specified in <code>endings</code>.
</p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">text</td><td class="prmType"><code><a>in DOMString</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The data to write.
</td></tr><tr><td class="prmName">endings</td><td class="prmType"><code><a>in DOMString</a></code></td><td class="prmNullFalse">?</td><td class="prmOptTrue">?</td><td class="prmDesc">
<div class="issue">Can we do without endings? Any choice other
than "transparent" can be implemented by the app author, and
most file formats don't care about line endings. "Transparent"
would be handy for sharing certain types of text files with apps
outside the browser [e.g. Makefiles on a system where make is
expecting \n will have issues if they're written with \r\n]. Is
it worth it? Can this be worked around if we don't supply
it?</div>
<p>
This parameter specifies how strings containing <code>\n</code>
are to be written out. If the user does not provide the
<code>endings</code> parameter, <a href="#dfn-user-agents" class="internalDFN">user agents</a><a> <em class="rfc2119" title="must">must</em> act as if
the user had specified a value of 'transparent'. If the user
provides the <code>endings</code> parameter, </a><a href="#dfn-user-agents" class="internalDFN">user agents</a><a>
<em class="rfc2119" title="must">must</em> convert newlines as specified below. The possible values
are:
</a></p>
<table class="simple">
<tbody><tr><th>Value</th><th>Description</th></tr>
<tr>
<td>"transparent"</td>
<td>
Code points from the string <em class="rfc2119" title="must">must</em> remain unchanged.
</td>
</tr>
<tr>
<td>"native"</td>
<td>
Newlines <em class="rfc2119" title="must">must</em> be transformed to the default line-ending
representation of the underlying host filesystem. For
example, if the underlying filesystem is FAT32, newlines
would be transformed into <code>\r\n</code> pairs as the
text was appended to the state of the BlobBuilder.
</td>
</tr>
</tbody></table>
</td></tr></table>
<table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt><code>append</code></dt><dd>
<p>
Appends the supplied <a href="#dfn-blob" class="internalDFN">Blob</a> to the current contents of the
<code>BlobBuilder</code>.
</p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">data</td><td class="prmType"><code><a>in Blob</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The data to append.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd><dt><code>append</code></dt><dd>
<p>
Appends the supplied <a href="#dfn-arraybuffer" class="internalDFN">ArrayBuffer</a> to the current contents of the
<code>BlobBuilder</code>.
</p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">data</td><td class="prmType"><code><a>in ArrayBuffer</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The data to append.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd>
<dt id="widl-BlobBuilder-getBlob"><code>getBlob</code></dt><dd>
<p>
Returns the current contents of the <code>BlobBuilder</code> as a
<code>Blob</code>.
</p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">contentType</td><td class="prmType"><code><a>in DOMString</a></code></td><td class="prmNullFalse">?</td><td class="prmOptTrue">?</td><td class="prmDesc">
Sets the content type of the blob produced.
</td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>Blob</a></code></div></dd></dl></div>
<div id="constructor" class="section">
<h3><span class="secno">4.2 </span>Constructor</h3>
<p>
When the <a href="#idl-def-BlobBuilder" class="idlType"><code>BlobBuilder</code></a> constructor is invoked, <a href="#dfn-user-agents" class="internalDFN">user agents</a>
<em class="rfc2119" title="must">must</em> return a new <a href="#idl-def-BlobBuilder" class="idlType"><code>BlobBuilder</code></a> object.
</p>
<p>
This constructor <em class="rfc2119" title="must">must</em> be visible when the script's global object is
either a Window object or an object implementing the WorkerUtils
interface.
</p>
</div>
</div>
<div id="the-filesaver-interface" class="section">
<!--OddPage--><h2><span class="secno">5. </span>The <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> interface</h2>
<p>
This interface provides methods to monitor the asynchronous writing of
blobs to disk using progress events [<cite><a class="bibref" rel="biblioentry" href="#bib-PROGRESS-EVENTS">PROGRESS-EVENTS</a></cite>] and <a href="#dfn-event-handler-attributes" class="internalDFN">event
handler attributes</a>.
</p>
<p>
This interface is specified to be used within the context of the global
object (Window [<cite><a class="bibref" rel="biblioentry" href="#bib-HTML5">HTML5</a></cite>]) and within Web Workers (WorkerUtils
[<cite><a class="bibref" rel="biblioentry" href="#bib-WEBWORKERS">WEBWORKERS</a></cite>]).
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-FileSaver">[<span class="extAttr">Constructor(in Blob data)</span>]
interface <span class="idlInterfaceID">FileSaver</span> {
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileSaver-abort">abort</a></span> () raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileSaver-INIT">INIT</a></span> = <span class="idlConstValue">0</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileSaver-WRITING">WRITING</a></span> = <span class="idlConstValue">1</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileSaver-DONE">DONE</a></span> = <span class="idlConstValue">2</span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-readyState">readyState</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a href="#idl-def-FileError" class="idlType"><code>FileError</code></a></span> <span class="idlAttrName"><a href="#widl-FileSaver-error">error</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onwritestart">onwritestart</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onprogress">onprogress</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onwrite">onwrite</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onabort">onabort</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onerror">onerror</a></span>;</span>
<span class="idlAttribute"> attribute <span class="idlAttrType"><a>Function</a></span> <span class="idlAttrName"><a href="#widl-FileSaver-onwriteend">onwriteend</a></span>;</span>
};</span>
</pre><div id="attributes" class="section"><h3><span class="secno">5.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-FileSaver-error"><code>error</code> of type <span class="idlAttrType"><a href="#idl-def-FileError" class="idlType"><code>FileError</code></a></span>, readonly</dt><dd>
<p>
The last error that occurred on the <code>FileSaver</code>.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onabort"><code>onabort</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for abort events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onerror"><code>onerror</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for error events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onprogress"><code>onprogress</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for progress events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onwrite"><code>onwrite</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for write events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onwriteend"><code>onwriteend</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for writeend events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-onwritestart"><code>onwritestart</code> of type <span class="idlAttrType"><a>Function</a></span></dt><dd>
<p>
Handler for writestart events.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileSaver-readyState"><code>readyState</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd>
<p>
The FileSaver object can be in one of 3 states. The
<code>readyState</code> attribute, on getting, <em class="rfc2119" title="must">must</em> return the
current state, which <em class="rfc2119" title="must">must</em> be one of the following values:
</p><ul>
<li><a>INIT</a></li>
<li><a>WRITING</a></li>
<li><a>DONE</a></li>
</ul>
<p></p>
<div><em>No exceptions.</em></div></dd></dl></div><div id="methods-1" class="section"><h3><span class="secno">5.2 </span>Methods</h3><dl class="methods"><dt id="widl-FileSaver-abort"><code>abort</code></dt><dd>
<p>
When the <code>abort</code> method is called, <a href="#dfn-user-agents" class="internalDFN">user agents</a>
<em class="rfc2119" title="must">must</em> run the steps below:
</p><ol>
<li>If <code>readyState</code> is <code>DONE</code> or
<code>INIT</code>, throw a <code>FileException</code> with error
code <code>INVALID_STATE_ERR</code> and terminate this overall
series of steps.</li>
<li>Terminate any steps having to do with writing a file.</li>
<li>Queue a task that will:
<ol>
<li>Set the <code>error</code> attribute to a FileError object
with the code <a href="#dfn-abort_err" class="internalDFN">ABORT_ERR</a>.</li>
<li>Set <code>readyState</code> to <code>DONE</code>.</li>
<li>Dispatch a progress event called error.</li>
<li>Dispatch a progress event called abort</li>
<li>Dispatch a progress event called writeend</li>
</ol></li>
<li>Stop dispatching any further progress events.</li>
<li>Terminate this overall set of steps.</li>
</ol>
<p></p>
<div><em>No parameters.</em></div><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>abort</code> while <code>readyState</code>
was <code>DONE</code>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div><div id="constants" class="section"><h3><span class="secno">5.3 </span>Constants</h3><dl class="constants"><dt id="widl-FileSaver-DONE"><code>DONE</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
The entire Blob has been written to the file, a file error occurred
during the write, or the write was aborted using <a>abort()</a>. The
FileSaver is no longer writing the blob.
</dd><dt id="widl-FileSaver-INIT"><code>INIT</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
The object has been constructed, but there is no pending write.
</dd><dt id="widl-FileSaver-WRITING"><code>WRITING</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd>
The blob is being written.
</dd></dl></div>
<div id="the-filesaver-constructor" class="section">
<h3><span class="secno">5.4 </span>The FileSaver Constructor</h3>
<p>
The <code>FileSaver(data)</code> constructor takes one argument: the
Blob of data to be saved to a file.
</p>
<p>
When the <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> constructor is called, the <a href="#dfn-user-agent" class="internalDFN">user agent</a>
<em class="rfc2119" title="must">must</em> return a new <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> object with <code>readyState</code>
set to <code>INIT</code>.
</p>
<p>
This constructor <em class="rfc2119" title="must">must</em> be visible when the script's global object is
either a Window object or an object implementing the WorkerUtils
interface.
</p>
</div>
<div id="the-filesaver-task-source" class="section">
<h3><span class="secno">5.5 </span>The FileSaver Task Source</h3>
<!--
TODO: Figure out how to do the references properly. Maybe just use raw
links to a reference section, as in the File API spec.
-->
<p>
The <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> interface enables asynchronous writes on
individual files by dispatching events to event handler methods. Unless
stated otherwise, the <a href="#dfn-task-source" class="internalDFN">task source</a> that is used in this
specification is the <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a>. This <a href="#dfn-task-source" class="internalDFN">task source</a> is
used for any event <a href="#dfn-task" class="internalDFN">task</a> that is asynchronously dispatched, or for
event tasks that are queued for dispatching.
</p>
<p>
After its constructor has returned, a new FileSaver <em class="rfc2119" title="must">must</em> asynchronously
execute the following steps.
</p>
<ol>
<li>Set <code>readyState</code> to <code>WRITING</code>.</li>
<li>If an error occurs during file write, proceed to the error steps
below.
<ol>
<li>Queue a task that will:
<ol>
<li>Set the <code>error</code> attribute; on getting the
<code>error</code> attribute <em class="rfc2119" title="must">must</em> be a
<code>FileError</code> object with a valid error code that
indicates the kind of file error that has occurred.</li>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called
<code>error</code>.</li>
<li>Dispatch a progress event called
<code>writeend</code>.</li>
</ol></li>
<li>Terminate this overall set of steps.</li>
</ol>
</li>
<li>Queue a task to dispatch a progress event called
<code>writestart</code>.</li>
<li>Make progress notifications.</li>
<li>When the data has been fully written, queue a task that will:
<ol>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called <code>write</code></li>
<li>Dispatch a progress event called <code>writeend</code></li>
</ol>
</li>
<li>Terminate this overall set of steps.</li>
</ol>
</div>
<div id="event-handler-attributes" class="section">
<h3><span class="secno">5.6 </span>Event Handler Attributes</h3>
<p>
The following are the <a href="#dfn-event-handler-attributes" class="internalDFN">event handler attributes</a> (and their
corresponding <a href="#dfn-event-handler-event-types" class="internalDFN">event handler event types</a>) that user agents <em class="rfc2119" title="must">must</em>
support on <code><a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a></code> as DOM attributes:
</p>
<table class="simple">
<thead>
<tr>
<th><a>event handler attribute</a></th>
<th><a>event handler event type</a></th>
</tr>
</thead>
<tbody>
<tr>
<td><dfn id="dfn-onwritestart"><code>onwritestart</code></dfn></td>
<td><code><a>writestart</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onprogress"><code>onprogress</code></dfn></td>
<td><code><a>progress</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onwrite"><code>onwrite</code></dfn></td>
<td><code><a>write</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onabort"><code>onabort</code></dfn></td>
<td><code><a>abort</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onerror"><code>onerror</code></dfn></td>
<td><code><a>error</a></code></td>
</tr>
</tbody>
<tbody>
<tr>
<td><dfn id="dfn-onwriteend"><code>onwriteend</code></dfn></td>
<td><code><a>writeend</a></code></td>
</tr>
</tbody>
</table>
</div>
</div>
<div id="the-filesaversync-interface" class="section">
<!--OddPage--><h2><span class="secno">6. </span>The <code>FileSaverSync</code> interface</h2>
<div class="issue">
<p>
It seems like this should have a blocking constructor and no methods
or properties, if it's to follow the constructor-based model of the
asynchronous interface. A global method seems like it would be
cleaner, though. Is it important that they match? If so, the asynch
constructor could turn into a method instead.
</p>
<p>
It's been pointed out that a method name like "saveAs" is too short
and generic; any global symbol should be longer and more explicit in
order to avoid confusion and naming conflicts.
</p>
</div>
</div>
<div id="the-filewriter-interface" class="section">
<!--OddPage--><h2><span class="secno">7. </span>The <a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a> interface</h2>
<p>
This interface expands on the <a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a> interface to allow for
multiple write actions, rather than just saving a single Blob.
</p>
<div class="issue">
Since this is intended to be used only with the sandboxed filesystem,
it could potentially move to the <a href="http://dev.w3.org/2009/dap/file-system/file-dir-sys.html">filesystem
spec</a>.
</div>
<pre class="idl"><span class="idlInterface" id="idl-def-FileWriter">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">FileWriter</span> : <span class="idlSuperclass"><a href="#idl-def-FileSaver" class="idlType"><code>FileSaver</code></a></span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-FileWriter-position">position</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-FileWriter-length">length</a></span>;</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriter-write">write</a></span> (<span class="idlParam"><span class="idlParamType"><a>Blob</a></span> <span class="idlParamName">data</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriter-seek">seek</a></span> (<span class="idlParam"><span class="idlParamType"><a>long long</a></span> <span class="idlParamName">offset</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriter-truncate">truncate</a></span> (<span class="idlParam"><span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">size</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
};</span>
</pre><div id="attributes-1" class="section"><h3><span class="secno">7.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-FileWriter-length"><code>length</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
<p>
The length of the file. If the user does not have read access to the
file, this <em class="rfc2119" title="must">must</em> be the highest byte offset at which the user has
written.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileWriter-position"><code>position</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
<p>
The byte offset at which the next write to the file will occur.
This <em class="rfc2119" title="must">must</em> be no greater than <code>length</code>.<br>
A newly-created FileWriter <em class="rfc2119" title="must">must</em> have position set to 0.
</p>
<div><em>No exceptions.</em></div></dd></dl></div><div id="methods-2" class="section"><h3><span class="secno">7.2 </span>Methods</h3><dl class="methods"><dt id="widl-FileWriter-seek"><code>seek</code></dt><dd>
<p>
Seek sets the file position at which the next write will occur.
</p>
<p>
Seek may not be called while the <a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a> is in the
<code>WRITING</code> state.
</p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">offset</td><td class="prmType"><code><a>long long</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
<p>
An absolute byte offset into the file. If <code>offset</code>
is greater than <code>length</code>, <code>length</code> is used
instead. If <code>offset</code> is less than zero,
<code>length</code> is added to it, so that it is treated as an
offset back from the end of the file. If it is still less than
zero, zero is used.<br>
</p>
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>seek</code> while <code>readyState</code>
was <code>WRITING</code>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-FileWriter-truncate"><code>truncate</code></dt><dd>
<p>
Changes the length of the file to that specified. If shortening the
file, data beyond the new length <em class="rfc2119" title="must">must</em> be discarded. If extending
the file, the existing data <em class="rfc2119" title="must">must</em> be zero-padded up to the new
length.
</p>
<p>
When the <code>truncate</code> method is called, <a href="#dfn-user-agents" class="internalDFN">user agents</a>
<em class="rfc2119" title="must">must</em> run the steps below (unless otherwise indicated).
</p>
<ol>
<li>If <code>readyState</code> is <code>WRITING</code>, throw a
<code>FileException</code> with error code
<code>INVALID_STATE_ERR</code> and terminate this overall series of
steps.</li>
<li>Set <code>readyState</code> to <code>WRITING</code>.</li>
<li>If an error occurs during truncate, proceed to the error steps
below.
<ol>
<li>Queue a task that will:
<ol>
<li>Set the <code>error</code> attribute; on getting the
<code>error</code> attribute <em class="rfc2119" title="must">must</em> be a
<code>FileError</code> object with a valid error code that
indicates the kind of file error that has occurred.</li>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called
<code>error</code>.</li>
<li>Dispatch a progress event called
<code>writeend</code></li>
</ol></li>
<li>On getting, the <code>length</code> and
<code>position</code> attributes <em class="rfc2119" title="should">should</em> indicate any
modification to the file.</li>
<li>Terminate this overall set of steps.</li>
</ol>
</li>
<li>Queue a task to dispatch a progress event called
<code>writestart</code>.</li>
<li>Upon successful completion:
<ul>
<li><code>length</code> <em class="rfc2119" title="must">must</em> be equal to <code>size</code>.</li>
<li><code>position</code> <em class="rfc2119" title="must">must</em> be the lesser of
<ul>
<li>its pre-truncate value,</li>
<li><code>size</code>.</li>
</ul>
</li>
<li>Queue a task that will:
<ol>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called <code>write</code></li>
<li>Dispatch a progress event called
<code>writeend</code></li>
</ol></li>
<li>Terminate this overall set of steps.</li>
</ul>
</li>
</ol>
<p></p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">size</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The size to which the length of the file is to be adjusted,
measured in bytes.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>truncate</code> while
<code>readyState</code> was <code>WRITING</code>.
</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-FileWriter-write"><code>write</code></dt><dd>
<p>
Write the supplied data to the file at <code>position</code>. When
the <code>write</code> method is called, <a href="#dfn-user-agents" class="internalDFN">user agents</a> <em class="rfc2119" title="must">must</em> run
the steps below (unless otherwise indicated).
</p><ol>
<li>If <code>readyState</code> is <code>WRITING</code>, throw a
<code>FileException</code> with error code
<code>INVALID_STATE_ERR</code> and terminate this overall series
of steps.</li>
<li>Set <code>readyState</code> to <code>WRITING</code>.</li>
<li>If an error occurs during file write, proceed to the error
steps below.
<ol>
<li>Queue a task that will:
<ol>
<li>Set the <code>error</code> attribute; on getting the
<code>error</code> attribute <em class="rfc2119" title="must">must</em> be a
<code>FileError</code> object with a valid error code that
indicates the kind of file error that has occurred.</li>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called
<code>error</code>.</li>
<li>Dispatch a progress event called
<code>writeend</code></li>
</ol></li>
<li>On getting, the <code>length</code> and
<code>position</code> attributes <em class="rfc2119" title="should">should</em> indicate any
fractional data successfully written to the file.</li>
<li>Terminate this overall set of steps.</li>
</ol>
</li>
<li>Queue a task to dispatch a progress event called
<code>writestart</code>.</li>
<li>Make progress notifications. On getting, while processing the
<code>write</code> method, the <code>length</code> and
<code>position</code> attributes <em class="rfc2119" title="should">should</em> indicate the progress
made in writing the file as of the last progress notification.
</li>
<li>Upon successful completion:
<ol>
<li><code>position</code> and <code>length</code> <em class="rfc2119" title="must">must</em>
indicate an increase of <code>data.size</code> over their
pre-write states, indicating the change to the underlying
file.</li>
<li>Queue a task that will:
<ol>
<li>Set readyState to <code>DONE</code>.</li>
<li>Dispatch a progress event called
<code>write</code></li>
<li>Dispatch a progress event called
<code>writeend</code></li>
</ol></li>
<li>Terminate this overall set of steps.</li>
</ol>
</li></ol>
<p></p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">data</td><td class="prmType"><code><a>Blob</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The blob to write.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>write</code> while <code>readyState</code>
was <code>WRITING</code>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
</div>
<div id="the-filewritersync-interface" class="section">
<!--OddPage--><h2><span class="secno">8. </span>The <code>FileWriterSync</code> interface</h2>
<p>
This interface lets users write, truncate, and append to files using
simple synchronous calls.
</p>
<p>
This interface is specified to be used only within Web Workers
(WorkerUtils [<cite><a class="bibref" rel="biblioentry" href="#bib-WEBWORKERS">WEBWORKERS</a></cite>]).
</p>
<div class="issue">
Since this is intended to be used only with the sandboxed filesystem,
it could potentially move to the <a href="http://dev.w3.org/2009/dap/file-system/file-dir-sys.html">filesystem
spec</a>.
</div>
<pre class="idl"><span class="idlInterface" id="idl-def-FileWriterSync">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">FileWriterSync</span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-FileWriterSync-position">position</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long long</a></span> <span class="idlAttrName"><a href="#widl-FileWriterSync-length">length</a></span>;</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriterSync-write">write</a></span> (<span class="idlParam"><span class="idlParamType"><a>Blob</a></span> <span class="idlParamName">data</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriterSync-seek">seek</a></span> (<span class="idlParam"><span class="idlParamType"><a>long long</a></span> <span class="idlParamName">offset</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-FileWriterSync-truncate">truncate</a></span> (<span class="idlParam"><span class="idlParamType"><a>unsigned long long</a></span> <span class="idlParamName">size</span></span>) raises (<span class="idlRaises"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></span>);</span>
};</span>
</pre><div id="attributes-2" class="section"><h3><span class="secno">8.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-FileWriterSync-length"><code>length</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
<p>
The length of the file. If the user does not have read access to
the file, this <em class="rfc2119" title="must">must</em> be the highest byte offset at which the user has
written.
</p>
<div><em>No exceptions.</em></div></dd><dt id="widl-FileWriterSync-position"><code>position</code> of type <span class="idlAttrType"><a>unsigned long long</a></span>, readonly</dt><dd>
<p>
The byte offset at which the next write to the file will occur.
This <em class="rfc2119" title="must">must</em> be no greater than <code>length</code>.
</p>
<div><em>No exceptions.</em></div></dd></dl></div><div id="methods-3" class="section"><h3><span class="secno">8.2 </span>Methods</h3><dl class="methods"><dt id="widl-FileWriterSync-seek"><code>seek</code></dt><dd>
<p>
Seek sets the file position at which the next write will occur.
</p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">offset</td><td class="prmType"><code><a>long long</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
An absolute byte offset into the file. If <code>offset</code>
is greater than <code>length</code>, <code>length</code> is used
instead. If <code>offset</code> is less than zero,
<code>length</code> is added to it, so that it is treated as an
offset back from the end of the file. If it is still less than
zero, zero is used.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">A user called <code>seek</code> while <code>readyState</code>
was <code>WRITING</code>.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-FileWriterSync-truncate"><code>truncate</code></dt><dd>
<p>
Changes the length of the file to that specified. If shortening the
file, data beyond the new length <em class="rfc2119" title="must">must</em> be discarded. If extending
the file, the existing data <em class="rfc2119" title="must">must</em> be zero-padded up to the new
length.
</p>
<p>
Upon successful completion:
</p><ul>
<li><code>length</code> <em class="rfc2119" title="must">must</em> be equal to <code>size</code>.</li>
<li><code>position</code> <em class="rfc2119" title="must">must</em> be the lesser of
<ul>
<li>its pre-truncate value,</li>
<li><code>size</code>.</li>
</ul>
</li>
</ul>
<p></p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">size</td><td class="prmType"><code><a>unsigned long long</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The size to which the length of the file is to be adjusted,
measured in bytes.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>NO_MODIFICATION_ALLOWED_ERR</code></td><td class="excCodeDesc">The user attempted to modify a read-only file.</td></tr><tr><td class="excCodeName"><code>NOT_FOUND_ERR</code></td><td class="excCodeDesc">The file to be truncated does not exist.</td></tr><tr><td class="excCodeName"><code>SECURITY_ERR</code></td><td class="excCodeDesc">The system has disallowed the truncation for security
reasons.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-FileWriterSync-write"><code>write</code></dt><dd>
<p>
Write the supplied data to the file at <code>position</code>.
Upon completion, <code>position</code> will increase by
<code>data.size</code>.
</p>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">data</td><td class="prmType"><code><a>Blob</a></code></td><td class="prmNullFalse">?</td><td class="prmOptFalse">?</td><td class="prmDesc">
The blob to write.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a href="#idl-def-FileException" class="idlType"><code>FileException</code></a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>NO_MODIFICATION_ALLOWED_ERR</code></td><td class="excCodeDesc">The user attempted to modify a read-only file.</td></tr><tr><td class="excCodeName"><code>NOT_FOUND_ERR</code></td><td class="excCodeDesc">The path to the directory containing the file to be written does
not exist, or the file does not exist and offset is nonzero.</td></tr><tr><td class="excCodeName"><code>INVALID_STATE_ERR</code></td><td class="excCodeDesc">At the time of the call, <code>readyState</code> was
<code>WRITING</code>.</td></tr><tr><td class="excCodeName"><code>SECURITY_ERR</code></td><td class="excCodeDesc">The system has disallowed the write for security reasons.</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
</div>
<div id="errors-and-exceptions" class="section">
<!--OddPage--><h2><span class="secno">9. </span>Errors and Exceptions</h2>
<p>
Error conditions can occur when attempting to write files. The list
below of potential error conditions is informative, with links to
normative descriptions of error codes:
</p>
<p>
The directory containing the file being written may not exist at the
time one of the asynchronous write methods or synchronous write methods
is 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).<br>
See <a href="#dfn-not_found_err" class="internalDFN">NOT_FOUND_ERR</a>.
</p>
<p>
The file being written may have been removed. If the file is not there,
writing to an offset other than zero is not permitted.<br>
See <a href="#dfn-not_found_err" class="internalDFN">NOT_FOUND_ERR</a>.
</p>
<p>
A file may be unwritable. This may be due to permission problems that
occur after a reference to a file has been acquired (e.g. concurrent
lock with another application).<br>
See <a href="#dfn-no_modification_allowed_err" class="internalDFN">NO_MODIFICATION_ALLOWED_ERR</a>.
</p>
<p>
User agents <em class="rfc2119" title="may">may</em> determine that some files are unsafe for use within web
applications. Additionally, some file and directory structures may be
considered restricted by the underlying filesystem; attempts to write to
them may be considered a security violation. See the security
considerations.<br>
See <a href="#dfn-security_err" class="internalDFN">SECURITY_ERR</a>.
</p>
<p>
A web application may attempt to initiate a write, seek, or truncate via
a FileWriter in the <code>WRITING</code> state.<br>
See <a href="#dfn-invalid_state_err" class="internalDFN">INVALID_STATE_ERR</a>.
</p>
<p>
During the writing of a file, the web application may itself wish to
abort (see abort()) the call to an asynchronous write method.<br>
See <a href="#dfn-abort_err" class="internalDFN">ABORT_ERR</a>.
</p>
<p>
A web application may request unsupported line endings.
See <a href="#dfn-syntax_err" class="internalDFN">SYNTAX_ERR</a>.
</p>
<div id="the-fileerror-interface" class="section">
<h3><span class="secno">9.1 </span>The FileError Interface</h3>
<p>
This interface extends the <a href="#idl-def-FileError" class="idlType"><code>FileError</code></a> interface described in
[<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>] to add several new error codes. It is used to report
errors asynchronously. The FileWriter object's error attribute is a
FileError object, and is accessed asynchronously through the onerror
event handler when error events are generated.
</p>
<pre class="idl"><span class="idlInterface" id="idl-def-FileError">interface <span class="idlInterfaceID">FileError</span> {
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-NOT_FOUND_ERR">NOT_FOUND_ERR</a></span> = <span class="idlConstValue">1</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-SECURITY_ERR">SECURITY_ERR</a></span> = <span class="idlConstValue">2</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-ABORT_ERR">ABORT_ERR</a></span> = <span class="idlConstValue">3</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-NOT_READABLE_ERR">NOT_READABLE_ERR</a></span> = <span class="idlConstValue">4</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-ENCODING_ERR">ENCODING_ERR</a></span> = <span class="idlConstValue">5</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-NO_MODIFICATION_ALLOWED_ERR">NO_MODIFICATION_ALLOWED_ERR</a></span> = <span class="idlConstValue">6</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-INVALID_STATE_ERR">INVALID_STATE_ERR</a></span> = <span class="idlConstValue">7</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileError-SYNTAX_ERR">SYNTAX_ERR</a></span> = <span class="idlConstValue">8</span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned short</a></span> <span class="idlAttrName"><a href="#widl-FileError-code">code</a></span>;</span>
};</span>
</pre><div id="attributes-3" class="section"><h4><span class="secno">9.1.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-FileError-code"><code>code</code> of type <span class="idlAttrType"><a>unsigned short</a></span>, readonly</dt><dd> <div><em>No exceptions.</em></div></dd></dl></div><div id="constants-1" class="section"><h4><span class="secno">9.1.2 </span>Constants</h4><dl class="constants"><dt id="widl-FileError-ABORT_ERR"><code>ABORT_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-ENCODING_ERR"><code>ENCODING_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-INVALID_STATE_ERR"><code>INVALID_STATE_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-NOT_READABLE_ERR"><code>NOT_READABLE_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-NO_MODIFICATION_ALLOWED_ERR"><code>NO_MODIFICATION_ALLOWED_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-SECURITY_ERR"><code>SECURITY_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileError-SYNTAX_ERR"><code>SYNTAX_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd></dl></div>
The <a>code</a> attribute <em class="rfc2119" title="must">must</em> return one of the constants of the
<a href="#idl-def-FileError" class="idlType"><code>FileError</code></a> error, which <em class="rfc2119" title="must">must</em> be the most appropriate code from the
<a href="#dfn-error-code-descriptions" class="internalDFN">Error Code Descriptions</a>.
</div>
<div id="the-fileexception-exception" class="section">
<h3><span class="secno">9.2 </span>The FileException exception</h3>
This interface extends the <a href="#idl-def-FileException" class="idlType"><code>FileException</code></a> interface described in
[<cite><a class="bibref" rel="biblioentry" href="#bib-FILE-API">FILE-API</a></cite>] to add several new error codes.
Any errors that need to be reported synchronously, including all that
occur during use of the synchronous write methods for Web Workers
[<cite><a class="bibref" rel="biblioentry" href="#bib-WEBWORKERS">WEBWORKERS</a></cite>] are reported using the FileException exception.
<pre class="idl"><span class="idlException" id="idl-def-FileException">exception <span class="idlExceptionID">FileException</span> {
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-NOT_FOUND_ERR">NOT_FOUND_ERR</a></span> = <span class="idlConstValue">1</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-SECURITY_ERR">SECURITY_ERR</a></span> = <span class="idlConstValue">2</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-ABORT_ERR">ABORT_ERR</a></span> = <span class="idlConstValue">3</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-NOT_READABLE_ERR">NOT_READABLE_ERR</a></span> = <span class="idlConstValue">4</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-ENCODING_ERR">ENCODING_ERR</a></span> = <span class="idlConstValue">5</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-NO_MODIFICATION_ALLOWED_ERR">NO_MODIFICATION_ALLOWED_ERR</a></span> = <span class="idlConstValue">6</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-INVALID_STATE_ERR">INVALID_STATE_ERR</a></span> = <span class="idlConstValue">7</span>;</span>
<span class="idlConst"> const <span class="idlConstType"><a>unsigned short</a></span> <span class="idlConstName"><a href="#widl-FileException-SYNTAX_ERR">SYNTAX_ERR</a></span> = <span class="idlConstValue">8</span>;</span>
<span class="idlField"> <span class="idlFieldType"><a>unsigned short</a></span> <span class="idlFieldName"><a href="#widl-FileException-code">code</a></span>;</span>
};</span>
</pre><div id="fields" class="section"><h4><span class="secno">9.2.1 </span>Fields</h4><dl class="fields"><dt id="widl-FileException-code"><code>code</code> of type <span class="idlFieldType"><a>unsigned short</a></span></dt><dd> </dd></dl></div><div id="constants-2" class="section"><h4><span class="secno">9.2.2 </span>Constants</h4><dl class="constants"><dt id="widl-FileException-ABORT_ERR"><code>ABORT_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-ENCODING_ERR"><code>ENCODING_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-INVALID_STATE_ERR"><code>INVALID_STATE_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-NOT_READABLE_ERR"><code>NOT_READABLE_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-NO_MODIFICATION_ALLOWED_ERR"><code>NO_MODIFICATION_ALLOWED_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-SECURITY_ERR"><code>SECURITY_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd><dt id="widl-FileException-SYNTAX_ERR"><code>SYNTAX_ERR</code> of type <span class="idlConstType"><a>unsigned short</a></span></dt><dd> </dd></dl></div>
The <a>code</a> field <em class="rfc2119" title="must">must</em> return one of the constants of the
<a href="#idl-def-FileException" class="idlType"><code>FileException</code></a> error, which <em class="rfc2119" title="must">must</em> be the most appropriate code from
the <a href="#dfn-error-code-descriptions" class="internalDFN">Error Code Descriptions</a>.
</div>
<div id="error-code-descriptions" class="section">
<h3><span class="secno">9.3 </span><dfn id="dfn-error-code-descriptions">Error Code Descriptions</dfn></h3>
<table class="simple">
<thead>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
<td><dfn id="dfn-no_modification_allowed_err">NO_MODIFICATION_ALLOWED_ERR</dfn></td><td>7</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code when attempting to write to a
file which cannot be modified due to the state of the
underlying filesystem.
</td>
</tr>
<tr>
<td><dfn id="dfn-not_found_err">NOT_FOUND_ERR</dfn></td><td>8</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code if:
<ul>
<li>the directory containing the file to be written could
not be found at the time the write was processed.</li>
<li>the file to be written does not exist at the time the
write was processed, and an <code>offset</code> other than
zero is specified.</li>
</ul>
</td>
</tr>
<tr>
<td><dfn id="dfn-invalid_state_err">INVALID_STATE_ERR</dfn></td><td>11</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code if an application attempts to
initiate a write, truncate, or seek using a <a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a>
which is already in the <a>WRITING</a> state.
</td>
</tr>
<tr>
<td><dfn id="dfn-syntax_err">SYNTAX_ERR</dfn></td><td>12</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code when an application attempts
to supply an invalid line ending specifier to the API.
</td>
</tr>
<tr>
<td><dfn id="dfn-security_err">SECURITY_ERR</dfn></td><td>18</td>
<td>
User agents <em class="rfc2119" title="may">may</em> use this code if:
<ul>
<li> it is determined that certain files are unsafe for
access within a Web application</li>
<li>it is determined that too many write calls are being
made on file resources</li>
<li>it is determined that the file has changed on disk since
the user selected it</li>
</ul>
This is a security error code to be used in situations not
covered by any other error codes.
</td>
</tr>
<tr>
<td><dfn id="dfn-abort_err">ABORT_ERR</dfn></td><td>20</td>
<td>User agents <em class="rfc2119" title="must">must</em> use this code if the read operation was
aborted, typically with a call to <a>abort()</a>.
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="informative section" id="security-considerations">
<!--OddPage--><h2><span class="secno">10. </span>Security Considerations</h2><p><em>This section is non-normative.</em></p>
<div id="basic-security-model" class="section">
<h3><span class="secno">10.1 </span>Basic Security Model</h3>
<p>
Most of the security issues pertaining to writing to a file on the
user's drive are the same as those involved in downloading arbitrary
files from the Internet. The primary difference [in the case of
FileWriter] stems from the fact that the file may be continuously
written and re-written, at least until such a time as it is deemed
closed by the <a href="#dfn-user-agent" class="internalDFN">user agent</a>. This has an impact on disk quota, IO
bandwidth, and on processes that may require analysing the content of
the file.
</p>
</div>
<div id="write-only-files" class="section">
<h3><span class="secno">10.2 </span>Write-Only Files</h3>
<p>
When a user grants an application write access to a file, it doesn't
necessarily imply that the app should also receive read access to that
file or any of that file's metadata [including length]. This
specification describes a way in which that information can be kept
secret for write-only files. If the application has obtained a
<a href="#idl-def-FileWriter" class="idlType"><code>FileWriter</code></a> through a mechanism that also implies read access,
those restrictions may be relaxed.
</p>
</div>
<div id="quotas" class="section">
<h3><span class="secno">10.3 </span>Quotas</h3>
<p>
Where quotas are concerned, <a href="#dfn-user-agents" class="internalDFN">user agents</a> may wish to monitor the
size of the file(s) being written and possibly interrupt the script and
warn the user if certain limits of file size, remaining space, or disk
bandwidth are reached.
</p>
</div>
<div id="other-standard-techniques" class="section">
<h3><span class="secno">10.4 </span>Other Standard Techniques</h3>
<p>
Other parts of the download protection tool-chain such as flagging files
as unsafe to open, refusing to create dangerous file names, and making
sure that the mime type of a file matches its extension should naturally
be applied.
</p>
</div>
</div>
<div class="appendix section" id="acknowledgements">
<!--OddPage--><h2><span class="secno">A. </span>Acknowledgements</h2>
<p>
Thanks to Arun Ranganathan for his File API, Opera for theirs, and Robin
Berjon both for his work on various file APIs and for <a href="http://dev.w3.org/2009/dap/ReSpec.js/documentation.html">ReSpec</a>.
</p>
</div>
<div id="references" class="appendix section"><!--OddPage--><h2><span class="secno">B. </span>References</h2><div id="normative-references" class="section"><h3><span class="secno">B.1 </span>Normative references</h3><dl class="bibliography"><dt id="bib-FILE-API">[FILE-API]</dt><dd>Arun Ranganathan. <a href="http://www.w3.org/TR/2009/WD-FileAPI-20091117/"><cite>File API.</cite></a> 17 November 2009. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2009/WD-FileAPI-20091117/">http://www.w3.org/TR/2009/WD-FileAPI-20091117/</a>
</dd><dt id="bib-HTML5">[HTML5]</dt><dd>Ian Hickson; David Hyatt. <a href="http://www.w3.org/TR/2010/WD-html5-20100304/"><cite>HTML 5.</cite></a> 4 March 2010. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2010/WD-html5-20100304/">http://www.w3.org/TR/2010/WD-html5-20100304/</a>
</dd><dt id="bib-PROGRESS-EVENTS">[PROGRESS-EVENTS]</dt><dd>Charles McCathieNevile. <a href="http://www.w3.org/TR/2008/WD-progress-events-20080521"><cite>Progress Events 1.0.</cite></a> 21 May 2008. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2008/WD-progress-events-20080521">http://www.w3.org/TR/2008/WD-progress-events-20080521</a>
</dd><dt id="bib-RFC2119">[RFC2119]</dt><dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate Requirement Levels.</cite></a> March 1997. Internet RFC 2119. URL: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
</dd><dt id="bib-TYPED-ARRAYS">[TYPED-ARRAYS]</dt><dd>Vladimir Vukicevic, Kenneth Russell. <a href="https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html"><cite>Typed Arrays</cite></a> Khronos Working Draft. (Work in progress.) URL: <a href="https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html">https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html</a>
</dd><dt id="bib-WEBWORKERS">[WEBWORKERS]</dt><dd>Ian Hickson. <a href="http://www.w3.org/TR/2009/WD-workers-20091222/"><cite>Web Workers.</cite></a> 22 December 2009. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2009/WD-workers-20091222/">http://www.w3.org/TR/2009/WD-workers-20091222/</a>
</dd></dl></div><div id="informative-references" class="section"><h3><span class="secno">B.2 </span>Informative references</h3><p>No informative references.</p></div></div></body></html>