Nathan Yonkee / Mbed 2 deprecated Nucleo_sinewave_output_copy

init

Dependencies:   mbed

mbed-os/platform/FileHandle.h@10:46a4cf51ee38, 2018-03-02 (annotated)

Committer:
Nathan Yonkee
Date:
Fri Mar 02 07:16:49 2018 -0700
Revision:
10:46a4cf51ee38
Parent:
9:d58e77ebd769 
remove mbed-os

Who changed what in which revision?

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