BA / Mbed OS BaBoRo1

mbed-os/features/filesystem/FileSystem.h@4:75df35ef4fb6, 2018-03-30 (annotated)

Committer:
borlanic
Date:
Fri Mar 30 14:07:05 2018 +0000
Revision:
4:75df35ef4fb6
Parent:
0:380207fcb5c1 
commentar

Who changed what in which revision?

UserRevisionLine numberNew contents of line
borlanic 0:380207fcb5c1 1
borlanic 0:380207fcb5c1 2 /* mbed Microcontroller Library
borlanic 0:380207fcb5c1 3 * Copyright (c) 2006-2013 ARM Limited
borlanic 0:380207fcb5c1 4 *
borlanic 0:380207fcb5c1 5 * Licensed under the Apache License, Version 2.0 (the "License");
borlanic 0:380207fcb5c1 6 * you may not use this file except in compliance with the License.
borlanic 0:380207fcb5c1 7 * You may obtain a copy of the License at
borlanic 0:380207fcb5c1 8 *
borlanic 0:380207fcb5c1 9 * http://www.apache.org/licenses/LICENSE-2.0
borlanic 0:380207fcb5c1 10 *
borlanic 0:380207fcb5c1 11 * Unless required by applicable law or agreed to in writing, software
borlanic 0:380207fcb5c1 12 * distributed under the License is distributed on an "AS IS" BASIS,
borlanic 0:380207fcb5c1 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
borlanic 0:380207fcb5c1 14 * See the License for the specific language governing permissions and
borlanic 0:380207fcb5c1 15 * limitations under the License.
borlanic 0:380207fcb5c1 16 */
borlanic 0:380207fcb5c1 17 #ifndef MBED_FILESYSTEM_H
borlanic 0:380207fcb5c1 18 #define MBED_FILESYSTEM_H
borlanic 0:380207fcb5c1 19
borlanic 0:380207fcb5c1 20 #include "platform/platform.h"
borlanic 0:380207fcb5c1 21
borlanic 0:380207fcb5c1 22 #include "platform/FileBase.h"
borlanic 0:380207fcb5c1 23 #include "platform/FileHandle.h"
borlanic 0:380207fcb5c1 24 #include "platform/DirHandle.h"
borlanic 0:380207fcb5c1 25 #include "platform/FileSystemLike.h"
borlanic 0:380207fcb5c1 26 #include "BlockDevice.h"
borlanic 0:380207fcb5c1 27
borlanic 0:380207fcb5c1 28 namespace mbed {
borlanic 0:380207fcb5c1 29 /** \addtogroup filesystem */
borlanic 0:380207fcb5c1 30 /** @{*/
borlanic 0:380207fcb5c1 31
borlanic 0:380207fcb5c1 32
borlanic 0:380207fcb5c1 33 // Opaque pointer representing files and directories
borlanic 0:380207fcb5c1 34 typedef void *fs_file_t;
borlanic 0:380207fcb5c1 35 typedef void *fs_dir_t;
borlanic 0:380207fcb5c1 36
borlanic 0:380207fcb5c1 37 // Predeclared classes
borlanic 0:380207fcb5c1 38 class Dir;
borlanic 0:380207fcb5c1 39 class File;
borlanic 0:380207fcb5c1 40
borlanic 0:380207fcb5c1 41 /** A filesystem object provides filesystem operations and file operations
borlanic 0:380207fcb5c1 42 * for the File and Dir classes on a block device.
borlanic 0:380207fcb5c1 43 *
borlanic 0:380207fcb5c1 44 * Implementations must provide at minimum file operations and mount
borlanic 0:380207fcb5c1 45 * operations for block devices.
borlanic 0:380207fcb5c1 46 *
borlanic 0:380207fcb5c1 47 * @note Synchronization level: Set by subclass
borlanic 0:380207fcb5c1 48 */
borlanic 0:380207fcb5c1 49 class FileSystem : public FileSystemLike {
borlanic 0:380207fcb5c1 50 public:
borlanic 0:380207fcb5c1 51 /** FileSystem lifetime
borlanic 0:380207fcb5c1 52 *
borlanic 0:380207fcb5c1 53 * @param name Name to add filesystem to tree as
borlanic 0:380207fcb5c1 54 */
borlanic 0:380207fcb5c1 55 FileSystem(const char *name = NULL);
borlanic 0:380207fcb5c1 56 virtual ~FileSystem() {}
borlanic 0:380207fcb5c1 57
borlanic 0:380207fcb5c1 58 /** Mounts a filesystem to a block device
borlanic 0:380207fcb5c1 59 *
borlanic 0:380207fcb5c1 60 * @param bd BlockDevice to mount to
borlanic 0:380207fcb5c1 61 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 62 */
borlanic 0:380207fcb5c1 63 virtual int mount(BlockDevice *bd) = 0;
borlanic 0:380207fcb5c1 64
borlanic 0:380207fcb5c1 65 /** Unmounts a filesystem from the underlying block device
borlanic 0:380207fcb5c1 66 *
borlanic 0:380207fcb5c1 67 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 68 */
borlanic 0:380207fcb5c1 69 virtual int unmount() = 0;
borlanic 0:380207fcb5c1 70
borlanic 0:380207fcb5c1 71 /** Reformats a filesystem, results in an empty and mounted filesystem
borlanic 0:380207fcb5c1 72 *
borlanic 0:380207fcb5c1 73 * @param bd BlockDevice to reformat and mount. If NULL, the mounted
borlanic 0:380207fcb5c1 74 * block device will be used.
borlanic 0:380207fcb5c1 75 * Note: if mount fails, bd must be provided.
borlanic 0:380207fcb5c1 76 * Default: NULL
borlanic 0:380207fcb5c1 77 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 78 */
borlanic 0:380207fcb5c1 79 virtual int reformat(BlockDevice *bd = NULL);
borlanic 0:380207fcb5c1 80
borlanic 0:380207fcb5c1 81 /** Remove a file from the filesystem.
borlanic 0:380207fcb5c1 82 *
borlanic 0:380207fcb5c1 83 * @param path The name of the file to remove.
borlanic 0:380207fcb5c1 84 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 85 */
borlanic 0:380207fcb5c1 86 virtual int remove(const char *path);
borlanic 0:380207fcb5c1 87
borlanic 0:380207fcb5c1 88 /** Rename a file in the filesystem.
borlanic 0:380207fcb5c1 89 *
borlanic 0:380207fcb5c1 90 * @param path The name of the file to rename.
borlanic 0:380207fcb5c1 91 * @param newpath The name to rename it to
borlanic 0:380207fcb5c1 92 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 93 */
borlanic 0:380207fcb5c1 94 virtual int rename(const char *path, const char *newpath);
borlanic 0:380207fcb5c1 95
borlanic 0:380207fcb5c1 96 /** Store information about the file in a stat structure
borlanic 0:380207fcb5c1 97 *
borlanic 0:380207fcb5c1 98 * @param path The name of the file to find information about
borlanic 0:380207fcb5c1 99 * @param st The stat buffer to write to
borlanic 0:380207fcb5c1 100 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 101 */
borlanic 0:380207fcb5c1 102 virtual int stat(const char *path, struct stat *st);
borlanic 0:380207fcb5c1 103
borlanic 0:380207fcb5c1 104 /** Create a directory in the filesystem.
borlanic 0:380207fcb5c1 105 *
borlanic 0:380207fcb5c1 106 * @param path The name of the directory to create.
borlanic 0:380207fcb5c1 107 * @param mode The permissions with which to create the directory
borlanic 0:380207fcb5c1 108 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 109 */
borlanic 0:380207fcb5c1 110 virtual int mkdir(const char *path, mode_t mode);
borlanic 0:380207fcb5c1 111
borlanic 0:380207fcb5c1 112 /** Store information about the mounted filesystem in a statvfs structure
borlanic 0:380207fcb5c1 113 *
borlanic 0:380207fcb5c1 114 * @param path The name of the file to find information about
borlanic 0:380207fcb5c1 115 * @param buf The stat buffer to write to
borlanic 0:380207fcb5c1 116 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 117 */
borlanic 0:380207fcb5c1 118 virtual int statvfs(const char *path, struct statvfs *buf);
borlanic 0:380207fcb5c1 119
borlanic 0:380207fcb5c1 120 protected:
borlanic 0:380207fcb5c1 121 friend class File;
borlanic 0:380207fcb5c1 122 friend class Dir;
borlanic 0:380207fcb5c1 123
borlanic 0:380207fcb5c1 124 /** Open a file on the filesystem
borlanic 0:380207fcb5c1 125 *
borlanic 0:380207fcb5c1 126 * @param file Destination for the handle to a newly created file
borlanic 0:380207fcb5c1 127 * @param path The name of the file to open
borlanic 0:380207fcb5c1 128 * @param flags The flags to open the file in, one of O_RDONLY, O_WRONLY, O_RDWR,
borlanic 0:380207fcb5c1 129 * bitwise or'd with one of O_CREAT, O_TRUNC, O_APPEND
borlanic 0:380207fcb5c1 130 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 131 */
borlanic 0:380207fcb5c1 132 virtual int file_open(fs_file_t *file, const char *path, int flags) = 0;
borlanic 0:380207fcb5c1 133
borlanic 0:380207fcb5c1 134 /** Close a file
borlanic 0:380207fcb5c1 135 *
borlanic 0:380207fcb5c1 136 * @param file File handle
borlanic 0:380207fcb5c1 137 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 138 */
borlanic 0:380207fcb5c1 139 virtual int file_close(fs_file_t file) = 0;
borlanic 0:380207fcb5c1 140
borlanic 0:380207fcb5c1 141 /** Read the contents of a file into a buffer
borlanic 0:380207fcb5c1 142 *
borlanic 0:380207fcb5c1 143 * @param file File handle
borlanic 0:380207fcb5c1 144 * @param buffer The buffer to read in to
borlanic 0:380207fcb5c1 145 * @param size The number of bytes to read
borlanic 0:380207fcb5c1 146 * @return The number of bytes read, 0 at end of file, negative error on failure
borlanic 0:380207fcb5c1 147 */
borlanic 0:380207fcb5c1 148 virtual ssize_t file_read(fs_file_t file, void *buffer, size_t size) = 0;
borlanic 0:380207fcb5c1 149
borlanic 0:380207fcb5c1 150 /** Write the contents of a buffer to a file
borlanic 0:380207fcb5c1 151 *
borlanic 0:380207fcb5c1 152 * @param file File handle
borlanic 0:380207fcb5c1 153 * @param buffer The buffer to write from
borlanic 0:380207fcb5c1 154 * @param size The number of bytes to write
borlanic 0:380207fcb5c1 155 * @return The number of bytes written, negative error on failure
borlanic 0:380207fcb5c1 156 */
borlanic 0:380207fcb5c1 157 virtual ssize_t file_write(fs_file_t file, const void *buffer, size_t size) = 0;
borlanic 0:380207fcb5c1 158
borlanic 0:380207fcb5c1 159 /** Flush any buffers associated with the file
borlanic 0:380207fcb5c1 160 *
borlanic 0:380207fcb5c1 161 * @param file File handle
borlanic 0:380207fcb5c1 162 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 163 */
borlanic 0:380207fcb5c1 164 virtual int file_sync(fs_file_t file);
borlanic 0:380207fcb5c1 165
borlanic 0:380207fcb5c1 166 /** Check if the file in an interactive terminal device
borlanic 0:380207fcb5c1 167 * If so, line buffered behaviour is used by default
borlanic 0:380207fcb5c1 168 *
borlanic 0:380207fcb5c1 169 * @param file File handle
borlanic 0:380207fcb5c1 170 * @return True if the file is a terminal
borlanic 0:380207fcb5c1 171 */
borlanic 0:380207fcb5c1 172 virtual int file_isatty(fs_file_t file);
borlanic 0:380207fcb5c1 173
borlanic 0:380207fcb5c1 174 /** Move the file position to a given offset from from a given location
borlanic 0:380207fcb5c1 175 *
borlanic 0:380207fcb5c1 176 * @param file File handle
borlanic 0:380207fcb5c1 177 * @param offset The offset from whence to move to
borlanic 0:380207fcb5c1 178 * @param whence The start of where to seek
borlanic 0:380207fcb5c1 179 * SEEK_SET to start from beginning of file,
borlanic 0:380207fcb5c1 180 * SEEK_CUR to start from current position in file,
borlanic 0:380207fcb5c1 181 * SEEK_END to start from end of file
borlanic 0:380207fcb5c1 182 * @return The new offset of the file
borlanic 0:380207fcb5c1 183 */
borlanic 0:380207fcb5c1 184 virtual off_t file_seek(fs_file_t file, off_t offset, int whence) = 0;
borlanic 0:380207fcb5c1 185
borlanic 0:380207fcb5c1 186 /** Get the file position of the file
borlanic 0:380207fcb5c1 187 *
borlanic 0:380207fcb5c1 188 * @param file File handle
borlanic 0:380207fcb5c1 189 * @return The current offset in the file
borlanic 0:380207fcb5c1 190 */
borlanic 0:380207fcb5c1 191 virtual off_t file_tell(fs_file_t file);
borlanic 0:380207fcb5c1 192
borlanic 0:380207fcb5c1 193 /** Rewind the file position to the beginning of the file
borlanic 0:380207fcb5c1 194 *
borlanic 0:380207fcb5c1 195 * @param file File handle
borlanic 0:380207fcb5c1 196 * @note This is equivalent to file_seek(file, 0, FS_SEEK_SET)
borlanic 0:380207fcb5c1 197 */
borlanic 0:380207fcb5c1 198 virtual void file_rewind(fs_file_t file);
borlanic 0:380207fcb5c1 199
borlanic 0:380207fcb5c1 200 /** Get the size of the file
borlanic 0:380207fcb5c1 201 *
borlanic 0:380207fcb5c1 202 * @param file File handle
borlanic 0:380207fcb5c1 203 * @return Size of the file in bytes
borlanic 0:380207fcb5c1 204 */
borlanic 0:380207fcb5c1 205 virtual off_t file_size(fs_file_t file);
borlanic 0:380207fcb5c1 206
borlanic 0:380207fcb5c1 207 /** Open a directory on the filesystem
borlanic 0:380207fcb5c1 208 *
borlanic 0:380207fcb5c1 209 * @param dir Destination for the handle to the directory
borlanic 0:380207fcb5c1 210 * @param path Name of the directory to open
borlanic 0:380207fcb5c1 211 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 212 */
borlanic 0:380207fcb5c1 213 virtual int dir_open(fs_dir_t *dir, const char *path);
borlanic 0:380207fcb5c1 214
borlanic 0:380207fcb5c1 215 /** Close a directory
borlanic 0:380207fcb5c1 216 *
borlanic 0:380207fcb5c1 217 * @param dir Dir handle
borlanic 0:380207fcb5c1 218 * @return 0 on success, negative error code on failure
borlanic 0:380207fcb5c1 219 */
borlanic 0:380207fcb5c1 220 virtual int dir_close(fs_dir_t dir);
borlanic 0:380207fcb5c1 221
borlanic 0:380207fcb5c1 222 /** Read the next directory entry
borlanic 0:380207fcb5c1 223 *
borlanic 0:380207fcb5c1 224 * @param dir Dir handle
borlanic 0:380207fcb5c1 225 * @param ent The directory entry to fill out
borlanic 0:380207fcb5c1 226 * @return 1 on reading a filename, 0 at end of directory, negative error on failure
borlanic 0:380207fcb5c1 227 */
borlanic 0:380207fcb5c1 228 virtual ssize_t dir_read(fs_dir_t dir, struct dirent *ent);
borlanic 0:380207fcb5c1 229
borlanic 0:380207fcb5c1 230 /** Set the current position of the directory
borlanic 0:380207fcb5c1 231 *
borlanic 0:380207fcb5c1 232 * @param dir Dir handle
borlanic 0:380207fcb5c1 233 * @param offset Offset of the location to seek to,
borlanic 0:380207fcb5c1 234 * must be a value returned from dir_tell
borlanic 0:380207fcb5c1 235 */
borlanic 0:380207fcb5c1 236 virtual void dir_seek(fs_dir_t dir, off_t offset);
borlanic 0:380207fcb5c1 237
borlanic 0:380207fcb5c1 238 /** Get the current position of the directory
borlanic 0:380207fcb5c1 239 *
borlanic 0:380207fcb5c1 240 * @param dir Dir handle
borlanic 0:380207fcb5c1 241 * @return Position of the directory that can be passed to dir_rewind
borlanic 0:380207fcb5c1 242 */
borlanic 0:380207fcb5c1 243 virtual off_t dir_tell(fs_dir_t dir);
borlanic 0:380207fcb5c1 244
borlanic 0:380207fcb5c1 245 /** Rewind the current position to the beginning of the directory
borlanic 0:380207fcb5c1 246 *
borlanic 0:380207fcb5c1 247 * @param dir Dir handle
borlanic 0:380207fcb5c1 248 */
borlanic 0:380207fcb5c1 249 virtual void dir_rewind(fs_dir_t dir);
borlanic 0:380207fcb5c1 250
borlanic 0:380207fcb5c1 251 /** Get the sizeof the directory
borlanic 0:380207fcb5c1 252 *
borlanic 0:380207fcb5c1 253 * @param dir Dir handle
borlanic 0:380207fcb5c1 254 * @return Number of files in the directory
borlanic 0:380207fcb5c1 255 */
borlanic 0:380207fcb5c1 256 virtual size_t dir_size(fs_dir_t dir);
borlanic 0:380207fcb5c1 257
borlanic 0:380207fcb5c1 258 protected:
borlanic 0:380207fcb5c1 259 // Hooks for FileSystemHandle
borlanic 0:380207fcb5c1 260 virtual int open(FileHandle **file, const char *path, int flags);
borlanic 0:380207fcb5c1 261 virtual int open(DirHandle **dir, const char *path);
borlanic 0:380207fcb5c1 262 };
borlanic 0:380207fcb5c1 263
borlanic 0:380207fcb5c1 264
borlanic 0:380207fcb5c1 265 /** @}*/
borlanic 0:380207fcb5c1 266 } // namespace mbed
borlanic 0:380207fcb5c1 267
borlanic 0:380207fcb5c1 268 #endif