1 // Copyright (c) 2011 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 #ifndef BASE_PLATFORM_FILE_H_ 6 #define BASE_PLATFORM_FILE_H_ 7 #pragma once 8 9 #include "build/build_config.h" 10 #if defined(OS_WIN) 11 #include <windows.h> 12 #endif 13 14 #include <string> 15 16 #include "base/base_api.h" 17 #include "base/basictypes.h" 18 #include "base/file_path.h" 19 #include "base/time.h" 20 21 namespace base { 22 23 #if defined(OS_WIN) 24 typedef HANDLE PlatformFile; 25 const PlatformFile kInvalidPlatformFileValue = INVALID_HANDLE_VALUE; 26 #elif defined(OS_POSIX) 27 typedef int PlatformFile; 28 const PlatformFile kInvalidPlatformFileValue = -1; 29 #endif 30 31 enum PlatformFileFlags { 32 PLATFORM_FILE_OPEN = 1, 33 PLATFORM_FILE_CREATE = 2, 34 PLATFORM_FILE_OPEN_ALWAYS = 4, // May create a new file. 35 PLATFORM_FILE_CREATE_ALWAYS = 8, // May overwrite an old file. 36 PLATFORM_FILE_READ = 16, 37 PLATFORM_FILE_WRITE = 32, 38 PLATFORM_FILE_EXCLUSIVE_READ = 64, // EXCLUSIVE is opposite of Windows SHARE 39 PLATFORM_FILE_EXCLUSIVE_WRITE = 128, 40 PLATFORM_FILE_ASYNC = 256, 41 PLATFORM_FILE_TEMPORARY = 512, // Used on Windows only 42 PLATFORM_FILE_HIDDEN = 1024, // Used on Windows only 43 PLATFORM_FILE_DELETE_ON_CLOSE = 2048, 44 PLATFORM_FILE_TRUNCATE = 4096, 45 PLATFORM_FILE_WRITE_ATTRIBUTES = 8192, // Used on Windows only 46 PLATFORM_FILE_ENUMERATE = 16384, // May enumerate directory 47 }; 48 49 // PLATFORM_FILE_ERROR_ACCESS_DENIED is returned when a call fails because of 50 // a filesystem restriction. PLATFORM_FILE_ERROR_SECURITY is returned when a 51 // browser policy doesn't allow the operation to be executed. 52 enum PlatformFileError { 53 PLATFORM_FILE_OK = 0, 54 PLATFORM_FILE_ERROR_FAILED = -1, 55 PLATFORM_FILE_ERROR_IN_USE = -2, 56 PLATFORM_FILE_ERROR_EXISTS = -3, 57 PLATFORM_FILE_ERROR_NOT_FOUND = -4, 58 PLATFORM_FILE_ERROR_ACCESS_DENIED = -5, 59 PLATFORM_FILE_ERROR_TOO_MANY_OPENED = -6, 60 PLATFORM_FILE_ERROR_NO_MEMORY = -7, 61 PLATFORM_FILE_ERROR_NO_SPACE = -8, 62 PLATFORM_FILE_ERROR_NOT_A_DIRECTORY = -9, 63 PLATFORM_FILE_ERROR_INVALID_OPERATION = -10, 64 PLATFORM_FILE_ERROR_SECURITY = -11, 65 PLATFORM_FILE_ERROR_ABORT = -12, 66 PLATFORM_FILE_ERROR_NOT_A_FILE = -13, 67 PLATFORM_FILE_ERROR_NOT_EMPTY = -14, 68 PLATFORM_FILE_ERROR_INVALID_URL = -15, 69 }; 70 71 // Used to hold information about a given file. 72 // If you add more fields to this structure (platform-specific fields are OK), 73 // make sure to update all functions that use it in file_util_{win|posix}.cc 74 // too, and the ParamTraits<base::PlatformFileInfo> implementation in 75 // chrome/common/common_param_traits.cc. 76 struct BASE_API PlatformFileInfo { 77 PlatformFileInfo(); 78 ~PlatformFileInfo(); 79 80 // The size of the file in bytes. Undefined when is_directory is true. 81 int64 size; 82 83 // True if the file corresponds to a directory. 84 bool is_directory; 85 86 // True if the file corresponds to a symbolic link. 87 bool is_symbolic_link; 88 89 // The last modified time of a file. 90 base::Time last_modified; 91 92 // The last accessed time of a file. 93 base::Time last_accessed; 94 95 // The creation time of a file. 96 base::Time creation_time; 97 }; 98 99 // Creates or opens the given file. If PLATFORM_FILE_OPEN_ALWAYS is used, and 100 // |created| is provided, |created| will be set to true if the file was created 101 // or to false in case the file was just opened. |error_code| can be NULL. 102 BASE_API PlatformFile CreatePlatformFile(const FilePath& name, 103 int flags, 104 bool* created, 105 PlatformFileError* error_code); 106 107 // Closes a file handle. Returns |true| on success and |false| otherwise. 108 BASE_API bool ClosePlatformFile(PlatformFile file); 109 110 // Reads the given number of bytes (or until EOF is reached) starting with the 111 // given offset. Returns the number of bytes read, or -1 on error. 112 BASE_API int ReadPlatformFile(PlatformFile file, int64 offset, 113 char* data, int size); 114 115 // Writes the given buffer into the file at the given offset, overwritting any 116 // data that was previously there. Returns the number of bytes written, or -1 117 // on error. 118 BASE_API int WritePlatformFile(PlatformFile file, int64 offset, 119 const char* data, int size); 120 121 // Truncates the given file to the given length. If |length| is greater than 122 // the current size of the file, the file is extended with zeros. If the file 123 // doesn't exist, |false| is returned. 124 BASE_API bool TruncatePlatformFile(PlatformFile file, int64 length); 125 126 // Flushes the buffers of the given file. 127 BASE_API bool FlushPlatformFile(PlatformFile file); 128 129 // Touches the given file. 130 BASE_API bool TouchPlatformFile(PlatformFile file, const Time& last_access_time, 131 const Time& last_modified_time); 132 133 // Returns some information for the given file. 134 BASE_API bool GetPlatformFileInfo(PlatformFile file, PlatformFileInfo* info); 135 136 // Use this class to pass ownership of a PlatformFile to a receiver that may or 137 // may not want to accept it. This class does not own the storage for the 138 // PlatformFile. 139 // 140 // EXAMPLE: 141 // 142 // void MaybeProcessFile(PassPlatformFile pass_file) { 143 // if (...) { 144 // PlatformFile file = pass_file.ReleaseValue(); 145 // // Now, we are responsible for closing |file|. 146 // } 147 // } 148 // 149 // void OpenAndMaybeProcessFile(const FilePath& path) { 150 // PlatformFile file = CreatePlatformFile(path, ...); 151 // MaybeProcessFile(PassPlatformFile(&file)); 152 // if (file != kInvalidPlatformFileValue) 153 // ClosePlatformFile(file); 154 // } 155 // 156 class BASE_API PassPlatformFile { 157 public: 158 explicit PassPlatformFile(PlatformFile* value) : value_(value) { 159 } 160 161 // Called to retrieve the PlatformFile stored in this object. The caller 162 // gains ownership of the PlatformFile and is now responsible for closing it. 163 // Any subsequent calls to this method will return an invalid PlatformFile. 164 PlatformFile ReleaseValue() { 165 PlatformFile temp = *value_; 166 *value_ = kInvalidPlatformFileValue; 167 return temp; 168 } 169 170 private: 171 PlatformFile* value_; 172 }; 173 174 } // namespace base 175 176 #endif // BASE_PLATFORM_FILE_H_ 177
