// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module filesystem.mojom;

import "components/filesystem/public/interfaces/file.mojom";
import "components/filesystem/public/interfaces/types.mojom";
import "mojo/common/file.mojom";

struct FileOpenDetails {
  string path;
  uint32 open_flags;
};

struct FileOpenResult {
  string path;
  FileError error;
  mojo.common.mojom.File? file_handle;
};

// This interface provides access to a directory in a "file system", providing
// operations such as creating/opening/removing/renaming files/directories
// within it. Note that all relative |path| arguments are relative to "this"
// directory (i.e., "this" directory functions as the current working directory
// for the various operations).
// TODO(vtl): Paths may be relative; should they allowed to be absolute?
// (Currently not.)
interface Directory {
  // Operations about "this" |Directory|:

  // Reads the contents of this directory.
  // TODO(vtl): Clarify error codes versus |directory_contents|.
  [Sync]
  Read() => (FileError error, array<DirectoryEntry>? directory_contents);

  // Operations *in* "this" |Directory|:

  // Opens the file specified by |path| with the given |open_flags|. |file| is
  // optional, mainly for consistency with |OpenDirectory()| (but may be useful,
  // together with |kOpenFlagCreate|, for "touching" a file).
  [Sync]
  OpenFile(string path, File&? file, uint32 open_flags)
      => (FileError error);

  // Opens the file specified by |path| with the given |open_flags|. Returns a
  // native file descriptor wrapped in a MojoHandle.
  [Sync]
  OpenFileHandle(string path, uint32 open_flags)
      => (FileError error, mojo.common.mojom.File? file_handle);

  // Like OpenFileHandle, but opens multiple files.
  [Sync]
  OpenFileHandles(array<FileOpenDetails> files)
      => (array<FileOpenResult> results);

  // Opens the directory specified by |path|. |directory| is optional, so that
  // this may be used as a simple "mkdir()" with |kOpenFlagCreate|.
  [Sync]
  OpenDirectory(string path,
                Directory&? directory,
                uint32 open_flags) => (FileError error);

  // Renames/moves the file/directory given by |path| to |new_path|.
  [Sync]
  Rename(string path, string new_path) => (FileError error);

  // Renames file |path| to |new_path|. Both paths must be on the same volume,
  // or the function will fail. Destination file will be created if it doesn't
  // exist. Prefer this function over Rename when dealing with temporary files.
  // On Windows it preserves attributes of the target file.
  [Sync]
  Replace(string path, string new_path) => (FileError error);

  // Deletes the given path, which may be a file or a directory (see
  // |kDeleteFlag...| for details).
  [Sync]
  Delete(string path, uint32 delete_flags) => (FileError error);

  // Returns true if |path| exists.
  [Sync]
  Exists(string path) => (FileError error, bool exists);

  // Returns true if |path| is writable.
  [Sync]
  IsWritable(string path) => (FileError error, bool is_writable);

  // Opens a file descriptor on this directory and calls
  // fsync()/FlushFileBuffers().
  [Sync]
  Flush() => (FileError error);

  // Gets information about this file. On success, |file_information| is
  // non-null and will contain this information.
  [Sync]
  StatFile(string path) => (FileError error, FileInformation? file_information);

  // Creates a copy of this directory.
  Clone(Directory& directory);

  // Reads the contents of an entire file.
  [Sync]
  ReadEntireFile(string path) => (FileError error, array<uint8> data);

  // Writes |data| to |path|, overwriting the file if it already exists.
  [Sync]
  WriteFile(string path, array<uint8> data) => (FileError error);

  // TODO(vtl): directory "streaming"?
  // TODO(vtl): "make root" (i.e., prevent cd-ing, etc., to parent); note that
  // this would require a much more complicated implementation (e.g., it needs
  // to be "inherited" by OpenDirectory(), and the enforcement needs to be valid
  // even if the opened directory is subsequently moved -- e.g., closer to the
  // "root")
  // TODO(vtl): Add a "watch"?
};