net/base/file_stream.h

   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_