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