Nicolas Borla / Mbed OS BBR_1Ebene

BBR 1 Ebene

mbed-os/platform/FileHandle.h@0:fbdae7e6d805, 2018-05-14 (annotated)

Committer:
borlanic
Date:
Mon May 14 11:29:06 2018 +0000
Revision:
0:fbdae7e6d805
BBR

Who changed what in which revision?

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