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