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