Marco Zecchini
/
Example_RTOS
Rtos API example
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 * \defgroup platform_FileHandle FileHandle functions 00032 * @{ 00033 */ 00034 00035 00036 /** Class FileHandle 00037 * 00038 * An abstract interface that represents operations on a file-like 00039 * object. The core functions are read, write, and seek, but only 00040 * a subset of these operations can be provided. 00041 * 00042 * @note to create a file, @see File 00043 * @note Synchronization level: Set by subclass 00044 */ 00045 class FileHandle : private NonCopyable<FileHandle> { 00046 public: 00047 virtual ~FileHandle() {} 00048 00049 /** Read the contents of a file into a buffer 00050 * 00051 * Devices acting as FileHandles should follow POSIX semantics: 00052 * 00053 * * if no data is available, and non-blocking set return -EAGAIN 00054 * * if no data is available, and blocking set, wait until data is available 00055 * * If any data is available, call returns immediately 00056 * 00057 * @param buffer The buffer to read in to 00058 * @param size The number of bytes to read 00059 * @return The number of bytes read, 0 at end of file, negative error on failure 00060 */ 00061 virtual ssize_t read(void *buffer, size_t size) = 0; 00062 00063 /** Write the contents of a buffer to a file 00064 * 00065 * @param buffer The buffer to write from 00066 * @param size The number of bytes to write 00067 * @return The number of bytes written, negative error on failure 00068 */ 00069 virtual ssize_t write(const void *buffer, size_t size) = 0; 00070 00071 /** Move the file position to a given offset from from a given location 00072 * 00073 * @param offset The offset from whence to move to 00074 * @param whence The start of where to seek 00075 * SEEK_SET to start from beginning of file, 00076 * SEEK_CUR to start from current position in file, 00077 * SEEK_END to start from end of file 00078 * @return The new offset of the file, negative error code on failure 00079 */ 00080 virtual off_t seek(off_t offset, int whence = SEEK_SET) = 0; 00081 00082 /** Close a file 00083 * 00084 * @return 0 on success, negative error code on failure 00085 */ 00086 virtual int close() = 0; 00087 00088 /** Flush any buffers associated with the file 00089 * 00090 * @return 0 on success, negative error code on failure 00091 */ 00092 virtual int sync() 00093 { 00094 return 0; 00095 } 00096 00097 /** Check if the file in an interactive terminal device 00098 * 00099 * @return True if the file is a terminal 00100 * @return False if the file is not a terminal 00101 * @return Negative error code on failure 00102 */ 00103 virtual int isatty() 00104 { 00105 return false; 00106 } 00107 00108 /** Get the file position of the file 00109 * 00110 * @note This is equivalent to seek(0, SEEK_CUR) 00111 * 00112 * @return The current offset in the file, negative error code on failure 00113 */ 00114 virtual off_t tell() 00115 { 00116 return seek(0, SEEK_CUR); 00117 } 00118 00119 /** Rewind the file position to the beginning of the file 00120 * 00121 * @note This is equivalent to seek(0, SEEK_SET) 00122 */ 00123 virtual void rewind() 00124 { 00125 seek(0, SEEK_SET); 00126 } 00127 00128 /** Get the size of the file 00129 * 00130 * @return Size of the file in bytes 00131 */ 00132 virtual off_t size(); 00133 00134 /** Move the file position to a given offset from a given location. 00135 * 00136 * @param offset The offset from whence to move to 00137 * @param whence SEEK_SET for the start of the file, SEEK_CUR for the 00138 * current file position, or SEEK_END for the end of the file. 00139 * 00140 * @returns 00141 * new file position on success, 00142 * -1 on failure or unsupported 00143 */ 00144 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::seek") 00145 virtual off_t lseek(off_t offset, int whence) 00146 { 00147 return seek(offset, whence); 00148 } 00149 00150 /** Flush any buffers associated with the FileHandle, ensuring it 00151 * is up to date on disk 00152 * 00153 * @returns 00154 * 0 on success or un-needed, 00155 * -1 on error 00156 */ 00157 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::sync") 00158 virtual int fsync() 00159 { 00160 return sync(); 00161 } 00162 00163 /** Find the length of the file 00164 * 00165 * @returns 00166 * Length of the file 00167 */ 00168 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::size") 00169 virtual off_t flen() 00170 { 00171 return size(); 00172 } 00173 00174 /** Set blocking or non-blocking mode of the file operation like read/write. 00175 * Definition depends upon the subclass implementing FileHandle. 00176 * The default is blocking. 00177 * 00178 * @param blocking true for blocking mode, false for non-blocking mode. 00179 * 00180 * @return 0 on success 00181 * @return Negative error code on failure 00182 */ 00183 virtual int set_blocking(bool blocking) 00184 { 00185 return -1; 00186 } 00187 00188 /** Check for poll event flags 00189 * The input parameter can be used or ignored - the could always return all events, 00190 * or could check just the events listed in events. 00191 * Call is non-blocking - returns instantaneous state of events. 00192 * Whenever an event occurs, the derived class should call the sigio() callback). 00193 * 00194 * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc. 00195 * 00196 * @returns bitmask of poll events that have occurred. 00197 */ 00198 virtual short poll(short events) const 00199 { 00200 // Possible default for real files 00201 return POLLIN | POLLOUT; 00202 } 00203 00204 /** Definition depends upon the subclass implementing FileHandle. 00205 * For example, if the FileHandle is of type Stream, writable() could return 00206 * true when there is ample buffer space available for write() calls. 00207 * 00208 * @returns true if the FileHandle is writable. 00209 */ 00210 bool writable() const 00211 { 00212 return poll(POLLOUT) & POLLOUT; 00213 } 00214 00215 /** Definition depends upon the subclass implementing FileHandle. 00216 * For example, if the FileHandle is of type Stream, readable() could return 00217 * true when there is something available to read. 00218 * 00219 * @returns true when there is something available to read. 00220 */ 00221 bool readable() const 00222 { 00223 return poll(POLLIN) & POLLIN; 00224 } 00225 00226 /** Register a callback on state change of the file. 00227 * 00228 * The specified callback will be called on state changes such as when 00229 * the file can be written to or read from. 00230 * 00231 * The callback may be called in an interrupt context and should not 00232 * perform expensive operations. 00233 * 00234 * Note! This is not intended as an attach-like asynchronous api, but rather 00235 * as a building block for constructing such functionality. 00236 * 00237 * The exact timing of when the registered function 00238 * is called is not guaranteed and susceptible to change. It should be used 00239 * as a cue to make read/write/poll calls to find the current state. 00240 * 00241 * @param func Function to call on state change 00242 */ 00243 virtual void sigio(Callback<void()> func) 00244 { 00245 //Default for real files. Do nothing for real files. 00246 } 00247 }; 00248 00249 /** Not a member function 00250 * This call is equivalent to posix fdopen(). 00251 * It associates a Stream to an already opened file descriptor (FileHandle) 00252 * 00253 * @param fh a pointer to an opened file descriptor 00254 * @param mode operation upon the file descriptor, e.g., 'wb+' 00255 * 00256 * @returns a pointer to std::FILE 00257 */ 00258 00259 std::FILE *fdopen(FileHandle *fh, const char *mode); 00260 00261 /**@}*/ 00262 00263 /**@}*/ 00264 00265 00266 } // namespace mbed 00267 00268 #endif
Generated on Sun Jul 17 2022 08:25:23 by 1.7.2