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 // This file defines FileStream, a basic interface for reading and writing files 6 // synchronously or asynchronously with support for seeking to an offset. 7 // Note that even when used asynchronously, only one operation is supported at 8 // a time. 9 10 #ifndef NET_BASE_FILE_STREAM_H_ 11 #define NET_BASE_FILE_STREAM_H_ 12 #pragma once 13 14 #include "base/memory/scoped_ptr.h" 15 #include "base/platform_file.h" 16 #include "net/base/completion_callback.h" 17 18 class FilePath; 19 20 namespace net { 21 22 // TODO(darin): Move this to a more generic location. 23 // This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux. 24 enum Whence { 25 FROM_BEGIN = 0, 26 FROM_CURRENT = 1, 27 FROM_END = 2 28 }; 29 30 class FileStream { 31 public: 32 FileStream(); 33 34 // Construct a FileStream with an existing file handle and opening flags. 35 // |file| is valid file handle. 36 // |flags| is a bitfield of base::PlatformFileFlags when the file handle was 37 // opened. 38 // The already opened file will not be automatically closed when FileStream 39 // is destructed. 40 FileStream(base::PlatformFile file, int flags); 41 42 ~FileStream(); 43 44 // Call this method to close the FileStream. It is OK to call Close 45 // multiple times. Redundant calls are ignored. 46 // Note that if there are any pending async operations, they'll be aborted. 47 void Close(); 48 49 // Call this method to open the FileStream. The remaining methods 50 // cannot be used unless this method returns OK. If the file cannot be 51 // opened then an error code is returned. 52 // open_flags is a bitfield of base::PlatformFileFlags 53 int Open(const FilePath& path, int open_flags); 54 55 // Returns true if Open succeeded and Close has not been called. 56 bool IsOpen() const; 57 58 // Adjust the position from where data is read. Upon success, the stream 59 // position relative to the start of the file is returned. Otherwise, an 60 // error code is returned. It is not valid to call Seek while a Read call 61 // has a pending completion. 62 int64 Seek(Whence whence, int64 offset); 63 64 // Returns the number of bytes available to read from the current stream 65 // position until the end of the file. Otherwise, an error code is returned. 66 int64 Available(); 67 68 // Call this method to read data from the current stream position. Up to 69 // buf_len bytes will be copied into buf. (In other words, partial reads are 70 // allowed.) Returns the number of bytes copied, 0 if at end-of-file, or an 71 // error code if the operation could not be performed. 72 // 73 // If opened with PLATFORM_FILE_ASYNC, then a non-null callback 74 // must be passed to this method. In asynchronous mode, if the read could 75 // not complete synchronously, then ERR_IO_PENDING is returned, and the 76 // callback will be notified on the current thread (via the MessageLoop) when 77 // the read has completed. 78 // 79 // In the case of an asychronous read, the memory pointed to by |buf| must 80 // remain valid until the callback is notified. However, it is valid to 81 // destroy or close the file stream while there is an asynchronous read in 82 // progress. That will cancel the read and allow the buffer to be freed. 83 // 84 // This method should not be called if the stream was opened WRITE_ONLY. 85 // 86 // You can pass NULL as the callback for synchronous I/O. 87 int Read(char* buf, int buf_len, CompletionCallback* callback); 88 89 // Performs the same as Read, but ensures that exactly buf_len bytes 90 // are copied into buf. A partial read may occur, but only as a result of 91 // end-of-file or fatal error. Returns the number of bytes copied into buf, 92 // 0 if at end-of-file and no bytes have been read into buf yet, 93 // or an error code if the operation could not be performed. 94 int ReadUntilComplete(char *buf, int buf_len); 95 96 // Call this method to write data at the current stream position. Up to 97 // buf_len bytes will be written from buf. (In other words, partial writes are 98 // allowed.) Returns the number of bytes written, or an error code if the 99 // operation could not be performed. 100 // 101 // If opened with PLATFORM_FILE_ASYNC, then a non-null callback 102 // must be passed to this method. In asynchronous mode, if the write could 103 // not complete synchronously, then ERR_IO_PENDING is returned, and the 104 // callback will be notified on the current thread (via the MessageLoop) when 105 // the write has completed. 106 // 107 // In the case of an asychronous write, the memory pointed to by |buf| must 108 // remain valid until the callback is notified. However, it is valid to 109 // destroy or close the file stream while there is an asynchronous write in 110 // progress. That will cancel the write and allow the buffer to be freed. 111 // 112 // This method should not be called if the stream was opened READ_ONLY. 113 // 114 // You can pass NULL as the callback for synchronous I/O. 115 int Write(const char* buf, int buf_len, CompletionCallback* callback); 116 117 // Truncates the file to be |bytes| length. This is only valid for writable 118 // files. After truncation the file stream is positioned at |bytes|. The new 119 // position is retured, or a value < 0 on error. 120 // WARNING: one may not truncate a file beyond its current length on any 121 // platform with this call. 122 int64 Truncate(int64 bytes); 123 124 // Forces out a filesystem sync on this file to make sure that the file was 125 // written out to disk and is not currently sitting in the buffer. This does 126 // not have to be called, it just forces one to happen at the time of 127 // calling. 128 // 129 /// Returns an error code if the operation could not be performed. 130 // 131 // This method should not be called if the stream was opened READ_ONLY. 132 int Flush(); 133 134 private: 135 class AsyncContext; 136 friend class AsyncContext; 137 138 // This member is used to support asynchronous reads. It is non-null when 139 // the FileStream was opened with PLATFORM_FILE_ASYNC. 140 scoped_ptr<AsyncContext> async_context_; 141 142 base::PlatformFile file_; 143 int open_flags_; 144 bool auto_closed_; 145 146 DISALLOW_COPY_AND_ASSIGN(FileStream); 147 }; 148 149 } // namespace net 150 151 #endif // NET_BASE_FILE_STREAM_H_ 152