summaryrefslogtreecommitdiffstats
path: root/dom/chrome-webidl/IOUtils.webidl
blob: a3e19c0401002514f4577efbbaf09d7f27ec6917 (plain)
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
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/.
 */

interface nsIFile;

/**
 * IOUtils is a simple, efficient interface for performing file I/O from a
 * privileged chrome-only context. All asynchronous I/O tasks are run on
 * a background thread.
 *
 * Pending I/O tasks will block shutdown at the |profileBeforeChange| phase.
 * During this shutdown phase, no additional I/O tasks will be accepted --
 * method calls to this interface will reject once shutdown has entered this
 * phase.
 *
 * IOUtils methods may reject for any number of reasons. Reasonable attempts
 * have been made to map each common operating system error to a |DOMException|.
 * Most often, a caller only needs to check if a given file wasn't found by
 * catching the rejected error and checking if |ex.name === 'NotFoundError'|.
 * In other cases, it is likely sufficient to allow the error to be caught and
 * reported elsewhere.
 */
[ChromeOnly, Exposed=(Window, Worker)]
namespace IOUtils {
 /**
   * Reads up to |opts.maxBytes| of the file at |path| according to |opts|.
   *
   * NB: The maximum file size that can be read is UINT32_MAX.
   *
   * @param path An absolute file path.
   *
   * @return Resolves with an array of unsigned byte values read from disk,
   *         otherwise rejects with a DOMException.
   */
  [NewObject]
  Promise<Uint8Array> read(DOMString path, optional ReadOptions opts = {});
  /**
   * Reads the UTF-8 text file located at |path| and returns the decoded
   * contents as a |DOMString|. If a UTF-8 byte order marker (BOM) is
   * present, it will be stripped from the returned string.
   *
   * NB: The maximum file size that can be read is UINT32_MAX.
   *
   * @param path An absolute file path.
   *
   * @return Resolves with the file contents encoded as a string, otherwise
   *         rejects with a DOMException.
   */
  [NewObject]
  Promise<UTF8String> readUTF8(DOMString path, optional ReadUTF8Options opts = {});
  /**
   * Read the UTF-8 text file located at |path| and return the contents
   * parsed as JSON into a JS value.
   *
   * NB: The maximum file size that can be read is UINT32_MAX.
   *
   * @param path An absolute path.
   *
   * @return Resolves with the contents of the file parsed as JSON.
   */
  [NewObject]
  Promise<any> readJSON(DOMString path, optional ReadUTF8Options opts = {});
  /**
   * Attempts to safely write |data| to a file at |path|.
   *
   * This operation can be made atomic by specifying the |tmpPath| option. If
   * specified, then this method ensures that the destination file is not
   * modified until the data is entirely written to the temporary file, after
   * which point the |tmpPath| is moved to the specified |path|.
   *
   * The target file can also be backed up to a |backupFile| before any writes
   * are performed to prevent data loss in case of corruption.
   *
   * @param path    An absolute file path.
   * @param data    Data to write to the file at path.
   *
   * @return Resolves with the number of bytes successfully written to the file,
   *         otherwise rejects with a DOMException.
   */
  [NewObject]
  Promise<unsigned long long> write(DOMString path, Uint8Array data, optional WriteOptions options = {});
  /**
   * Attempts to encode |string| to UTF-8, then safely write the result to a
   * file at |path|. Works exactly like |write|.
   *
   * @param path      An absolute file path.
   * @param string    A string to write to the file at path.
   * @param options   Options for writing the file.
   *
   * @return Resolves with the number of bytes successfully written to the file,
   *         otherwise rejects with a DOMException.
   */
  [NewObject]
  Promise<unsigned long long> writeUTF8(DOMString path, UTF8String string, optional WriteOptions options = {});
  /**
   * Attempts to serialize |value| into a JSON string and encode it as into a
   * UTF-8 string, then safely write the result to a file at |path|. Works
   * exactly like |write|.
   *
   * @param path      An absolute file path
   * @param value     The value to be serialized.
   * @param options   Options for writing the file. The "append" mode is not supported.
   *
   * @return Resolves with the number of bytes successfully written to the file,
   *         otherwise rejects with a DOMException.
   */
  [NewObject]
  Promise<unsigned long long> writeJSON(DOMString path, any value, optional WriteOptions options = {});
  /**
   * Moves the file from |sourcePath| to |destPath|, creating necessary parents.
   * If |destPath| is a directory, then the source file will be moved into the
   * destination directory.
   *
   * @param sourcePath An absolute file path identifying the file or directory
   *                   to move.
   * @param destPath   An absolute file path identifying the destination
   *                   directory and/or file name.
   *
   * @return Resolves if the file is moved successfully, otherwise rejects with
   *         a DOMException.
   */
  [NewObject]
  Promise<undefined> move(DOMString sourcePath, DOMString destPath, optional MoveOptions options = {});
  /**
   * Removes a file or directory at |path| according to |options|.
   *
   * @param path An absolute file path identifying the file or directory to
   *             remove.
   *
   * @return Resolves if the file is removed successfully, otherwise rejects
   *         with a DOMException.
   */
  [NewObject]
  Promise<undefined> remove(DOMString path, optional RemoveOptions options = {});
  /**
   * Creates a new directory at |path| according to |options|.
   *
   * @param path An absolute file path identifying the directory to create.
   *
   * @return Resolves if the directory is created successfully, otherwise
   *         rejects with a DOMException.
   */
  [NewObject]
  Promise<undefined> makeDirectory(DOMString path, optional MakeDirectoryOptions options = {});
  /**
   * Obtains information about a file, such as size, modification dates, etc.
   *
   * @param path An absolute file path identifying the file or directory to
   *             inspect.
   *
   * @return Resolves with a |FileInfo| object for the file at path, otherwise
   *         rejects with a DOMException.
   *
   * @see FileInfo
   */
  [NewObject]
  Promise<FileInfo> stat(DOMString path);
  /**
   * Copies a file or directory from |sourcePath| to |destPath| according to
   * |options|.
   *
   * @param sourcePath An absolute file path identifying the source file to be
   *                   copied.
   * @param destPath   An absolute file path identifying the location for the
   *                   copy.
   *
   * @return Resolves if the file was copied successfully, otherwise rejects
   *         with a DOMException.
   */
  [NewObject]
  Promise<undefined> copy(DOMString sourcePath, DOMString destPath, optional CopyOptions options = {});
  /**
   * Updates the access time for the file at |path|.
   *
   * @param path         An absolute file path identifying the file whose
   *                     modification time is to be set. This file must exist
   *                     and will not be created.
   * @param modification An optional access time for the file expressed in
   *                     milliseconds since the Unix epoch
   *                     (1970-01-01T00:00:00Z). The current system time is used
   *                     if this parameter is not provided.
   *
   * @return Resolves with the updated access time time expressed in
   *         milliseconds since the Unix epoch, otherwise rejects with a
   *         DOMException.
   */
  [NewObject]
  Promise<long long> setAccessTime(DOMString path, optional long long access);
  /**
   * Updates the modification time for the file at |path|.
   *
   * @param path         An absolute file path identifying the file whose
   *                     modification time is to be set. This file must exist
   *                     and will not be created.
   * @param modification An optional modification time for the file expressed in
   *                     milliseconds since the Unix epoch
   *                     (1970-01-01T00:00:00Z). The current system time is used
   *                     if this parameter is not provided.
   *
   * @return Resolves with the updated modification time expressed in
   *         milliseconds since the Unix epoch, otherwise rejects with a
   *         DOMException.
   */
  [NewObject]
  Promise<long long> setModificationTime(DOMString path, optional long long modification);
  /**
   * Retrieves a (possibly empty) list of immediate children of the directory at
   * |path|.
   *
   * @param path An absolute file path.
   *
   * @return Resolves with a sequence of absolute file paths representing the
   *         children of the directory at |path|, otherwise rejects with a
   *         DOMException.
   */
  [NewObject]
  Promise<sequence<DOMString>> getChildren(DOMString path, optional GetChildrenOptions options = {});
  /**
   * Set the permissions of the file at |path|.
   *
   * Windows does not make a distinction between user, group, and other
   * permissions like UNICES do. If a permission flag is set for any of user,
   * group, or other has a permission, then all users will have that
   * permission. Additionally, Windows does not support setting the
   * "executable" permission.
   *
   * @param path        An absolute file path
   * @param permissions The UNIX file mode representing the permissions.
   * @param honorUmask  If omitted or true, any UNIX file mode value is
   *                    modified by the process umask. If false, the exact value
   *                    of UNIX file mode will be applied. This value has no effect
   *                    on Windows.
   *
   * @return Resolves if the permissions were set successfully, otherwise
   *         rejects with a DOMException.
   */
  [NewObject]
  Promise<undefined> setPermissions(DOMString path, unsigned long permissions, optional boolean honorUmask = true);
  /**
   * Return whether or not the file exists at the given path.
   *
   * @param path An absolute file path.
   *
   * @return A promise that resolves to whether or not the given file exists.
   */
  [NewObject]
  Promise<boolean> exists(DOMString path);

