Kyle Wengryn / platform

update

FileHandle.h@0:bfff72fb3650, 2021-04-08 (annotated)

Committer:
kwengryn3
Date:
Thu Apr 08 16:43:07 2021 +0000
Revision:
0:bfff72fb3650
update;

Who changed what in which revision?

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