Kev Mann / mbed-dev-OS5_10_4

RTC auf true

platform/FileHandle.h@0:38ceb79fef03, 2018-11-28 (annotated)

Committer:
kevman
Date:
Wed Nov 28 15:10:15 2018 +0000
Revision:
0:38ceb79fef03
RTC modified

Who changed what in which revision?

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