  /**
   * Create a file with a unique name and return its path.
   *
   * @param parent An absolute path to the directory where the file is to be
   *               created.
   * @param prefix A prefix for the filename.
   *
   * @return A promise that resolves to a unique filename.
   */
  [NewObject]
  Promise<DOMString> createUniqueFile(DOMString parent, DOMString prefix, optional unsigned long permissions = 0644);

  /**
   * Create a directory with a unique name and return its path.
   *
   * @param parent An absolute path to the directory where the file is to be
   *               created.
   * @param prefix A prefix for the directory name.
   *
   * @return A promise that resolves to a unique directory name.
   */
  [NewObject]
  Promise<DOMString> createUniqueDirectory(DOMString parent, DOMString prefix, optional unsigned long permissions = 0755);

  /**
   * Compute the hash of a file as a hex digest.
   *
   * @param path   The absolute path of the file to hash.
   * @param method The hashing method to use.
   *
   * @return A promise that resolves to the hex digest of the file's hash in lowercase.
   */
  [NewObject]
  Promise<UTF8String> computeHexDigest(DOMString path, HashAlgorithm method);

#if defined(XP_WIN)
  /**
   * Return the Windows-specific file attributes of the file at the given path.
   *
   * @param path An absolute file path.
   *
   * @return A promise that resolves to the Windows-specific file attributes.
   */
  [NewObject]
  Promise<WindowsFileAttributes> getWindowsAttributes(DOMString path);

