1 // Copyright (c) 2012 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 13 #include "base/files/file.h" 14 #include "net/base/completion_callback.h" 15 #include "net/base/file_stream_whence.h" 16 #include "net/base/net_export.h" 17 18 namespace base { 19 class FilePath; 20 class TaskRunner; 21 } 22 23 namespace net { 24 25 class IOBuffer; 26 27 class NET_EXPORT FileStream { 28 public: 29 // Creates a FileStream. 30 // Uses |task_runner| for asynchronous operations. 31 explicit FileStream(const scoped_refptr<base::TaskRunner>& task_runner); 32 33 // Construct a FileStream with an existing valid |file|. 34 // Uses |task_runner| for asynchronous operations. 35 FileStream(base::File file, 36 const scoped_refptr<base::TaskRunner>& task_runner); 37 38 // The underlying file is closed automatically. 39 virtual ~FileStream(); 40 41 // Call this method to open the FileStream asynchronously. The remaining 42 // methods cannot be used unless the file is opened successfully. Returns 43 // ERR_IO_PENDING if the operation is started. If the operation cannot be 44 // started then an error code is returned. 45 // 46 // Once the operation is done, |callback| will be run on the thread where 47 // Open() was called, with the result code. open_flags is a bitfield of 48 // base::File::Flags. 49 // 50 // If the file stream is not closed manually, the underlying file will be 51 // automatically closed when FileStream is destructed in an asynchronous 52 // manner (i.e. the file stream is closed in the background but you don't 53 // know when). 54 virtual int Open(const base::FilePath& path, int open_flags, 55 const CompletionCallback& callback); 56 57 // Returns ERR_IO_PENDING and closes the file asynchronously, calling 58 // |callback| when done. 59 // It is invalid to request any asynchronous operations while there is an 60 // in-flight asynchronous operation. 61 virtual int Close(const CompletionCallback& callback); 62 63 // Returns true if Open succeeded and Close has not been called. 64 virtual bool IsOpen() const; 65 66 // Adjust the position from where data is read asynchronously. 67 // Upon success, ERR_IO_PENDING is returned and |callback| will be run 68 // on the thread where Seek() was called with the the stream position 69 // relative to the start of the file. Otherwise, an error code is returned. 70 // It is invalid to request any asynchronous operations while there is an 71 // in-flight asynchronous operation. 72 virtual int Seek(Whence whence, int64 offset, 73 const Int64CompletionCallback& callback); 74 75 // Call this method to read data from the current stream position 76 // asynchronously. Up to buf_len bytes will be copied into buf. (In 77 // other words, partial reads are allowed.) Returns the number of bytes 78 // copied, 0 if at end-of-file, or an error code if the operation could 79 // not be performed. 80 // 81 // The file must be opened with FLAG_ASYNC, and a non-null 82 // callback must be passed to this method. If the read could not 83 // complete synchronously, then ERR_IO_PENDING is returned, and the 84 // callback will be run on the thread where Read() was called, when the 85 // read has completed. 86 // 87 // It is valid to destroy or close the file stream while there is an 88 // asynchronous read in progress. That will cancel the read and allow 89 // the buffer to be freed. 90 // 91 // It is invalid to request any asynchronous operations while there is an 92 // in-flight asynchronous operation. 93 // 94 // This method must not be called if the stream was opened WRITE_ONLY. 95 virtual int Read(IOBuffer* buf, int buf_len, 96 const CompletionCallback& callback); 97 98 // Call this method to write data at the current stream position 99 // asynchronously. Up to buf_len bytes will be written from buf. (In 100 // other words, partial writes are allowed.) Returns the number of 101 // bytes written, or an error code if the operation could not be 102 // performed. 103 // 104 // The file must be opened with FLAG_ASYNC, and a non-null 105 // callback must be passed to this method. If the write could not 106 // complete synchronously, then ERR_IO_PENDING is returned, and the 107 // callback will be run on the thread where Write() was called when 108 // the write has completed. 109 // 110 // It is valid to destroy or close the file stream while there is an 111 // asynchronous write in progress. That will cancel the write and allow 112 // the buffer to be freed. 113 // 114 // It is invalid to request any asynchronous operations while there is an 115 // in-flight asynchronous operation. 116 // 117 // This method must not be called if the stream was opened READ_ONLY. 118 // 119 // Zero byte writes are not allowed. 120 virtual int Write(IOBuffer* buf, int buf_len, 121 const CompletionCallback& callback); 122 123 // Forces out a filesystem sync on this file to make sure that the file was 124 // written out to disk and is not currently sitting in the buffer. This does 125 // not have to be called, it just forces one to happen at the time of 126 // calling. 127 // 128 // The file must be opened with FLAG_ASYNC, and a non-null 129 // callback must be passed to this method. If the write could not 130 // complete synchronously, then ERR_IO_PENDING is returned, and the 131 // callback will be run on the thread where Flush() was called when 132 // the write has completed. 133 // 134 // It is valid to destroy or close the file stream while there is an 135 // asynchronous flush in progress. That will cancel the flush and allow 136 // the buffer to be freed. 137 // 138 // It is invalid to request any asynchronous operations while there is an 139 // in-flight asynchronous operation. 140 // 141 // This method should not be called if the stream was opened READ_ONLY. 142 virtual int Flush(const CompletionCallback& callback); 143 144 // Returns the underlying file for testing. 145 const base::File& GetFileForTesting() const; 146 147 private: 148 class Context; 149 150 // Context performing I/O operations. It was extracted into a separate class 151 // to perform asynchronous operations because FileStream can be destroyed 152 // before completion of an async operation. Also if a FileStream is destroyed 153 // without explicitly calling Close, the file should be closed asynchronously 154 // without delaying FileStream's destructor. 155 scoped_ptr<Context> context_; 156 157 DISALLOW_COPY_AND_ASSIGN(FileStream); 158 }; 159 160 } // namespace net 161 162 #endif // NET_BASE_FILE_STREAM_H_ 163