Base: Move platform_file.* to files/file.*

base/files/file.h

 // Copyright (c) 2012 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.
 
-#ifndef BASE_PLATFORM_FILE_H_
-#define BASE_PLATFORM_FILE_H_
+#ifndef BASE_FILES_FILE_H_
+#define BASE_FILES_FILE_H_
 
 #include "build/build_config.h"
 #if defined(OS_WIN)
 #include <windows.h>
 #endif
 
 #include <string>
 
 #include "base/base_export.h"
 #include "base/basictypes.h"
 #include "base/files/file_path.h"
+#include "base/move.h"
 #include "base/time/time.h"
 
+#if defined(OS_WIN)
+#include "base/win/scoped_handle.h"
+#endif
+
 namespace base {
 
-// PLATFORM_FILE_(OPEN|CREATE).* are mutually exclusive. You should specify
-// exactly one of the five (possibly combining with other flags) when opening
-// or creating a file.
-// PLATFORM_FILE_(WRITE|APPEND) are mutually exclusive. This is so that APPEND
-// behavior will be consistent with O_APPEND on POSIX.
-// PLATFORM_FILE_EXCLUSIVE_(READ|WRITE) only grant exclusive access to the file
-// on creation on POSIX; for existing files, consider using LockPlatformFile().
-enum PlatformFileFlags {
-  PLATFORM_FILE_OPEN = 1 << 0,             // Opens a file, only if it exists.
-  PLATFORM_FILE_CREATE = 1 << 1,           // Creates a new file, only if it
-                                           // does not already exist.
-  PLATFORM_FILE_OPEN_ALWAYS = 1 << 2,      // May create a new file.
-  PLATFORM_FILE_CREATE_ALWAYS = 1 << 3,    // May overwrite an old file.
-  PLATFORM_FILE_OPEN_TRUNCATED = 1 << 4,   // Opens a file and truncates it,
-                                           // only if it exists.
-  PLATFORM_FILE_READ = 1 << 5,
-  PLATFORM_FILE_WRITE = 1 << 6,
-  PLATFORM_FILE_APPEND = 1 << 7,
-  PLATFORM_FILE_EXCLUSIVE_READ = 1 << 8,   // EXCLUSIVE is opposite of Windows
-                                           // SHARE
-  PLATFORM_FILE_EXCLUSIVE_WRITE = 1 << 9,
-  PLATFORM_FILE_ASYNC = 1 << 10,
-  PLATFORM_FILE_TEMPORARY = 1 << 11,       // Used on Windows only
-  PLATFORM_FILE_HIDDEN = 1 << 12,          // Used on Windows only
-  PLATFORM_FILE_DELETE_ON_CLOSE = 1 << 13,
-
-  PLATFORM_FILE_WRITE_ATTRIBUTES = 1 << 14,  // Used on Windows only
-
-  PLATFORM_FILE_SHARE_DELETE = 1 << 15,      // Used on Windows only
-
-  PLATFORM_FILE_TERMINAL_DEVICE = 1 << 16,   // Serial port flags
-  PLATFORM_FILE_BACKUP_SEMANTICS = 1 << 17,  // Used on Windows only
-
-  PLATFORM_FILE_EXECUTE = 1 << 18,           // Used on Windows only
-};
-
-// This enum has been recorded in multiple histograms. If the order of the
-// fields needs to change, please ensure that those histograms are obsolete or
-// have been moved to a different enum.
-//
-// PLATFORM_FILE_ERROR_ACCESS_DENIED is returned when a call fails because of
-// a filesystem restriction. PLATFORM_FILE_ERROR_SECURITY is returned when a
-// browser policy doesn't allow the operation to be executed.
-enum PlatformFileError {
-  PLATFORM_FILE_OK = 0,
-  PLATFORM_FILE_ERROR_FAILED = -1,
-  PLATFORM_FILE_ERROR_IN_USE = -2,
-  PLATFORM_FILE_ERROR_EXISTS = -3,
-  PLATFORM_FILE_ERROR_NOT_FOUND = -4,
-  PLATFORM_FILE_ERROR_ACCESS_DENIED = -5,
-  PLATFORM_FILE_ERROR_TOO_MANY_OPENED = -6,
-  PLATFORM_FILE_ERROR_NO_MEMORY = -7,
-  PLATFORM_FILE_ERROR_NO_SPACE = -8,
-  PLATFORM_FILE_ERROR_NOT_A_DIRECTORY = -9,
-  PLATFORM_FILE_ERROR_INVALID_OPERATION = -10,
-  PLATFORM_FILE_ERROR_SECURITY = -11,
-  PLATFORM_FILE_ERROR_ABORT = -12,
-  PLATFORM_FILE_ERROR_NOT_A_FILE = -13,
-  PLATFORM_FILE_ERROR_NOT_EMPTY = -14,
-  PLATFORM_FILE_ERROR_INVALID_URL = -15,
-  PLATFORM_FILE_ERROR_IO = -16,
-  // Put new entries here and increment PLATFORM_FILE_ERROR_MAX.
-  PLATFORM_FILE_ERROR_MAX = -17
-};
-
-// This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux.
-enum PlatformFileWhence {
-  PLATFORM_FILE_FROM_BEGIN   = 0,
-  PLATFORM_FILE_FROM_CURRENT = 1,
-  PLATFORM_FILE_FROM_END     = 2
-};
-
-// Used to hold information about a given file.
-// If you add more fields to this structure (platform-specific fields are OK),
-// make sure to update all functions that use it in file_util_{win|posix}.cc
-// too, and the ParamTraits<base::PlatformFileInfo> implementation in
-// chrome/common/common_param_traits.cc.
-struct BASE_EXPORT PlatformFileInfo {
-  PlatformFileInfo();
-  ~PlatformFileInfo();
-
-  // The size of the file in bytes.  Undefined when is_directory is true.
-  int64 size;
-
-  // True if the file corresponds to a directory.
-  bool is_directory;
-
-  // True if the file corresponds to a symbolic link.
-  bool is_symbolic_link;
-
-  // The last modified time of a file.
-  base::Time last_modified;
-
-  // The last accessed time of a file.
-  base::Time last_accessed;
-
-  // The creation time of a file.
-  base::Time creation_time;
-};
-
 #if defined(OS_WIN)
 typedef HANDLE PlatformFile;
-const PlatformFile kInvalidPlatformFileValue = INVALID_HANDLE_VALUE;
-BASE_EXPORT PlatformFileError LastErrorToPlatformFileError(DWORD last_error);
 #elif defined(OS_POSIX)
 typedef int PlatformFile;
-const PlatformFile kInvalidPlatformFileValue = -1;
-BASE_EXPORT PlatformFileError ErrnoToPlatformFileError(int saved_errno);
-#endif
-
-// Creates or opens the given file. If |created| is provided, it will be set to
-// true if a new file was created [or an old one truncated to zero length to
-// simulate a new file, which can happen with PLATFORM_FILE_CREATE_ALWAYS], and
-// false otherwise.  |error| can be NULL.
+#endif
+
+
+// Thin wrapper around an OS-level file.
+// Note that this class does not provide any support for asynchronous IO, other
+// than the ability to create asynchronous handles on Windows.
 //
-// This function fails with 'access denied' if the |name| contains path
-// traversal ('..') components.
-BASE_EXPORT PlatformFile CreatePlatformFile(const FilePath& name,
-                                            int flags,
-                                            bool* created,
-                                            PlatformFileError* error);
-
-// Same as CreatePlatformFile but allows paths with traversal (like \..\)
-// components. Use only with extreme care.
-BASE_EXPORT PlatformFile CreatePlatformFileUnsafe(const FilePath& name,
-                                                  int flags,
-                                                  bool* created,
-                                                  PlatformFileError* error);
-
-BASE_EXPORT FILE* FdopenPlatformFile(PlatformFile file, const char* mode);
-
-// Closes a file handle. Returns |true| on success and |false| otherwise.
-BASE_EXPORT bool ClosePlatformFile(PlatformFile file);
-
-// Changes current position in the file to an |offset| relative to an origin
-// defined by |whence|. Returns the resultant current position in the file
-// (relative to the start) or -1 in case of error.
-BASE_EXPORT int64 SeekPlatformFile(PlatformFile file,
-                                   PlatformFileWhence whence,
-                                   int64 offset);
-
-// Reads the given number of bytes (or until EOF is reached) starting with the
-// given offset. Returns the number of bytes read, or -1 on error. Note that
-// this function makes a best effort to read all data on all platforms, so it is
-// not intended for stream oriented files but instead for cases when the normal
-// expectation is that actually |size| bytes are read unless there is an error.
-BASE_EXPORT int ReadPlatformFile(PlatformFile file, int64 offset,
-                                 char* data, int size);
-
-// Same as above but without seek.
-BASE_EXPORT int ReadPlatformFileAtCurrentPos(PlatformFile file,
-                                             char* data, int size);
-
-// Reads the given number of bytes (or until EOF is reached) starting with the
-// given offset, but does not make any effort to read all data on all platforms.
-// Returns the number of bytes read, or -1 on error.
-BASE_EXPORT int ReadPlatformFileNoBestEffort(PlatformFile file, int64 offset,
-                                             char* data, int size);
-
-// Same as above but without seek.
-BASE_EXPORT int ReadPlatformFileCurPosNoBestEffort(PlatformFile file,
-                                                   char* data, int size);
-
-// Writes the given buffer into the file at the given offset, overwritting any
-// data that was previously there. Returns the number of bytes written, or -1
-// on error. Note that this function makes a best effort to write all data on
-// all platforms.
-// Ignores the offset and writes to the end of the file if the file was opened
-// with PLATFORM_FILE_APPEND.
-BASE_EXPORT int WritePlatformFile(PlatformFile file, int64 offset,
-                                  const char* data, int size);
-
-// Save as above but without seek.
-BASE_EXPORT int WritePlatformFileAtCurrentPos(PlatformFile file,
-                                              const char* data, int size);
-
-// Save as above but does not make any effort to write all data on all
-// platforms. Returns the number of bytes written, or -1 on error.
-BASE_EXPORT int WritePlatformFileCurPosNoBestEffort(PlatformFile file,
-                                                    const char* data, int size);
-
-// Truncates the given file to the given length. If |length| is greater than
-// the current size of the file, the file is extended with zeros. If the file
-// doesn't exist, |false| is returned.
-BASE_EXPORT bool TruncatePlatformFile(PlatformFile file, int64 length);
-
-// Flushes the buffers of the given file.
-BASE_EXPORT bool FlushPlatformFile(PlatformFile file);
-
-// Touches the given file.
-BASE_EXPORT bool TouchPlatformFile(PlatformFile file,
-                                   const Time& last_access_time,
-                                   const Time& last_modified_time);
-
-// Returns some information for the given file.
-BASE_EXPORT bool GetPlatformFileInfo(PlatformFile file, PlatformFileInfo* info);
-
-// Attempts to take an exclusive write lock on the file. Returns immediately
-// (i.e. does not wait for another process to unlock the file). If the lock
-// was obtained, the result will be PLATFORM_FILE_OK. A lock only guarantees
-// that other processes may not also take a lock on the same file with the
-// same API - it may still be opened, renamed, unlinked, etc.
-//
-// Common semantics:
-//  * Locks are held by processes, but not inherited by child processes.
-//  * Locks are released by the OS on file handle close or process termination.
-//  * Locks are reliable only on local filesystems.
-//  * Duplicated file handles may also write to locked files.
-// Windows-specific semantics:
-//  * Locks are mandatory for read/write APIs, advisory for mapping APIs.
-//  * Within a process, locking the same file (by the same or new handle)
-//    will fail.
-// POSIX-specific semantics:
-//  * Locks are advisory only.
-//  * Within a process, locking the same file (by the same or new handle)
-//    will succeed.
-//  * Closing any descriptor on a given file releases the lock.
-BASE_EXPORT PlatformFileError LockPlatformFile(PlatformFile file);
-
-// Unlock a file previously locked with LockPlatformFile.
-BASE_EXPORT PlatformFileError UnlockPlatformFile(PlatformFile file);
-
-// Use this class to pass ownership of a PlatformFile to a receiver that may or
-// may not want to accept it.  This class does not own the storage for the
-// PlatformFile.
-//
-// EXAMPLE:
-//
-//  void MaybeProcessFile(PassPlatformFile pass_file) {
-//    if (...) {
-//      PlatformFile file = pass_file.ReleaseValue();
-//      // Now, we are responsible for closing |file|.
-//    }
-//  }
-//
-//  void OpenAndMaybeProcessFile(const FilePath& path) {
-//    PlatformFile file = CreatePlatformFile(path, ...);
-//    MaybeProcessFile(PassPlatformFile(&file));
-//    if (file != kInvalidPlatformFileValue)
-//      ClosePlatformFile(file);
-//  }
-//
-class BASE_EXPORT PassPlatformFile {
+// Note about const: this class does not attempt to determine if the underlying
+// file system object is affected by a particular method in order to consider
+// that method const or not. Only methods that deal with member variables in an
+// obvious non-modifying way are marked as const. Any method that forward calls
+// to the OS is not considered const, even if there is no apparent change to
+// member variables.
+class BASE_EXPORT File {
+  MOVE_ONLY_TYPE_FOR_CPP_03(File, RValue)
+
  public:
-  explicit PassPlatformFile(PlatformFile* value) : value_(value) {
-  }
-
-  // Called to retrieve the PlatformFile stored in this object.  The caller
-  // gains ownership of the PlatformFile and is now responsible for closing it.
-  // Any subsequent calls to this method will return an invalid PlatformFile.
-  PlatformFile ReleaseValue() {
-    PlatformFile temp = *value_;
-    *value_ = kInvalidPlatformFileValue;
-    return temp;
-  }
+  // FLAG_(OPEN|CREATE).* are mutually exclusive. You should specify exactly one
+  // of the five (possibly combining with other flags) when opening or creating
+  // a file.
+  // FLAG_(WRITE|APPEND) are mutually exclusive. This is so that APPEND behavior
+  // will be consistent with O_APPEND on POSIX.
+  // FLAG_EXCLUSIVE_(READ|WRITE) only grant exclusive access to the file on
+  // creation on POSIX; for existing files, consider using Lock().
+  enum Flags {
+    FLAG_OPEN = 1 << 0,             // Opens a file, only if it exists.
+    FLAG_CREATE = 1 << 1,           // Creates a new file, only if it does not
+                                    // already exist.
+    FLAG_OPEN_ALWAYS = 1 << 2,      // May create a new file.
+    FLAG_CREATE_ALWAYS = 1 << 3,    // May overwrite an old file.
+    FLAG_OPEN_TRUNCATED = 1 << 4,   // Opens a file and truncates it, only if it
+                                    // exists.
+    FLAG_READ = 1 << 5,
+    FLAG_WRITE = 1 << 6,
+    FLAG_APPEND = 1 << 7,
+    FLAG_EXCLUSIVE_READ = 1 << 8,   // EXCLUSIVE is opposite of Windows SHARE.
+    FLAG_EXCLUSIVE_WRITE = 1 << 9,
+    FLAG_ASYNC = 1 << 10,
+    FLAG_TEMPORARY = 1 << 11,       // Used on Windows only.
+    FLAG_HIDDEN = 1 << 12,          // Used on Windows only.
+    FLAG_DELETE_ON_CLOSE = 1 << 13,
+    FLAG_WRITE_ATTRIBUTES = 1 << 14,  // Used on Windows only.
+    FLAG_SHARE_DELETE = 1 << 15,      // Used on Windows only.
+    FLAG_TERMINAL_DEVICE = 1 << 16,   // Serial port flags.
+    FLAG_BACKUP_SEMANTICS = 1 << 17,  // Used on Windows only.
+    FLAG_EXECUTE = 1 << 18,           // Used on Windows only.
+  };
+
+  // This enum has been recorded in multiple histograms. If the order of the
+  // fields needs to change, please ensure that those histograms are obsolete or
+  // have been moved to a different enum.
+  //
+  // FILE_ERROR_ACCESS_DENIED is returned when a call fails because of a
+  // filesystem restriction. FILE_ERROR_SECURITY is returned when a browser
+  // policy doesn't allow the operation to be executed.
+  enum Error {
+    FILE_OK = 0,
+    FILE_ERROR_FAILED = -1,
+    FILE_ERROR_IN_USE = -2,
+    FILE_ERROR_EXISTS = -3,
+    FILE_ERROR_NOT_FOUND = -4,
+    FILE_ERROR_ACCESS_DENIED = -5,
+    FILE_ERROR_TOO_MANY_OPENED = -6,
+    FILE_ERROR_NO_MEMORY = -7,
+    FILE_ERROR_NO_SPACE = -8,
+    FILE_ERROR_NOT_A_DIRECTORY = -9,
+    FILE_ERROR_INVALID_OPERATION = -10,
+    FILE_ERROR_SECURITY = -11,
+    FILE_ERROR_ABORT = -12,
+    FILE_ERROR_NOT_A_FILE = -13,
+    FILE_ERROR_NOT_EMPTY = -14,
+    FILE_ERROR_INVALID_URL = -15,
+    FILE_ERROR_IO = -16,
+    // Put new entries here and increment FILE_ERROR_MAX.
+    FILE_ERROR_MAX = -17
+  };
+
+  // This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux.
+  enum Whence {
+    FROM_BEGIN   = 0,
+    FROM_CURRENT = 1,
+    FROM_END     = 2
+  };
+
+  // Used to hold information about a given file.
+  // If you add more fields to this structure (platform-specific fields are OK),
+  // make sure to update all functions that use it in file_util_{win|posix}.cc
+  // too, and the ParamTraits<base::PlatformFileInfo> implementation in
+  // chrome/common/common_param_traits.cc.
+  struct BASE_EXPORT Info {
+    Info();
+    ~Info();
+
+    // The size of the file in bytes.  Undefined when is_directory is true.
+    int64 size;
+
+    // True if the file corresponds to a directory.
+    bool is_directory;
+
+    // True if the file corresponds to a symbolic link.
+    bool is_symbolic_link;
+
+    // The last modified time of a file.
+    base::Time last_modified;
+
+    // The last accessed time of a file.
+    base::Time last_accessed;
+
+    // The creation time of a file.
+    base::Time creation_time;
+  };
+
+  File();
+
+  // Creates or opens the given file. This will fail with 'access denied' if the
+  // |name| contains path traversal ('..') components.
+  File(const FilePath& name, uint32 flags);
+
+  // Takes ownership of |platform_file|.
+  explicit File(PlatformFile platform_file);
+
+  // Move constructor for C++03 move emulation of this type.
+  File(RValue other);
+
+  ~File();
+
+  // Move operator= for C++03 move emulation of this type.
+  File& operator=(RValue other);
+
+  // Creates or opens the given file, allowing paths with traversal ('..')
+  // components. Use only with extreme care.
+  void CreateBaseFileUnsafe(const FilePath& name, uint32 flags);
+
+  bool IsValid() const;
+
+  // Returns true if a new file was created (or an old one truncated to zero
+  // length to simulate a new file, which can happen with
+  // FLAG_CREATE_ALWAYS), and false otherwise.
+  bool created() const { return created_; }
+
+  // Returns the OS result of opening this file.
+  Error error() const { return error_; }

[Nico, 2014/01/08 03:28:38]

This looks like an error-prone api. Quick, what does this do:

  File my_file = ...;
  if (my_file.error()) {
    // Do stuff here.
  }

Turns out that "Do stuff here" is executed if there's NO error, since error()
returns an Error, not a bool, and enum value 0, the false value is FILE_OK.

This method needs to be renamed. (error_code() or something)

[rvargas (doing something else), 2014/01/08 03:42:08]

yeah... that is an incorrect pattern no mater what error() is named, as the
thing to check is not the error code but the state of the object itself:

File my_file(...);
if (my_file.IsValid()) {
  // do something
}

This method is just a way for _really_ interested parties to find out what
happened, and it only refers to opening the file, not to further operations
(Read etc).

I'm open to suggestions of how to express that directly on the name :)

+
+  PlatformFile GetPlatformFile() const { return file_; }
+  PlatformFile TakePlatformFile();
+
+  // Destroying this object closes the file automatically.
+  void Close();
+
+  // Changes current position in the file to an |offset| relative to an origin
+  // defined by |whence|. Returns the resultant current position in the file
+  // (relative to the start) or -1 in case of error.
+  int64 Seek(Whence whence, int64 offset);
+
+  // Reads the given number of bytes (or until EOF is reached) starting with the
+  // given offset. Returns the number of bytes read, or -1 on error. Note that
+  // this function makes a best effort to read all data on all platforms, so it
+  // is not intended for stream oriented files but instead for cases when the
+  // normal expectation is that actually |size| bytes are read unless there is
+  // an error.
+  int Read(int64 offset, char* data, int size);
+
+  // Same as above but without seek.
+  int ReadAtCurrentPos(char* data, int size);
+
+  // Reads the given number of bytes (or until EOF is reached) starting with the
+  // given offset, but does not make any effort to read all data on all
+  // platforms. Returns the number of bytes read, or -1 on error.
+  int ReadNoBestEffort(int64 offset, char* data, int size);
+
+  // Same as above but without seek.
+  int ReadAtCurrentPosNoBestEffort(char* data, int size);
+
+  // Writes the given buffer into the file at the given offset, overwritting any
+  // data that was previously there. Returns the number of bytes written, or -1
+  // on error. Note that this function makes a best effort to write all data on
+  // all platforms.
+  // Ignores the offset and writes to the end of the file if the file was opened
+  // with FLAG_APPEND.
+  int Write(int64 offset, const char* data, int size);
+
+  // Save as above but without seek.
+  int WriteAtCurrentPos(const char* data, int size);
+
+  // Save as above but does not make any effort to write all data on all
+  // platforms. Returns the number of bytes written, or -1 on error.
+  int WriteAtCurrentPosNoBestEffort(const char* data, int size);
+
+  // Truncates the file to the given length. If |length| is greater than the
+  // current size of the file, the file is extended with zeros. If the file
+  // doesn't exist, |false| is returned.
+  bool Truncate(int64 length);
+
+  // Flushes the buffers.
+  bool Flush();
+
+  // Updates the file times.
+  bool SetTimes(Time last_access_time, Time last_modified_time);
+
+  // Returns some basic information for the given file.
+  bool GetInfo(Info* info);
+
+  // Attempts to take an exclusive write lock on the file. Returns immediately
+  // (i.e. does not wait for another process to unlock the file). If the lock
+  // was obtained, the result will be FILE_OK. A lock only guarantees
+  // that other processes may not also take a lock on the same file with the
+  // same API - it may still be opened, renamed, unlinked, etc.
+  //
+  // Common semantics:
+  //  * Locks are held by processes, but not inherited by child processes.
+  //  * Locks are released by the OS on file close or process termination.
+  //  * Locks are reliable only on local filesystems.
+  //  * Duplicated file handles may also write to locked files.
+  // Windows-specific semantics:
+  //  * Locks are mandatory for read/write APIs, advisory for mapping APIs.
+  //  * Within a process, locking the same file (by the same or new handle)
+  //    will fail.
+  // POSIX-specific semantics:
+  //  * Locks are advisory only.
+  //  * Within a process, locking the same file (by the same or new handle)
+  //    will succeed.
+  //  * Closing any descriptor on a given file releases the lock.
+  Error Lock();
+
+  // Unlock a file previously locked.
+  Error Unlock();
+
+#if defined(OS_WIN)
+  static Error OSErrorToFileError(DWORD last_error);
+#elif defined(OS_POSIX)
+  static Error OSErrorToFileError(int saved_errno);
+#endif
 
  private:
-  PlatformFile* value_;
+  void SetPlatformFile(PlatformFile file);
+
+#if defined(OS_WIN)
+  win::ScopedHandle file_;
+#elif defined(OS_POSIX)
+  PlatformFile file_;
+#endif
+
+  Error error_;
+  bool created_;
+  bool async_;
 };
 
 }  // namespace base
 
-#endif  // BASE_PLATFORM_FILE_H_
+#endif  // BASE_FILES_FILE_H_