mbed library sources. Supersedes mbed-src.
Dependents: Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more
FileHandle.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2017 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 "Callback.h" 00024 #include "platform/mbed_poll.h" 00025 #include "platform/platform.h" 00026 #include "platform/NonCopyable.h" 00027 00028 namespace mbed { 00029 /** \addtogroup platform */ 00030 /** @{*/ 00031 /** 00032 * \defgroup platform_FileHandle FileHandle functions 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 /** Move the file position to a given offset from a given location. 00142 * 00143 * @param offset The offset from whence to move to 00144 * @param whence SEEK_SET for the start of the file, SEEK_CUR for the 00145 * current file position, or SEEK_END for the end of the file. 00146 * 00147 * @returns 00148 * new file position on success, 00149 * -1 on failure or unsupported 00150 * @deprecated Replaced by `off_t FileHandle::seek(off_t offset, int whence = SEEK_SET)' 00151 * 00152 */ 00153 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::seek") 00154 virtual off_t lseek(off_t offset, int whence) 00155 { 00156 return seek(offset, whence); 00157 } 00158 00159 /** Flush any buffers associated with the FileHandle, ensuring it 00160 * is up to date on disk 00161 * 00162 * @returns 00163 * 0 on success or un-needed, 00164 * -1 on error 00165 * @deprecated Replaced by `int FileHandle::sync()' 00166 */ 00167 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::sync") 00168 virtual int fsync() 00169 { 00170 return sync(); 00171 } 00172 00173 /** Find the length of the file 00174 * 00175 * @returns 00176 * Length of the file 00177 * @deprecated Replaced by `off_t FileHandle::size()' 00178 */ 00179 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::size") 00180 virtual off_t flen() 00181 { 00182 return size(); 00183 } 00184 00185 /** Set blocking or nonblocking mode of the file operation like read/write. 00186 * Definition depends on the subclass implementing FileHandle. 00187 * The default is blocking. 00188 * 00189 * @param blocking true for blocking mode, false for nonblocking mode. 00190 * 00191 * @return 0 on success 00192 * @return Negative error code on failure 00193 */ 00194 virtual int set_blocking(bool blocking) 00195 { 00196 return blocking ? 0 : -ENOTTY; 00197 } 00198 00199 /** Check current blocking or nonblocking mode for file operations. 00200 * 00201 * @return true for blocking mode, false for nonblocking mode. 00202 */ 00203 virtual bool is_blocking() const 00204 { 00205 return true; 00206 } 00207 00208 /** Check for poll event flags 00209 * You can use or ignore the input parameter. You can return all events 00210 * or check just the events listed in events. 00211 * Call is nonblocking - returns instantaneous state of events. 00212 * Whenever an event occurs, the derived class should call the sigio() callback). 00213 * 00214 * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc. 00215 * 00216 * @returns bitmask of poll events that have occurred. 00217 */ 00218 virtual short poll(short events) const 00219 { 00220 // Possible default for real files 00221 return POLLIN | POLLOUT; 00222 } 00223 00224 /** Definition depends on the subclass implementing FileHandle. 00225 * For example, if the FileHandle is of type Stream, writable() could return 00226 * true when there is ample buffer space available for write() calls. 00227 * 00228 * @returns true if the FileHandle is writable. 00229 */ 00230 bool writable() const 00231 { 00232 return poll(POLLOUT) & POLLOUT; 00233 } 00234 00235 /** Definition depends on the subclass implementing FileHandle. 00236 * For example, if the FileHandle is of type Stream, readable() could return 00237 * true when there is something available to read. 00238 * 00239 * @returns true when there is something available to read. 00240 */ 00241 bool readable() const 00242 { 00243 return poll(POLLIN) & POLLIN; 00244 } 00245 00246 /** Register a callback on state change of the file. 00247 * 00248 * The specified callback will be called on state changes such as when 00249 * the file can be written to or read from. 00250 * 00251 * The callback may be called in an interrupt context and should not 00252 * perform expensive operations. 00253 * 00254 * Note! This is not intended as an attach-like asynchronous API, but rather 00255 * as a building block for constructing such functionality. 00256 * 00257 * The exact timing of when the registered function 00258 * is called is not guaranteed and is susceptible to change. It should be used 00259 * as a cue to make read/write/poll calls to find the current state. 00260 * 00261 * @param func Function to call on state change 00262 */ 00263 virtual void sigio(Callback<void()> func) 00264 { 00265 //Default for real files. Do nothing for real files. 00266 } 00267 }; 00268 00269 /**@}*/ 00270 00271 /**@}*/ 00272 00273 00274 } // namespace mbed 00275 00276 #endif
Generated on Tue Jul 12 2022 20:41:14 by 1.7.2