15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This file defines FileStream, a basic interface for reading and writing files 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// synchronously or asynchronously with support for seeking to an offset. 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Note that even when used asynchronously, only one operation is supported at 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// a time. 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef NET_BASE_FILE_STREAM_H_ 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define NET_BASE_FILE_STREAM_H_ 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1323730a6e56a168d1879203e4b3819bb36e3d8f1fTorne (Richard Coles)#include "base/files/file.h" 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/completion_callback.h" 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/file_stream_whence.h" 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/net_export.h" 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)namespace base { 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class FilePath; 20010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles)class TaskRunner; 212a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)} 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace net { 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class IOBuffer; 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NET_EXPORT FileStream { 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 290529e5d033099cbfc42635f6f6183833b09dff6eBen Murdoch // Creates a FileStream. 307d4cd473f85ac64c3747c96c277f9e506a0d2246Torne (Richard Coles) // Uses |task_runner| for asynchronous operations. 310529e5d033099cbfc42635f6f6183833b09dff6eBen Murdoch explicit FileStream(const scoped_refptr<base::TaskRunner>& task_runner); 327d4cd473f85ac64c3747c96c277f9e506a0d2246Torne (Richard Coles) 33010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) // Construct a FileStream with an existing valid |file|. 347d4cd473f85ac64c3747c96c277f9e506a0d2246Torne (Richard Coles) // Uses |task_runner| for asynchronous operations. 3523730a6e56a168d1879203e4b3819bb36e3d8f1fTorne (Richard Coles) FileStream(base::File file, 3623730a6e56a168d1879203e4b3819bb36e3d8f1fTorne (Richard Coles) const scoped_refptr<base::TaskRunner>& task_runner); 3723730a6e56a168d1879203e4b3819bb36e3d8f1fTorne (Richard Coles) 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The underlying file is closed automatically. 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~FileStream(); 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Call this method to open the FileStream asynchronously. The remaining 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // methods cannot be used unless the file is opened successfully. Returns 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // ERR_IO_PENDING if the operation is started. If the operation cannot be 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // started then an error code is returned. 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Once the operation is done, |callback| will be run on the thread where 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Open() was called, with the result code. open_flags is a bitfield of 48010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) // base::File::Flags. 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If the file stream is not closed manually, the underlying file will be 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // automatically closed when FileStream is destructed in an asynchronous 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // manner (i.e. the file stream is closed in the background but you don't 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // know when). 542a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) virtual int Open(const base::FilePath& path, int open_flags, 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback); 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) // Returns ERR_IO_PENDING and closes the file asynchronously, calling 5858537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) // |callback| when done. 5958537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) // It is invalid to request any asynchronous operations while there is an 6058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) // in-flight asynchronous operation. 6158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) virtual int Close(const CompletionCallback& callback); 6258537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns true if Open succeeded and Close has not been called. 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual bool IsOpen() const; 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Adjust the position from where data is read asynchronously. 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Upon success, ERR_IO_PENDING is returned and |callback| will be run 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // on the thread where Seek() was called with the the stream position 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // relative to the start of the file. Otherwise, an error code is returned. 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // It is invalid to request any asynchronous operations while there is an 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // in-flight asynchronous operation. 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int Seek(Whence whence, int64 offset, 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Int64CompletionCallback& callback); 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Call this method to read data from the current stream position 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // asynchronously. Up to buf_len bytes will be copied into buf. (In 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // other words, partial reads are allowed.) Returns the number of bytes 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // copied, 0 if at end-of-file, or an error code if the operation could 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // not be performed. 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 81010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) // The file must be opened with FLAG_ASYNC, and a non-null 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback must be passed to this method. If the read could not 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // complete synchronously, then ERR_IO_PENDING is returned, and the 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback will be run on the thread where Read() was called, when the 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // read has completed. 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // It is valid to destroy or close the file stream while there is an 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // asynchronous read in progress. That will cancel the read and allow 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the buffer to be freed. 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // It is invalid to request any asynchronous operations while there is an 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // in-flight asynchronous operation. 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This method must not be called if the stream was opened WRITE_ONLY. 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int Read(IOBuffer* buf, int buf_len, 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback); 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Call this method to write data at the current stream position 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // asynchronously. Up to buf_len bytes will be written from buf. (In 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // other words, partial writes are allowed.) Returns the number of 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // bytes written, or an error code if the operation could not be 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // performed. 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 104010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) // The file must be opened with FLAG_ASYNC, and a non-null 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback must be passed to this method. If the write could not 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // complete synchronously, then ERR_IO_PENDING is returned, and the 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback will be run on the thread where Write() was called when 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the write has completed. 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // It is valid to destroy or close the file stream while there is an 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // asynchronous write in progress. That will cancel the write and allow 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the buffer to be freed. 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // It is invalid to request any asynchronous operations while there is an 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // in-flight asynchronous operation. 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This method must not be called if the stream was opened READ_ONLY. 1182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // 1192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // Zero byte writes are not allowed. 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int Write(IOBuffer* buf, int buf_len, 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback); 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Forces out a filesystem sync on this file to make sure that the file was 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // written out to disk and is not currently sitting in the buffer. This does 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // not have to be called, it just forces one to happen at the time of 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // calling. 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 128010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) // The file must be opened with FLAG_ASYNC, and a non-null 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback must be passed to this method. If the write could not 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // complete synchronously, then ERR_IO_PENDING is returned, and the 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback will be run on the thread where Flush() was called when 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the write has completed. 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // It is valid to destroy or close the file stream while there is an 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // asynchronous flush in progress. That will cancel the flush and allow 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the buffer to be freed. 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // It is invalid to request any asynchronous operations while there is an 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // in-flight asynchronous operation. 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This method should not be called if the stream was opened READ_ONLY. 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int Flush(const CompletionCallback& callback); 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 144010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) // Returns the underlying file for testing. 14523730a6e56a168d1879203e4b3819bb36e3d8f1fTorne (Richard Coles) const base::File& GetFileForTesting() const; 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) class Context; 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 15023730a6e56a168d1879203e4b3819bb36e3d8f1fTorne (Richard Coles) // Context performing I/O operations. It was extracted into a separate class 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to perform asynchronous operations because FileStream can be destroyed 15223730a6e56a168d1879203e4b3819bb36e3d8f1fTorne (Richard Coles) // before completion of an async operation. Also if a FileStream is destroyed 15323730a6e56a168d1879203e4b3819bb36e3d8f1fTorne (Richard Coles) // without explicitly calling Close, the file should be closed asynchronously 15423730a6e56a168d1879203e4b3819bb36e3d8f1fTorne (Richard Coles) // without delaying FileStream's destructor. 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) scoped_ptr<Context> context_; 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) DISALLOW_COPY_AND_ASSIGN(FileStream); 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace net 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // NET_BASE_FILE_STREAM_H_ 163