Mistake on this page?
Report an issue in GitHub or email us
FileHandle.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017-2019 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 #ifndef MBED_FILEHANDLE_H
18 #define MBED_FILEHANDLE_H
19 
20 typedef int FILEHANDLE;
21 
22 #include <cstdio>
23 #include "platform/Callback.h"
24 #include "platform/mbed_poll.h"
25 #include "platform/platform.h"
26 #include "platform/NonCopyable.h"
27 
28 namespace mbed {
29 
30 /**
31  * \defgroup platform_FileHandle FileHandle functions
32  * \ingroup platform-public-api-file
33  * @{
34  */
35 
36 
37 /** Class FileHandle
38  *
39  * An abstract interface that represents operations on a file-like
40  * object. The core functions are read, write and seek, but only
41  * a subset of these operations can be provided.
42  *
43  * @note to create a file, @see File
44  * @note Synchronization level: Set by subclass
45  */
46 class FileHandle : private NonCopyable<FileHandle> {
47 public:
48  virtual ~FileHandle() = default;
49 
50  /** Read the contents of a file into a buffer
51  *
52  * Devices acting as FileHandles should follow POSIX semantics:
53  *
54  * * if no data is available, and nonblocking set, return -EAGAIN
55  * * if no data is available, and blocking set, wait until some data is available
56  * * If any data is available, call returns immediately
57  *
58  * @param buffer The buffer to read in to
59  * @param size The number of bytes to read
60  * @return The number of bytes read, 0 at end of file, negative error on failure
61  */
62  virtual ssize_t read(void *buffer, size_t size) = 0;
63 
64  /** Write the contents of a buffer to a file
65  *
66  * Devices acting as FileHandles should follow POSIX semantics:
67  *
68  * * if blocking, block until all data is written
69  * * if no data can be written, and nonblocking set, return -EAGAIN
70  * * if some data can be written, and nonblocking set, write partial
71  *
72  * @param buffer The buffer to write from
73  * @param size The number of bytes to write
74  * @return The number of bytes written, negative error on failure
75  */
76  virtual ssize_t write(const void *buffer, size_t size) = 0;
77 
78  /** Move the file position to a given offset from from a given location
79  *
80  * @param offset The offset from whence to move to
81  * @param whence The start of where to seek
82  * SEEK_SET to start from beginning of file,
83  * SEEK_CUR to start from current position in file,
84  * SEEK_END to start from end of file
85  * @return The new offset of the file, negative error code on failure
86  */
87  virtual off_t seek(off_t offset, int whence = SEEK_SET) = 0;
88 
89  /** Close a file
90  *
91  * @return 0 on success, negative error code on failure
92  */
93  virtual int close() = 0;
94 
95  /** Flush any buffers associated with the file
96  *
97  * @return 0 on success, negative error code on failure
98  */
99  virtual int sync()
100  {
101  return 0;
102  }
103 
104  /** Check if the file in an interactive terminal device
105  *
106  * @return True if the file is a terminal
107  * @return False if the file is not a terminal
108  * @return Negative error code on failure
109  */
110  virtual int isatty()
111  {
112  return false;
113  }
114 
115  /** Get the file position of the file
116  *
117  * @note This is equivalent to seek(0, SEEK_CUR)
118  *
119  * @return The current offset in the file, negative error code on failure
120  */
121  virtual off_t tell()
122  {
123  return seek(0, SEEK_CUR);
124  }
125 
126  /** Rewind the file position to the beginning of the file
127  *
128  * @note This is equivalent to seek(0, SEEK_SET)
129  */
130  virtual void rewind()
131  {
132  seek(0, SEEK_SET);
133  }
134 
135  /** Get the size of the file
136  *
137  * @return Size of the file in bytes
138  */
139  virtual off_t size();
140 
141  /** Truncate or extend a file.
142  *
143  * The file's length is set to the specified value. The seek pointer is
144  * not changed. If the file is extended, the extended area appears as if
145  * it were zero-filled.
146  *
147  * @param length The requested new length for the file
148  *
149  * @return Zero on success, negative error code on failure
150  */
151  virtual int truncate(off_t length)
152  {
153  return -EINVAL;
154  }
155 
156  /** Set blocking or nonblocking mode of the file operation like read/write.
157  * Definition depends on the subclass implementing FileHandle.
158  * The default is blocking.
159  *
160  * @param blocking true for blocking mode, false for nonblocking mode.
161  *
162  * @return 0 on success
163  * @return Negative error code on failure
164  */
165  virtual int set_blocking(bool blocking)
166  {
167  return blocking ? 0 : -ENOTTY;
168  }
169 
170  /** Check current blocking or nonblocking mode for file operations.
171  *
172  * @return true for blocking mode, false for nonblocking mode.
173  */
174  virtual bool is_blocking() const
175  {
176  return true;
177  }
178 
179  /** Enable or disable input
180  *
181  * Control enabling of device for input. This is primarily intended
182  * for temporary power-saving; the overall ability of the device to operate for
183  * input and/or output may be fixed at creation time, but this call can
184  * allow input to be temporarily disabled to permit power saving without
185  * losing device state.
186  *
187  * @param enabled true to enable input, false to disable.
188  *
189  * @return 0 on success
190  * @return Negative error code on failure
191  */
192  virtual int enable_input(bool enabled)
193  {
194  return -EINVAL;
195  }
196 
197  /** Enable or disable output
198  *
199  * Control enabling of device for output. This is primarily intended
200  * for temporary power-saving; the overall ability of the device to operate for
201  * input and/or output may be fixed at creation time, but this call can
202  * allow output to be temporarily disabled to permit power saving without
203  * losing device state.
204  *
205  * @param enabled true to enable output, false to disable.
206  *
207  * @return 0 on success
208  * @return Negative error code on failure
209  */
210  virtual int enable_output(bool enabled)
211  {
212  return -EINVAL;
213  }
214 
215  /** Check for poll event flags
216  * You can use or ignore the input parameter. You can return all events
217  * or check just the events listed in events.
218  * Call is nonblocking - returns instantaneous state of events.
219  * Whenever an event occurs, the derived class should call the sigio() callback).
220  *
221  * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc.
222  *
223  * @returns bitmask of poll events that have occurred.
224  */
225  virtual short poll(short events) const
226  {
227  // Possible default for real files
228  return POLLIN | POLLOUT;
229  }
230 
231  /** Definition depends on the subclass implementing FileHandle.
232  * For example, if the FileHandle is of type Stream, writable() could return
233  * true when there is ample buffer space available for write() calls.
234  *
235  * @returns true if the FileHandle is writable.
236  */
237  bool writable() const
238  {
239  return poll(POLLOUT) & POLLOUT;
240  }
241 
242  /** Definition depends on the subclass implementing FileHandle.
243  * For example, if the FileHandle is of type Stream, readable() could return
244  * true when there is something available to read.
245  *
246  * @returns true when there is something available to read.
247  */
248  bool readable() const
249  {
250  return poll(POLLIN) & POLLIN;
251  }
252 
253  /** Register a callback on state change of the file.
254  *
255  * The specified callback will be called on state changes such as when
256  * the file can be written to or read from.
257  *
258  * The callback may be called in an interrupt context and should not
259  * perform expensive operations.
260  *
261  * Note! This is not intended as an attach-like asynchronous API, but rather
262  * as a building block for constructing such functionality.
263  *
264  * The exact timing of when the registered function
265  * is called is not guaranteed and is susceptible to change. It should be used
266  * as a cue to make read/write/poll calls to find the current state.
267  *
268  * @param func Function to call on state change
269  */
270  virtual void sigio(Callback<void()> func)
271  {
272  //Default for real files. Do nothing for real files.
273  }
274 };
275 
276 /**@}*/
277 
278 } // namespace mbed
279 
280 #endif
virtual off_t size()
Get the size of the file.
virtual void sigio(Callback< void()> func)
Register a callback on state change of the file.
Definition: FileHandle.h:270
bool readable() const
Definition depends on the subclass implementing FileHandle.
Definition: FileHandle.h:248
virtual int set_blocking(bool blocking)
Set blocking or nonblocking mode of the file operation like read/write.
Definition: FileHandle.h:165
virtual ssize_t write(const void *buffer, size_t size)=0
Write the contents of a buffer to a file.
virtual int enable_output(bool enabled)
Enable or disable output.
Definition: FileHandle.h:210
virtual int close()=0
Close a file.
virtual int isatty()
Check if the file in an interactive terminal device.
Definition: FileHandle.h:110
Class FileHandle.
Definition: FileHandle.h:46
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:162
virtual off_t seek(off_t offset, int whence=SEEK_SET)=0
Move the file position to a given offset from from a given location.
virtual ssize_t read(void *buffer, size_t size)=0
Read the contents of a file into a buffer.
virtual int sync()
Flush any buffers associated with the file.
Definition: FileHandle.h:99
virtual short poll(short events) const
Check for poll event flags You can use or ignore the input parameter.
Definition: FileHandle.h:225
virtual int truncate(off_t length)
Truncate or extend a file.
Definition: FileHandle.h:151
virtual int enable_input(bool enabled)
Enable or disable input.
Definition: FileHandle.h:192
virtual void rewind()
Rewind the file position to the beginning of the file.
Definition: FileHandle.h:130
virtual off_t tell()
Get the file position of the file.
Definition: FileHandle.h:121
bool writable() const
Definition depends on the subclass implementing FileHandle.
Definition: FileHandle.h:237
Callback class based on template specialization.
Definition: Callback.h:53
virtual bool is_blocking() const
Check current blocking or nonblocking mode for file operations.
Definition: FileHandle.h:174
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.