components/filesystem/public/interfaces/file.mojom

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // TODO(vtl): notes to self:
   6 //  - file offsets, file positions, and file sizes are int64 (though positions
   7 //    and sizes must always be non-negative)
   8 //  - buffer size parameters (for read/write) are uint32
   9
  10 module filesystem;
  11
  12 import "components/filesystem/public/interfaces/types.mojom";
  13
  14 // TODO(vtl): Write comments.
  15 interface File {
  16   // Flushes/closes this file; no operations may be performed on this file after
  17   // this. Note that any error code is strictly informational -- the close may
  18   // not be retried.
  19   Close() => (FileError err);
  20
  21   // Reads (at most) |num_bytes_to_read| from the location specified by
  22   // |offset|/|whence|. On success, |bytes_read| is set to the data read.
  23   // TODO(vtl): Define/clarify behavior when less than |num_bytes_to_read| bytes
  24   // are read.
  25   // TODO(vtl): Clarify when (for what values of |offset|/|whence|) this
  26   // modifies the file position. Or maybe there should be a flag?
  27   Read(uint32 num_bytes_to_read, int64 offset, Whence whence)
  28       => (FileError error, array<uint8>? bytes_read);
  29
  30   // Writes |bytes_to_write| to the location specified by |offset|/|whence|.
  31   // TODO(vtl): Clarify behavior when |num_bytes_written| is less than the size
  32   // of |bytes_to_write|.
  33   Write(array<uint8> bytes_to_write, int64 offset, Whence whence)
  34       => (FileError error, uint32 num_bytes_written);
  35
  36   // Gets the current file position. On success, |position| is the current
  37   // offset (in bytes) from the beginning of the file).
  38   Tell() => (FileError error, int64 position);
  39
  40   // Sets the current file position to that specified by |offset|/|whence|. On
  41   // success, |position| is the offset (in bytes) from the beginning of the
  42   // file.
  43   Seek(int64 offset, Whence whence) => (FileError error, int64 position);
  44
  45   // Gets information about this file. On success, |file_information| is
  46   // non-null and will contain this information.
  47   Stat() => (FileError error, FileInformation? file_information);
  48
  49   // Truncates this file to the size specified by |size| (in bytes).
  50   Truncate(int64 size) => (FileError error);
  51
  52   // Updates this file's atime and/or mtime to the time specified by |atime| (or
  53   // |mtime|, respectively), which may also indicate "now". If |atime| or
  54   // |mtime| is null, then the corresponding time is not modified.
  55   Touch(TimespecOrNow? atime, TimespecOrNow? mtime) => (FileError error);
  56
  57   // Creates a new |File| instance, which shares the same "file description".
  58   // I.e., the access mode, etc. (as specified to |Directory::OpenFile()| by the
  59   // |open_flags| argument) as well as file position.
  60   Dup(File& file) => (FileError error);
  61
  62   // Syncs data to disk.
  63   Flush() => (FileError error);
  64
  65   // Returns a handle to the file for raw access.
  66   AsHandle() => (FileError error, handle file_handle);
  67 };