EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

platform/FileHandle.h@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

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