Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
FileHandle.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2017-2019 ARM Limited 00003 * SPDX-License-Identifier: Apache-2.0 00004 * 00005 * Licensed under the Apache License, Version 2.0 (the "License"); 00006 * you may not use this file except in compliance with the License. 00007 * You may obtain a copy of the License at 00008 * 00009 * http://www.apache.org/licenses/LICENSE-2.0 00010 * 00011 * Unless required by applicable law or agreed to in writing, software 00012 * distributed under the License is distributed on an "AS IS" BASIS, 00013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00014 * See the License for the specific language governing permissions and 00015 * limitations under the License. 00016 */ 00017 #ifndef MBED_FILEHANDLE_H 00018 #define MBED_FILEHANDLE_H 00019 00020 typedef int FILEHANDLE; 00021 00022 #include <cstdio> 00023 #include "platform/Callback.h" 00024 #include "platform/mbed_poll.h" 00025 #include "platform/platform.h" 00026 #include "platform/NonCopyable.h" 00027 00028 namespace mbed { 00029 00030 /** 00031 * \defgroup platform_FileHandle FileHandle functions 00032 * \ingroup platform-public-api-file 00033 * @{ 00034 */ 00035 00036 00037 /** Class FileHandle 00038 * 00039 * An abstract interface that represents operations on a file-like 00040 * object. The core functions are read, write and seek, but only 00041 * a subset of these operations can be provided. 00042 * 00043 * @note to create a file, @see File 00044 * @note Synchronization level: Set by subclass 00045 */ 00046 class FileHandle : private NonCopyable<FileHandle> { 00047 public: 00048 virtual ~FileHandle() {} 00049 00050 /** Read the contents of a file into a buffer 00051 * 00052 * Devices acting as FileHandles should follow POSIX semantics: 00053 * 00054 * * if no data is available, and nonblocking set, return -EAGAIN 00055 * * if no data is available, and blocking set, wait until some data is available 00056 * * If any data is available, call returns immediately 00057 * 00058 * @param buffer The buffer to read in to 00059 * @param size The number of bytes to read 00060 * @return The number of bytes read, 0 at end of file, negative error on failure 00061 */ 00062 virtual ssize_t read(void *buffer, size_t size) = 0; 00063 00064 /** Write the contents of a buffer to a file 00065 * 00066 * Devices acting as FileHandles should follow POSIX semantics: 00067 * 00068 * * if blocking, block until all data is written 00069 * * if no data can be written, and nonblocking set, return -EAGAIN 00070 * * if some data can be written, and nonblocking set, write partial 00071 * 00072 * @param buffer The buffer to write from 00073 * @param size The number of bytes to write 00074 * @return The number of bytes written, negative error on failure 00075 */ 00076 virtual ssize_t write(const void *buffer, size_t size) = 0; 00077 00078 /** Move the file position to a given offset from from a given location 00079 * 00080 * @param offset The offset from whence to move to 00081 * @param whence The start of where to seek 00082 * SEEK_SET to start from beginning of file, 00083 * SEEK_CUR to start from current position in file, 00084 * SEEK_END to start from end of file 00085 * @return The new offset of the file, negative error code on failure 00086 */ 00087 virtual off_t seek(off_t offset, int whence = SEEK_SET) = 0; 00088 00089 /** Close a file 00090 * 00091 * @return 0 on success, negative error code on failure 00092 */ 00093 virtual int close() = 0; 00094 00095 /** Flush any buffers associated with the file 00096 * 00097 * @return 0 on success, negative error code on failure 00098 */ 00099 virtual int sync() 00100 { 00101 return 0; 00102 } 00103 00104 /** Check if the file in an interactive terminal device 00105 * 00106 * @return True if the file is a terminal 00107 * @return False if the file is not a terminal 00108 * @return Negative error code on failure 00109 */ 00110 virtual int isatty() 00111 { 00112 return false; 00113 } 00114 00115 /** Get the file position of the file 00116 * 00117 * @note This is equivalent to seek(0, SEEK_CUR) 00118 * 00119 * @return The current offset in the file, negative error code on failure 00120 */ 00121 virtual off_t tell() 00122 { 00123 return seek(0, SEEK_CUR); 00124 } 00125 00126 /** Rewind the file position to the beginning of the file 00127 * 00128 * @note This is equivalent to seek(0, SEEK_SET) 00129 */ 00130 virtual void rewind() 00131 { 00132 seek(0, SEEK_SET); 00133 } 00134 00135 /** Get the size of the file 00136 * 00137 * @return Size of the file in bytes 00138 */ 00139 virtual off_t size(); 00140 00141 /** Truncate or extend a file. 00142 * 00143 * The file's length is set to the specified value. The seek pointer is 00144 * not changed. If the file is extended, the extended area appears as if 00145 * it were zero-filled. 00146 * 00147 * @param length The requested new length for the file 00148 * 00149 * @return Zero on success, negative error code on failure 00150 */ 00151 virtual int truncate(off_t length) 00152 { 00153 return -EINVAL; 00154 } 00155 00156 /** Move the file position to a given offset from a given location. 00157 * 00158 * @param offset The offset from whence to move to 00159 * @param whence SEEK_SET for the start of the file, SEEK_CUR for the 00160 * current file position, or SEEK_END for the end of the file. 00161 * 00162 * @returns 00163 * new file position on success, 00164 * -1 on failure or unsupported 00165 * @deprecated Replaced by `off_t FileHandle::seek(off_t offset, int whence = SEEK_SET)' 00166 * 00167 */ 00168 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::seek") 00169 virtual off_t lseek(off_t offset, int whence) 00170 { 00171 return seek(offset, whence); 00172 } 00173 00174 /** Flush any buffers associated with the FileHandle, ensuring it 00175 * is up to date on disk 00176 * 00177 * @returns 00178 * 0 on success or un-needed, 00179 * -1 on error 00180 * @deprecated Replaced by `int FileHandle::sync()' 00181 */ 00182 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::sync") 00183 virtual int fsync() 00184 { 00185 return sync(); 00186 } 00187 00188 /** Find the length of the file 00189 * 00190 * @returns 00191 * Length of the file 00192 * @deprecated Replaced by `off_t FileHandle::size()' 00193 */ 00194 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::size") 00195 virtual off_t flen() 00196 { 00197 return size(); 00198 } 00199 00200 /** Set blocking or nonblocking mode of the file operation like read/write. 00201 * Definition depends on the subclass implementing FileHandle. 00202 * The default is blocking. 00203 * 00204 * @param blocking true for blocking mode, false for nonblocking mode. 00205 * 00206 * @return 0 on success 00207 * @return Negative error code on failure 00208 */ 00209 virtual int set_blocking(bool blocking) 00210 { 00211 return blocking ? 0 : -ENOTTY; 00212 } 00213 00214 /** Check current blocking or nonblocking mode for file operations. 00215 * 00216 * @return true for blocking mode, false for nonblocking mode. 00217 */ 00218 virtual bool is_blocking() const 00219 { 00220 return true; 00221 } 00222 00223 /** Enable or disable input 00224 * 00225 * Control enabling of device for input. This is primarily intended 00226 * for temporary power-saving; the overall ability of the device to operate for 00227 * input and/or output may be fixed at creation time, but this call can 00228 * allow input to be temporarily disabled to permit power saving without 00229 * losing device state. 00230 * 00231 * @param enabled true to enable input, false to disable. 00232 * 00233 * @return 0 on success 00234 * @return Negative error code on failure 00235 */ 00236 virtual int enable_input(bool enabled) 00237 { 00238 return -EINVAL; 00239 } 00240 00241 /** Enable or disable output 00242 * 00243 * Control enabling of device for output. This is primarily intended 00244 * for temporary power-saving; the overall ability of the device to operate for 00245 * input and/or output may be fixed at creation time, but this call can 00246 * allow output to be temporarily disabled to permit power saving without 00247 * losing device state. 00248 * 00249 * @param enabled true to enable output, false to disable. 00250 * 00251 * @return 0 on success 00252 * @return Negative error code on failure 00253 */ 00254 virtual int enable_output(bool enabled) 00255 { 00256 return -EINVAL; 00257 } 00258 00259 /** Check for poll event flags 00260 * You can use or ignore the input parameter. You can return all events 00261 * or check just the events listed in events. 00262 * Call is nonblocking - returns instantaneous state of events. 00263 * Whenever an event occurs, the derived class should call the sigio() callback). 00264 * 00265 * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc. 00266 * 00267 * @returns bitmask of poll events that have occurred. 00268 */ 00269 virtual short poll(short events) const 00270 { 00271 // Possible default for real files 00272 return POLLIN | POLLOUT; 00273 } 00274 00275 /** Definition depends on the subclass implementing FileHandle. 00276 * For example, if the FileHandle is of type Stream, writable() could return 00277 * true when there is ample buffer space available for write() calls. 00278 * 00279 * @returns true if the FileHandle is writable. 00280 */ 00281 bool writable() const 00282 { 00283 return poll(POLLOUT) & POLLOUT; 00284 } 00285 00286 /** Definition depends on the subclass implementing FileHandle. 00287 * For example, if the FileHandle is of type Stream, readable() could return 00288 * true when there is something available to read. 00289 * 00290 * @returns true when there is something available to read. 00291 */ 00292 bool readable() const 00293 { 00294 return poll(POLLIN) & POLLIN; 00295 } 00296 00297 /** Register a callback on state change of the file. 00298 * 00299 * The specified callback will be called on state changes such as when 00300 * the file can be written to or read from. 00301 * 00302 * The callback may be called in an interrupt context and should not 00303 * perform expensive operations. 00304 * 00305 * Note! This is not intended as an attach-like asynchronous API, but rather 00306 * as a building block for constructing such functionality. 00307 * 00308 * The exact timing of when the registered function 00309 * is called is not guaranteed and is susceptible to change. It should be used 00310 * as a cue to make read/write/poll calls to find the current state. 00311 * 00312 * @param func Function to call on state change 00313 */ 00314 virtual void sigio(Callback<void()> func) 00315 { 00316 //Default for real files. Do nothing for real files. 00317 } 00318 }; 00319 00320 /**@}*/ 00321 00322 } // namespace mbed 00323 00324 #endif
Generated on Tue Jul 12 2022 13:54:21 by