  /**
   * Set the Windows-specific file attributes of the file at the given path.
   *
   * @param path An absolute file path.
   * @param attrs The attributes to set. Attributes will only be set if they are
   *              |true| or |false| (i.e., |undefined| attributes are not
   *              changed).
   *
   * @return A promise that resolves is the attributes were set successfully.
   */
  [NewObject]
  Promise<undefined> setWindowsAttributes(DOMString path, optional WindowsFileAttributes attrs = {});
#elif defined(XP_MACOSX)
  /**
   * Return whether or not the file has a specific extended attribute.
   *
   * @param path An absolute path.
   * @param attr The attribute to check for.
   *
   * @return A promise that resolves to whether or not the file has an extended
   *         attribute, or rejects with an error.
   */
  [NewObject]
  Promise<boolean> hasMacXAttr(DOMString path, UTF8String attr);
  /**
   * Return the value of an extended attribute for a file.
   *
   * @param path An absolute path.
   * @param attr The attribute to get the value of.
   *
   * @return A promise that resolves to the value of the extended attribute, or
   *         rejects with an error.
   */
  [NewObject]
  Promise<Uint8Array> getMacXAttr(DOMString path, UTF8String attr);
  /**
   * Set the extended attribute on a file.
   *
   * @param path  An absolute path.
   * @param attr  The attribute to set.
   * @param value The value of the attribute to set.
   *
   * @return A promise that resolves to whether or not the file has an extended
   *         attribute, or rejects with an error.
   */
  [NewObject]
  Promise<undefined> setMacXAttr(DOMString path, UTF8String attr, Uint8Array value);
  /**
   * Delete the extended attribute on a file.
   *
   * @param path An absolute path.
   * @param attr The attribute to delete.
   *
   * @return A promise that resolves if the attribute was deleted, or rejects
   *         with an error.
   */
  [NewObject]
  Promise<undefined> delMacXAttr(DOMString path, UTF8String attr);
#endif

