forked
Embed:
(wiki syntax)
Show/hide line numbers
FileHandle.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2017 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 #ifndef MBED_FILEHANDLE_H 00017 #define MBED_FILEHANDLE_H 00018 00019 typedef int FILEHANDLE; 00020 00021 #include <cstdio> 00022 #include "Callback.h" 00023 #include "platform/mbed_poll.h" 00024 #include "platform/platform.h" 00025 #include "platform/NonCopyable.h" 00026 00027 namespace mbed { 00028 /** \addtogroup platform */ 00029 00030 00031 /** Class FileHandle 00032 * 00033 * An abstract interface that represents operations on a file-like 00034 * object. The core functions are read, write, and seek, but only 00035 * a subset of these operations can be provided. 00036 * 00037 * @note to create a file, @see File 00038 * @note Synchronization level: Set by subclass 00039 * @ingroup platform 00040 */ 00041 class FileHandle : private NonCopyable<FileHandle> { 00042 public: 00043 virtual ~FileHandle() {} 00044 00045 /** Read the contents of a file into a buffer 00046 * 00047 * Devices acting as FileHandles should follow POSIX semantics: 00048 * 00049 * * if no data is available, and non-blocking set return -EAGAIN 00050 * * if no data is available, and blocking set, wait until data is available 00051 * * If any data is available, call returns immediately 00052 * 00053 * @param buffer The buffer to read in to 00054 * @param size The number of bytes to read 00055 * @return The number of bytes read, 0 at end of file, negative error on failure 00056 */ 00057 virtual ssize_t read(void *buffer, size_t size) = 0; 00058 00059 /** Write the contents of a buffer to a file 00060 * 00061 * @param buffer The buffer to write from 00062 * @param size The number of bytes to write 00063 * @return The number of bytes written, negative error on failure 00064 */ 00065 virtual ssize_t write(const void *buffer, size_t size) = 0; 00066 00067 /** Move the file position to a given offset from from a given location 00068 * 00069 * @param offset The offset from whence to move to 00070 * @param whence The start of where to seek 00071 * SEEK_SET to start from beginning of file, 00072 * SEEK_CUR to start from current position in file, 00073 * SEEK_END to start from end of file 00074 * @return The new offset of the file, negative error code on failure 00075 */ 00076 virtual off_t seek(off_t offset, int whence = SEEK_SET) = 0; 00077 00078 /** Close a file 00079 * 00080 * @return 0 on success, negative error code on failure 00081 */ 00082 virtual int close() = 0; 00083 00084 /** Flush any buffers associated with the file 00085 * 00086 * @return 0 on success, negative error code on failure 00087 */ 00088 virtual int sync() 00089 { 00090 return 0; 00091 } 00092 00093 /** Check if the file in an interactive terminal device 00094 * 00095 * @return True if the file is a terminal 00096 * @return False if the file is not a terminal 00097 * @return Negative error code on failure 00098 */ 00099 virtual int isatty() 00100 { 00101 return false; 00102 } 00103 00104 /** Get the file position of the file 00105 * 00106 * @note This is equivalent to seek(0, SEEK_CUR) 00107 * 00108 * @return The current offset in the file, negative error code on failure 00109 */ 00110 virtual off_t tell() 00111 { 00112 return seek(0, SEEK_CUR); 00113 } 00114 00115 /** Rewind the file position to the beginning of the file 00116 * 00117 * @note This is equivalent to seek(0, SEEK_SET) 00118 */ 00119 virtual void rewind() 00120 { 00121 seek(0, SEEK_SET); 00122 } 00123 00124 /** Get the size of the file 00125 * 00126 * @return Size of the file in bytes 00127 */ 00128 virtual off_t size(); 00129 00130 /** Move the file position to a given offset from a given location. 00131 * 00132 * @param offset The offset from whence to move to 00133 * @param whence SEEK_SET for the start of the file, SEEK_CUR for the 00134 * current file position, or SEEK_END for the end of the file. 00135 * 00136 * @returns 00137 * new file position on success, 00138 * -1 on failure or unsupported 00139 */ 00140 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::seek") 00141 virtual off_t lseek(off_t offset, int whence) 00142 { 00143 return seek(offset, whence); 00144 } 00145 00146 /** Flush any buffers associated with the FileHandle, ensuring it 00147 * is up to date on disk 00148 * 00149 * @returns 00150 * 0 on success or un-needed, 00151 * -1 on error 00152 */ 00153 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::sync") 00154 virtual int fsync() 00155 { 00156 return sync(); 00157 } 00158 00159 /** Find the length of the file 00160 * 00161 * @returns 00162 * Length of the file 00163 */ 00164 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::size") 00165 virtual off_t flen() 00166 { 00167 return size(); 00168 } 00169 00170 /** Set blocking or non-blocking mode of the file operation like read/write. 00171 * Definition depends upon the subclass implementing FileHandle. 00172 * The default is blocking. 00173 * 00174 * @param blocking true for blocking mode, false for non-blocking mode. 00175 * 00176 * @return 0 on success 00177 * @return Negative error code on failure 00178 */ 00179 virtual int set_blocking(bool blocking) 00180 { 00181 return -1; 00182 } 00183 00184 /** Check for poll event flags 00185 * The input parameter can be used or ignored - the could always return all events, 00186 * or could check just the events listed in events. 00187 * Call is non-blocking - returns instantaneous state of events. 00188 * Whenever an event occurs, the derived class should call the sigio() callback). 00189 * 00190 * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc. 00191 * 00192 * @returns bitmask of poll events that have occurred. 00193 */ 00194 virtual short poll(short events) const 00195 { 00196 // Possible default for real files 00197 return POLLIN | POLLOUT; 00198 } 00199 00200 /** Definition depends upon the subclass implementing FileHandle. 00201 * For example, if the FileHandle is of type Stream, writable() could return 00202 * true when there is ample buffer space available for write() calls. 00203 * 00204 * @returns true if the FileHandle is writable. 00205 */ 00206 bool writable() const 00207 { 00208 return poll(POLLOUT) & POLLOUT; 00209 } 00210 00211 /** Definition depends upon the subclass implementing FileHandle. 00212 * For example, if the FileHandle is of type Stream, readable() could return 00213 * true when there is something available to read. 00214 * 00215 * @returns true when there is something available to read. 00216 */ 00217 bool readable() const 00218 { 00219 return poll(POLLIN) & POLLIN; 00220 } 00221 00222 /** Register a callback on state change of the file. 00223 * 00224 * The specified callback will be called on state changes such as when 00225 * the file can be written to or read from. 00226 * 00227 * The callback may be called in an interrupt context and should not 00228 * perform expensive operations. 00229 * 00230 * Note! This is not intended as an attach-like asynchronous api, but rather 00231 * as a building block for constructing such functionality. 00232 * 00233 * The exact timing of when the registered function 00234 * is called is not guaranteed and susceptible to change. It should be used 00235 * as a cue to make read/write/poll calls to find the current state. 00236 * 00237 * @param func Function to call on state change 00238 */ 00239 virtual void sigio(Callback<void()> func) 00240 { 00241 //Default for real files. Do nothing for real files. 00242 } 00243 }; 00244 00245 /** Not a member function 00246 * This call is equivalent to posix fdopen(). 00247 * It associates a Stream to an already opened file descriptor (FileHandle) 00248 * 00249 * @param fh a pointer to an opened file descriptor 00250 * @param mode operation upon the file descriptor, e.g., 'wb+' 00251 * 00252 * @returns a pointer to std::FILE 00253 */ 00254 00255 std::FILE *fdopen(FileHandle *fh, const char *mode); 00256 00257 } // namespace mbed 00258 00259 #endif
Generated on Tue Jul 12 2022 16:02:32 by
![doxygen](doxygen.png)