FileHandle.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00020  * SOFTWARE.
00021  */
00022 #ifndef MBED_FILEHANDLE_H
00023 #define MBED_FILEHANDLE_H
00024 
00025 typedef int FILEHANDLE;
00026 
00027 #include <stdio.h>
00028 
00029 #if defined(__ARMCC_VERSION) || defined(__ICCARM__)
00030 typedef int ssize_t;
00031 typedef long off_t;
00032 
00033 #else
00034 #   include <sys/types.h>
00035 #endif
00036 
00037 namespace mbed {
00038 
00039 /** An OO equivalent of the internal FILEHANDLE variable
00040  *  and associated _sys_* functions.
00041  *
00042  * FileHandle is an abstract class, needing at least sys_write and
00043  *  sys_read to be implmented for a simple interactive device.
00044  *
00045  * No one ever directly tals to/instanciates a FileHandle - it gets
00046  *  created by FileSystem, and wrapped up by stdio.
00047  */
00048 class FileHandle {
00049 
00050 public:
00051     /** Write the contents of a buffer to the file
00052      *
00053      *  @param buffer the buffer to write from
00054      *  @param length the number of characters to write
00055      *
00056      *  @returns
00057      *  The number of characters written (possibly 0) on success, -1 on error.
00058      */
00059     virtual ssize_t write(const void* buffer, size_t length) = 0;
00060 
00061     /** Close the file
00062      *
00063      *  @returns
00064      *  Zero on success, -1 on error.
00065      */
00066     virtual int close() = 0;
00067 
00068     /** Function read
00069      *  Reads the contents of the file into a buffer
00070      *
00071      *  @param buffer the buffer to read in to
00072      *  @param length the number of characters to read
00073      *
00074      *  @returns
00075      *  The number of characters read (zero at end of file) on success, -1 on error.
00076      */
00077     virtual ssize_t read(void* buffer, size_t length) = 0;
00078 
00079     /** Check if the handle is for a interactive terminal device.
00080      * If so, line buffered behaviour is used by default
00081      *
00082      *  @returns
00083      *    1 if it is a terminal,
00084      *    0 otherwise
00085      */
00086     virtual int isatty() = 0;
00087 
00088     /** Move the file position to a given offset from a given location.
00089      *
00090      *  @param offset The offset from whence to move to
00091      *  @param whence SEEK_SET for the start of the file, SEEK_CUR for the
00092      *   current file position, or SEEK_END for the end of the file.
00093      *
00094      *  @returns
00095      *    new file position on success,
00096      *    -1 on failure or unsupported
00097      */
00098     virtual off_t lseek(off_t offset, int whence) = 0;
00099 
00100     /** Flush any buffers associated with the FileHandle, ensuring it
00101      *  is up to date on disk
00102      *
00103      *  @returns
00104      *    0 on success or un-needed,
00105      *   -1 on error
00106      */
00107     virtual int fsync() = 0;
00108 
00109     virtual off_t flen() {
00110         /* remember our current position */
00111         off_t pos = lseek(0, SEEK_CUR);
00112         if(pos == -1) return -1;
00113         /* seek to the end to get the file length */
00114         off_t res = lseek(0, SEEK_END);
00115         /* return to our old position */
00116         lseek(pos, SEEK_SET);
00117         return res;
00118     }
00119 
00120     virtual ~FileHandle();
00121 };
00122 
00123 } // namespace mbed
00124 
00125 #endif
00126