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