takashi kadono / Mbed OS Nucleo446_SSD1331

Color Oled(SSD1331) connect to STMicroelectronics Nucleo-F466

Dependencies:   ssd1331

mbed-os/platform/FileHandle.h@3:f3764f852aa8, 2018-10-11 (annotated)

Committer:
kadonotakashi
Date:
Thu Oct 11 02:27:46 2018 +0000
Revision:
3:f3764f852aa8
Parent:
0:8fdf9a60065b 
Nucreo 446 + SSD1331 test version;

Who changed what in which revision?

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