  /**
   * Return a nsIFile whose parent directory exists. The parent directory of the
   * file will be created off main thread if it does not already exist.
   *
   * @param components The path components. The first component must be an
   *                   absolute path.
   *
   * @return A promise that resolves to an nsIFile for the requested file.
   */
  [NewObject]
  Promise<nsIFile> getFile(DOMString... components);

  /**
   * Return an nsIFile corresponding to a directory. It will be created
   * off-main-thread if it does not already exist.
   *
   * @param components The path components. The first component must be an
   *                   absolute path.
   *
   * @return A promise that resolves to an nsIFile for the requested directory.
   */
  [NewObject]
  Promise<nsIFile> getDirectory(DOMString... components);
};

[Exposed=Window]
partial namespace IOUtils {
  /**
   * The async shutdown client for the profile-before-change shutdown phase.
   */
  [Throws]
  readonly attribute any profileBeforeChange;

  /**
   * The async shutdown client for the profile-before-change-telemetry shutdown
   * phase.
   *
   * ONLY telemetry should register blockers on this client.
   */
  [Throws]
  readonly attribute any sendTelemetry;
};

[Exposed=Worker]
partial namespace IOUtils {
  /**
   * Synchronously opens the file at |path|. This API is only available in workers.
   *
   * @param path An absolute file path.
   *
   * @return A |SyncReadFile| object for the file.
   */
  [Throws]
  SyncReadFile openFileForSyncReading(DOMString path);

#ifdef XP_UNIX
  /**
   * Launch a child process; uses `base::LaunchApp` from IPC.  (This WebIDL
   * binding is currently Unix-only; it could also be supported on Windows
   * but it would use u16-based strings, so it would basically be a separate
   * copy of the bindings.)
   *
   * This interface was added for use by `Subprocess.sys.jsm`; other would-be
   * callers may want to just use Subprocess instead of calling this directly.
   *
   * @param argv The command to run and its arguments.
   * @param options Various parameters about how the child process is launched
   *                and its initial environment.
   *
   * @return The process ID.  Note that various errors (e.g., the
   *         executable to be launched doesn't exist) may not be
   *         encountered until after the process is created, so a
   *         successful return doesn't necessarily imply a successful
   *         launch.
   */
  [Throws]
  unsigned long launchProcess(sequence<UnixString> argv, LaunchOptions options);
#endif
};

/**
 * An object representing an open file, allowing parts of the file contents to be
 * read synchronously. Only available in workers.
 */
[ChromeOnly, Exposed=Worker]
interface SyncReadFile {
  /**
   * The file size, in bytes.
   */
  readonly attribute long long size;

  /**
   * Synchronously read |dest.length| bytes at offset |offset| into |dest|.
   * Throws if the file has been closed already or if the read would be out-of-bounds.
   *
   * @param dest   A Uint8Array whose entire contents will be overwritten with
   *               bytes read from the file.
   * @param offset The file offset at which the read range begins. (The length of the
   *               range is given by |dest.length|.)
   */
  [Throws]
  undefined readBytesInto(Uint8Array dest, long long offset);

