Simon Cooksey / mbed-os

Pinned to some recent date

drivers/FileHandle.h@0:fb7af294d5d9, 2016-11-17 (annotated)

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Simon Cooksey 0:fb7af294d5d9 1 /* mbed Microcontroller Library
Simon Cooksey 0:fb7af294d5d9 2 * Copyright (c) 2006-2013 ARM Limited
Simon Cooksey 0:fb7af294d5d9 3 *
Simon Cooksey 0:fb7af294d5d9 4 * Licensed under the Apache License, Version 2.0 (the "License");
Simon Cooksey 0:fb7af294d5d9 5 * you may not use this file except in compliance with the License.
Simon Cooksey 0:fb7af294d5d9 6 * You may obtain a copy of the License at
Simon Cooksey 0:fb7af294d5d9 7 *
Simon Cooksey 0:fb7af294d5d9 8 * http://www.apache.org/licenses/LICENSE-2.0
Simon Cooksey 0:fb7af294d5d9 9 *
Simon Cooksey 0:fb7af294d5d9 10 * Unless required by applicable law or agreed to in writing, software
Simon Cooksey 0:fb7af294d5d9 11 * distributed under the License is distributed on an "AS IS" BASIS,
Simon Cooksey 0:fb7af294d5d9 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Simon Cooksey 0:fb7af294d5d9 13 * See the License for the specific language governing permissions and
Simon Cooksey 0:fb7af294d5d9 14 * limitations under the License.
Simon Cooksey 0:fb7af294d5d9 15 */
Simon Cooksey 0:fb7af294d5d9 16 #ifndef MBED_FILEHANDLE_H
Simon Cooksey 0:fb7af294d5d9 17 #define MBED_FILEHANDLE_H
Simon Cooksey 0:fb7af294d5d9 18
Simon Cooksey 0:fb7af294d5d9 19 typedef int FILEHANDLE;
Simon Cooksey 0:fb7af294d5d9 20
Simon Cooksey 0:fb7af294d5d9 21 #include <stdio.h>
Simon Cooksey 0:fb7af294d5d9 22
Simon Cooksey 0:fb7af294d5d9 23 #if defined(__ARMCC_VERSION) || defined(__ICCARM__)
Simon Cooksey 0:fb7af294d5d9 24 typedef int ssize_t;
Simon Cooksey 0:fb7af294d5d9 25 typedef long off_t;
Simon Cooksey 0:fb7af294d5d9 26
Simon Cooksey 0:fb7af294d5d9 27 #else
Simon Cooksey 0:fb7af294d5d9 28 # include <sys/types.h>
Simon Cooksey 0:fb7af294d5d9 29 #endif
Simon Cooksey 0:fb7af294d5d9 30
Simon Cooksey 0:fb7af294d5d9 31 namespace mbed {
Simon Cooksey 0:fb7af294d5d9 32 /** \addtogroup drivers */
Simon Cooksey 0:fb7af294d5d9 33 /** @{*/
Simon Cooksey 0:fb7af294d5d9 34
Simon Cooksey 0:fb7af294d5d9 35 /** An OO equivalent of the internal FILEHANDLE variable
Simon Cooksey 0:fb7af294d5d9 36 * and associated _sys_* functions.
Simon Cooksey 0:fb7af294d5d9 37 *
Simon Cooksey 0:fb7af294d5d9 38 * FileHandle is an abstract class, needing at least sys_write and
Simon Cooksey 0:fb7af294d5d9 39 * sys_read to be implmented for a simple interactive device.
Simon Cooksey 0:fb7af294d5d9 40 *
Simon Cooksey 0:fb7af294d5d9 41 * No one ever directly tals to/instanciates a FileHandle - it gets
Simon Cooksey 0:fb7af294d5d9 42 * created by FileSystem, and wrapped up by stdio.
Simon Cooksey 0:fb7af294d5d9 43 *
Simon Cooksey 0:fb7af294d5d9 44 * @Note Synchronization level: Set by subclass
Simon Cooksey 0:fb7af294d5d9 45 */
Simon Cooksey 0:fb7af294d5d9 46 class FileHandle {
Simon Cooksey 0:fb7af294d5d9 47
Simon Cooksey 0:fb7af294d5d9 48 public:
Simon Cooksey 0:fb7af294d5d9 49 /** Write the contents of a buffer to the file
Simon Cooksey 0:fb7af294d5d9 50 *
Simon Cooksey 0:fb7af294d5d9 51 * @param buffer the buffer to write from
Simon Cooksey 0:fb7af294d5d9 52 * @param length the number of characters to write
Simon Cooksey 0:fb7af294d5d9 53 *
Simon Cooksey 0:fb7af294d5d9 54 * @returns
Simon Cooksey 0:fb7af294d5d9 55 * The number of characters written (possibly 0) on success, -1 on error.
Simon Cooksey 0:fb7af294d5d9 56 */
Simon Cooksey 0:fb7af294d5d9 57 virtual ssize_t write(const void* buffer, size_t length) = 0;
Simon Cooksey 0:fb7af294d5d9 58
Simon Cooksey 0:fb7af294d5d9 59 /** Close the file
Simon Cooksey 0:fb7af294d5d9 60 *
Simon Cooksey 0:fb7af294d5d9 61 * @returns
Simon Cooksey 0:fb7af294d5d9 62 * Zero on success, -1 on error.
Simon Cooksey 0:fb7af294d5d9 63 */
Simon Cooksey 0:fb7af294d5d9 64 virtual int close() = 0;
Simon Cooksey 0:fb7af294d5d9 65
Simon Cooksey 0:fb7af294d5d9 66 /** Function read
Simon Cooksey 0:fb7af294d5d9 67 * Reads the contents of the file into a buffer
Simon Cooksey 0:fb7af294d5d9 68 *
Simon Cooksey 0:fb7af294d5d9 69 * @param buffer the buffer to read in to
Simon Cooksey 0:fb7af294d5d9 70 * @param length the number of characters to read
Simon Cooksey 0:fb7af294d5d9 71 *
Simon Cooksey 0:fb7af294d5d9 72 * @returns
Simon Cooksey 0:fb7af294d5d9 73 * The number of characters read (zero at end of file) on success, -1 on error.
Simon Cooksey 0:fb7af294d5d9 74 */
Simon Cooksey 0:fb7af294d5d9 75 virtual ssize_t read(void* buffer, size_t length) = 0;
Simon Cooksey 0:fb7af294d5d9 76
Simon Cooksey 0:fb7af294d5d9 77 /** Check if the handle is for a interactive terminal device.
Simon Cooksey 0:fb7af294d5d9 78 * If so, line buffered behaviour is used by default
Simon Cooksey 0:fb7af294d5d9 79 *
Simon Cooksey 0:fb7af294d5d9 80 * @returns
Simon Cooksey 0:fb7af294d5d9 81 * 1 if it is a terminal,
Simon Cooksey 0:fb7af294d5d9 82 * 0 otherwise
Simon Cooksey 0:fb7af294d5d9 83 */
Simon Cooksey 0:fb7af294d5d9 84 virtual int isatty() = 0;
Simon Cooksey 0:fb7af294d5d9 85
Simon Cooksey 0:fb7af294d5d9 86 /** Move the file position to a given offset from a given location.
Simon Cooksey 0:fb7af294d5d9 87 *
Simon Cooksey 0:fb7af294d5d9 88 * @param offset The offset from whence to move to
Simon Cooksey 0:fb7af294d5d9 89 * @param whence SEEK_SET for the start of the file, SEEK_CUR for the
Simon Cooksey 0:fb7af294d5d9 90 * current file position, or SEEK_END for the end of the file.
Simon Cooksey 0:fb7af294d5d9 91 *
Simon Cooksey 0:fb7af294d5d9 92 * @returns
Simon Cooksey 0:fb7af294d5d9 93 * new file position on success,
Simon Cooksey 0:fb7af294d5d9 94 * -1 on failure or unsupported
Simon Cooksey 0:fb7af294d5d9 95 */
Simon Cooksey 0:fb7af294d5d9 96 virtual off_t lseek(off_t offset, int whence) = 0;
Simon Cooksey 0:fb7af294d5d9 97
Simon Cooksey 0:fb7af294d5d9 98 /** Flush any buffers associated with the FileHandle, ensuring it
Simon Cooksey 0:fb7af294d5d9 99 * is up to date on disk
Simon Cooksey 0:fb7af294d5d9 100 *
Simon Cooksey 0:fb7af294d5d9 101 * @returns
Simon Cooksey 0:fb7af294d5d9 102 * 0 on success or un-needed,
Simon Cooksey 0:fb7af294d5d9 103 * -1 on error
Simon Cooksey 0:fb7af294d5d9 104 */
Simon Cooksey 0:fb7af294d5d9 105 virtual int fsync() = 0;
Simon Cooksey 0:fb7af294d5d9 106
Simon Cooksey 0:fb7af294d5d9 107 virtual off_t flen() {
Simon Cooksey 0:fb7af294d5d9 108 lock();
Simon Cooksey 0:fb7af294d5d9 109 /* remember our current position */
Simon Cooksey 0:fb7af294d5d9 110 off_t pos = lseek(0, SEEK_CUR);
Simon Cooksey 0:fb7af294d5d9 111 if(pos == -1) {
Simon Cooksey 0:fb7af294d5d9 112 unlock();
Simon Cooksey 0:fb7af294d5d9 113 return -1;
Simon Cooksey 0:fb7af294d5d9 114 }
Simon Cooksey 0:fb7af294d5d9 115 /* seek to the end to get the file length */
Simon Cooksey 0:fb7af294d5d9 116 off_t res = lseek(0, SEEK_END);
Simon Cooksey 0:fb7af294d5d9 117 /* return to our old position */
Simon Cooksey 0:fb7af294d5d9 118 lseek(pos, SEEK_SET);
Simon Cooksey 0:fb7af294d5d9 119 unlock();
Simon Cooksey 0:fb7af294d5d9 120 return res;
Simon Cooksey 0:fb7af294d5d9 121 }
Simon Cooksey 0:fb7af294d5d9 122
Simon Cooksey 0:fb7af294d5d9 123 virtual ~FileHandle();
Simon Cooksey 0:fb7af294d5d9 124
Simon Cooksey 0:fb7af294d5d9 125 protected:
Simon Cooksey 0:fb7af294d5d9 126
Simon Cooksey 0:fb7af294d5d9 127 /** Acquire exclusive access to this object.
Simon Cooksey 0:fb7af294d5d9 128 */
Simon Cooksey 0:fb7af294d5d9 129 virtual void lock() {
Simon Cooksey 0:fb7af294d5d9 130 // Stub
Simon Cooksey 0:fb7af294d5d9 131 }
Simon Cooksey 0:fb7af294d5d9 132
Simon Cooksey 0:fb7af294d5d9 133 /** Release exclusive access to this object.
Simon Cooksey 0:fb7af294d5d9 134 */
Simon Cooksey 0:fb7af294d5d9 135 virtual void unlock() {
Simon Cooksey 0:fb7af294d5d9 136 // Stub
Simon Cooksey 0:fb7af294d5d9 137 }
Simon Cooksey 0:fb7af294d5d9 138 };
Simon Cooksey 0:fb7af294d5d9 139
Simon Cooksey 0:fb7af294d5d9 140 } // namespace mbed
Simon Cooksey 0:fb7af294d5d9 141
Simon Cooksey 0:fb7af294d5d9 142 #endif
Simon Cooksey 0:fb7af294d5d9 143
Simon Cooksey 0:fb7af294d5d9 144 /** @}*/