Thomas Lyp / DevLibMemoryController

Initial commit

Dependencies:   FastPWM

mbed-dev-master/platform/FileHandle.h@0:bb348c97df44, 2020-09-16 (annotated)

Committer:
lypinator
Date:
Wed Sep 16 01:11:49 2020 +0000
Revision:
0:bb348c97df44
Added PWM

Who changed what in which revision?

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