  /**
   * Close the file. Subsequent calls to readBytesInto will throw.
   * If the file is not closed manually, it will be closed once this object is GC'ed.
   */
  undefined close();
};

/**
 * Options to be passed to the |IOUtils.readUTF8| method.
 */
dictionary ReadUTF8Options {
  /**
   * If true, this option indicates that the file to be read is compressed with
   * LZ4-encoding, and should be decompressed before the data is returned to
   * the caller.
   */
  boolean decompress = false;
};

/**
 * Options to be passed to the |IOUtils.read| method.
 */
dictionary ReadOptions : ReadUTF8Options {
  /**
   * The offset into the file to read from. If unspecified, the file will be read
   * from the start.
   */
  unsigned long long offset = 0;

  /**
   * The max bytes to read from the file at path. If unspecified, the entire
   * file will be read. This option is incompatible with |decompress|.
   */
  unsigned long? maxBytes = null;
};

/**
 * Modes for writing to a file.
 */
enum WriteMode {
  /**
   * Overwrite the contents of the file.
   *
   * The file will be created if it does not exist.
   */
  "overwrite",
  /**
   * Append to the end of the file.
   *
   * This mode will refuse to create the file if it does not exist.
   */
  "append",
  /**
   * Append to the end of the file, or create it if it does not exist.
   */
  "appendOrCreate",
  /**
   * Create a new file.
   *
   * This mode will refuse to overwrite an existing file.
   */
  "create",
};

/**
 * Options to be passed to the |IOUtils.write| and |writeUTF8|
 * methods.
 */
dictionary WriteOptions {
  /**
   * If specified, backup the destination file to this path before writing.
   */
  DOMString backupFile;
  /**
   * If specified, write the data to a file at |tmpPath| instead of directly to
   * the destination. Once the write is complete, the destination will be
   * overwritten by a move. Specifying this option will make the write a little
   * slower, but also safer.
   */
  DOMString tmpPath;
  /**
   * The mode used to write to the file.
   */
  WriteMode mode = "overwrite";
  /**
   * If true, force the OS to write its internal buffers to the disk.
   * This is considerably slower for the whole system, but safer in case of
   * an improper system shutdown (e.g. due to a kernel panic) or device
   * disconnection before the buffers are flushed.
   */
  boolean flush = false;
  /**
   * If true, compress the data with LZ4-encoding before writing to the file.
   */
  boolean compress = false;
};

/**
 * Options to be passed to the |IOUtils.move| method.
 */
dictionary MoveOptions {
  /**
   * If true, fail if the destination already exists.
   */
  boolean noOverwrite = false;
};

/**
 * Options to be passed to the |IOUtils.remove| method.
 */
dictionary RemoveOptions {
  /**
   * If true, no error will be reported if the target file is missing.
   */
  boolean ignoreAbsent = true;
  /**
   * If true, and the target is a directory, recursively remove files.
   */
  boolean recursive = false;

  /**
   * If true, a failed delete on a readonly file will be retried by first
   * removing the readonly attribute.
   *
   * Only has an effect on Windows.
   */
  boolean retryReadonly = false;
};

/**
 * Options to be passed to the |IOUtils.makeDirectory| method.
 */
dictionary MakeDirectoryOptions {
  /**
   * If true, create the directory and all necessary ancestors if they do not
   * already exist. If false and any ancestor directories do not exist,
   * |makeDirectory| will reject with an error.
   */
  boolean createAncestors = true;
  /**
   * If true, succeed even if the directory already exists (default behavior).
   * Otherwise, fail if the directory already exists.
   */
  boolean ignoreExisting = true;
  /**
   * The file mode to create the directory with.
   *
   * This is ignored on Windows.
   */
  unsigned long permissions = 0755;

};

