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