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