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