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/net_export.h"
  16
  17 namespace base {
  18 class FilePath;
  19 class TaskRunner;
  20 }
  21
  22 namespace net {
  23
  24 class IOBuffer;
  25
  26 class 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_