/**
 * Options to be passed to the |IOUtils.copy| method.
 */
dictionary CopyOptions {
  /**
   * If true, fail if the destination already exists.
   */
  boolean noOverwrite = false;
  /**
   * If true, copy the source recursively.
   */
  boolean recursive = false;
};

/**
 * Options to be passed to the |IOUtils.getChildren| method.
 */
dictionary GetChildrenOptions {
  /**
   * If true, no error will be reported if the target file is missing.
   */
  boolean ignoreAbsent = false;
};

/**
 * Types of files that are recognized by the |IOUtils.stat| method.
 */
enum FileType { "regular", "directory", "other" };

/**
 * Basic metadata about a file.
 */
dictionary FileInfo {
  /**
   * The absolute path to the file on disk, as known when this file info was
   * obtained.
   */
  DOMString path;

  /**
   * Identifies if the file at |path| is a regular file, directory, or something
   * something else.
   */
  FileType type;

  /**
   * If this represents a regular file, the size of the file in bytes.
   * Otherwise, -1.
   */
  long long size;

  /**
   * The timestamp of file creation, represented in milliseconds since Epoch
   * (1970-01-01T00:00:00.000Z).
   *
   * This is only available on MacOS and Windows.
   */
  long long creationTime;

  /**
   * The timestmp of last file accesss, represented in milliseconds since Epoch
   * (1970-01-01T00:00:00.000Z).
   */
  long long lastAccessed;

  /**
   * The timestamp of the last file modification, represented in milliseconds
   * since Epoch (1970-01-01T00:00:00.000Z).
   */
  long long lastModified;

  /**
   * The permissions of the file, expressed as a UNIX file mode.
   *
   * NB: Windows does not make a distinction between user, group, and other
   * permissions like UNICES do. The user, group, and other parts will always
   * be identical on Windows.
   */
  unsigned long permissions;
};

/**
 * The supported hash algorithms for |IOUtils.hashFile|.
 */
enum HashAlgorithm { "sha256", "sha384", "sha512" };

#ifdef XP_WIN
/**
 * Windows-specific file attributes.
 */
dictionary WindowsFileAttributes {
  /**
   * Whether or not the file is read-only.
   */
  boolean readOnly;
  /**
   * Whether or not the file is hidden.
   */
  boolean hidden;
  /**
   * Whether or not the file is classified as a system file.
   */
  boolean system;
};
#endif

#ifdef XP_UNIX
/**
 * Used where the POSIX API allows an arbitrary byte string but in
 * practice it's usually UTF-8, so JS strings are accepted for
 * convenience.
 */
typedef (UTF8String or Uint8Array) UnixString;

/**
 * Options for the `launchApp` method.  See also `base::LaunchOptions`
 * in C++.
 */
dictionary LaunchOptions {
  /**
   * The environment variables, as a sequence of `NAME=value` strings.
   * (The underlying C++ code can also inherit the current environment
   * with optional changes; that feature could be added here if needed.)
   */
  required sequence<UnixString> environment;

  /**
   * The initial current working directory.
   */
  UnixString workdir;

  /**
   * File descriptors to pass to the child process.  Any fds not
   * mentioned here, other than stdin/out/err, will not be inherited
   * even if they aren't marked close-on-exec.
   */
  sequence<FdMapping> fdMap;

  /**
   * On macOS 10.14+, disclaims responsibility for the child process
   * with respect to privacy/security permission prompts and
   * decisions.  Ignored if not supported by the OS.
   */
  boolean disclaim = false;
};

/**
 * Describes a file descriptor to give to the child process.
 */
dictionary FdMapping {
  /**
   * The fd in the parent process to pass.  This must remain open during
   * the call to `launchApp` but can be closed after it returns (or throws).
   */
  required unsigned long src;

  /**
   * The fd number to map it to in the child process.
   */
  required unsigned long dst;
};
#endif