// 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.

[DartPackage="mojo_services"]
module mojo.files;

// Error codes used by the file manager.
// TODO(vtl): Add more (to, e.g., cover all of errno).
enum Error {
  OK = 0,
  UNKNOWN,
  INVALID_ARGUMENT,
  PERMISSION_DENIED,
  OUT_OF_RANGE,
  UNIMPLEMENTED,
  CLOSED,
  UNAVAILABLE,
  INTERNAL,
};

// Used to explain the meaning of an offset within a file.
enum Whence {
  // Offset is from current position in the file.
  FROM_CURRENT = 0,
  // Offset is relative to the beginning of the file.
  FROM_START,
  // Offset is relative to the end of the file.
  FROM_END,
};

// Describes (idealized) wall-clock time, since Unix epoch (i.e., since
// "1970-01-01 00:00 UTC", ignoring leap seconds and that UTC as we know it
// started in 1972).
// TODO(vtl): Should probably be moved out of mojo.files (maybe to mojo.time?).
struct Timespec {
  int64 seconds;
  int32 nanoseconds;  // Always in the interval [0, 10^9).
};

// Used for |Touch()| calls. If |now| is set, |timespec| must be null (the time
// "now" will be used). Otherwise, |timespec| must not be null.
// TODO(vtl): Use a union instead, when that becomes possible.
struct TimespecOrNow {
  bool now;
  Timespec? timespec;
};

// Describes various information about a file or directory (for |Stat()|). Note
// that access/modification times may be set arbitrarily (by those with
// appropriate capabilities) and may not reflect reality.
struct FileInformation {
  // Type of the file.
  FileType type;
  // Size of the file, in bytes. Zero for directories.
  int64 size;
  // Last access time, if available/supported.
  Timespec? atime;
  // Last modification time, if available/supported.
  Timespec? mtime;
};

// File and directory open flags (at least one of |kOpenFlagRead| and
// |kOpenFlagWrite| is required):
// Opens the file/directory for reading.
const uint32 kOpenFlagRead = 0x1;
// Opens the file/directory for writing.
const uint32 kOpenFlagWrite = 0x2;
// Only meaningful together with |kOpenFlagWrite|: creates the file if
// necessary.
const uint32 kOpenFlagCreate = 0x4;
// Only meaningful together with |kOpenFlagCreate|: requires file/directory to
// be created, failing if it already exists.
const uint32 kOpenFlagExclusive = 0x8;
// Only meaningful for files, together with |kOpenFlagWrite|: writes will always
// append to the file.
const uint32 kOpenFlagAppend = 0x10;
// Only meaningful for files, together with |kOpenFlagWrite|: truncates the
// file.
const uint32 kOpenFlagTruncate = 0x20;

// File types.
enum FileType {
  UNKNOWN = 0,
  REGULAR_FILE,
  DIRECTORY,
};

// Describes a directory entry (i.e., a single member of a directory).
struct DirectoryEntry {
  FileType type;
  string name;
};

// Deletion flags:
// Only delete if the path refers to a file/non-directory (by default, will
// delete files and directories).
const uint32 kDeleteFlagFileOnly = 0x1;
// Only delete if the path refers to a directory.
const uint32 kDeleteFlagDirectoryOnly = 0x2;
// Recursively delete (neither of the two flags above may be specified).
const uint32 kDeleteFlagRecursive = 0x4;