Elijah Stanger-Jones / mbed-dev-f303

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

platform/DirHandle.h@2:4364577b5ad8, 2020-11-09 (annotated)

Committer:
elijahsj
Date:
Mon Nov 09 00:33:19 2020 -0500
Revision:
2:4364577b5ad8
Parent:
1:8a094db1347f 
copied mbed library

Who changed what in which revision?

UserRevisionLine numberNew contents of line
elijahsj 1:8a094db1347f 1 /* mbed Microcontroller Library
elijahsj 1:8a094db1347f 2 * Copyright (c) 2006-2013 ARM Limited
elijahsj 1:8a094db1347f 3 *
elijahsj 1:8a094db1347f 4 * Licensed under the Apache License, Version 2.0 (the "License");
elijahsj 1:8a094db1347f 5 * you may not use this file except in compliance with the License.
elijahsj 1:8a094db1347f 6 * You may obtain a copy of the License at
elijahsj 1:8a094db1347f 7 *
elijahsj 1:8a094db1347f 8 * http://www.apache.org/licenses/LICENSE-2.0
elijahsj 1:8a094db1347f 9 *
elijahsj 1:8a094db1347f 10 * Unless required by applicable law or agreed to in writing, software
elijahsj 1:8a094db1347f 11 * distributed under the License is distributed on an "AS IS" BASIS,
elijahsj 1:8a094db1347f 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
elijahsj 1:8a094db1347f 13 * See the License for the specific language governing permissions and
elijahsj 1:8a094db1347f 14 * limitations under the License.
elijahsj 1:8a094db1347f 15 */
elijahsj 1:8a094db1347f 16 #ifndef MBED_DIRHANDLE_H
elijahsj 1:8a094db1347f 17 #define MBED_DIRHANDLE_H
elijahsj 1:8a094db1347f 18
elijahsj 1:8a094db1347f 19 #include <stdint.h>
elijahsj 1:8a094db1347f 20 #include "platform/platform.h"
elijahsj 1:8a094db1347f 21 #include "platform/FileHandle.h"
elijahsj 1:8a094db1347f 22 #include "platform/NonCopyable.h"
elijahsj 1:8a094db1347f 23
elijahsj 1:8a094db1347f 24 namespace mbed {
elijahsj 1:8a094db1347f 25 /** \addtogroup platform */
elijahsj 1:8a094db1347f 26
elijahsj 1:8a094db1347f 27
elijahsj 1:8a094db1347f 28 /** Represents a directory stream. Objects of this type are returned
elijahsj 1:8a094db1347f 29 * by an opendir function. The core functions are read and seek,
elijahsj 1:8a094db1347f 30 * but only a subset needs to be provided.
elijahsj 1:8a094db1347f 31 *
elijahsj 1:8a094db1347f 32 * If a FileSystemLike class defines the opendir method, then the
elijahsj 1:8a094db1347f 33 * directories of an object of that type can be accessed by
elijahsj 1:8a094db1347f 34 * DIR *d = opendir("/example/directory") (or opendir("/example")
elijahsj 1:8a094db1347f 35 * to open the root of the filesystem), and then using readdir(d) etc.
elijahsj 1:8a094db1347f 36 *
elijahsj 1:8a094db1347f 37 * The root directory is considered to contain all FileHandle and
elijahsj 1:8a094db1347f 38 * FileSystem objects, so the DIR* returned by opendir("/") will
elijahsj 1:8a094db1347f 39 * reflect this.
elijahsj 1:8a094db1347f 40 *
elijahsj 1:8a094db1347f 41 * @note to create a directory, @see Dir
elijahsj 1:8a094db1347f 42 * @note Synchronization level: Set by subclass
elijahsj 1:8a094db1347f 43 * @ingroup platform
elijahsj 1:8a094db1347f 44 */
elijahsj 1:8a094db1347f 45 class DirHandle : private NonCopyable<DirHandle> {
elijahsj 1:8a094db1347f 46 public:
elijahsj 1:8a094db1347f 47 virtual ~DirHandle() {}
elijahsj 1:8a094db1347f 48
elijahsj 1:8a094db1347f 49 /** Read the next directory entry
elijahsj 1:8a094db1347f 50 *
elijahsj 1:8a094db1347f 51 * @param ent The directory entry to fill out
elijahsj 1:8a094db1347f 52 * @return 1 on reading a filename, 0 at end of directory, negative error on failure
elijahsj 1:8a094db1347f 53 */
elijahsj 1:8a094db1347f 54 virtual ssize_t read(struct dirent *ent) = 0;
elijahsj 1:8a094db1347f 55
elijahsj 1:8a094db1347f 56 /** Close a directory
elijahsj 1:8a094db1347f 57 *
elijahsj 1:8a094db1347f 58 * @return 0 on success, negative error code on failure
elijahsj 1:8a094db1347f 59 */
elijahsj 1:8a094db1347f 60 virtual int close() = 0;
elijahsj 1:8a094db1347f 61
elijahsj 1:8a094db1347f 62 /** Set the current position of the directory
elijahsj 1:8a094db1347f 63 *
elijahsj 1:8a094db1347f 64 * @param offset Offset of the location to seek to,
elijahsj 1:8a094db1347f 65 * must be a value returned from tell
elijahsj 1:8a094db1347f 66 */
elijahsj 1:8a094db1347f 67 virtual void seek(off_t offset) = 0;
elijahsj 1:8a094db1347f 68
elijahsj 1:8a094db1347f 69 /** Get the current position of the directory
elijahsj 1:8a094db1347f 70 *
elijahsj 1:8a094db1347f 71 * @return Position of the directory that can be passed to rewind
elijahsj 1:8a094db1347f 72 */
elijahsj 1:8a094db1347f 73 virtual off_t tell() = 0;
elijahsj 1:8a094db1347f 74
elijahsj 1:8a094db1347f 75 /** Rewind the current position to the beginning of the directory
elijahsj 1:8a094db1347f 76 */
elijahsj 1:8a094db1347f 77 virtual void rewind() = 0;
elijahsj 1:8a094db1347f 78
elijahsj 1:8a094db1347f 79 /** Get the sizeof the directory
elijahsj 1:8a094db1347f 80 *
elijahsj 1:8a094db1347f 81 * @return Number of files in the directory
elijahsj 1:8a094db1347f 82 */
elijahsj 1:8a094db1347f 83 virtual size_t size()
elijahsj 1:8a094db1347f 84 {
elijahsj 1:8a094db1347f 85 off_t off = tell();
elijahsj 1:8a094db1347f 86 size_t size = 0;
elijahsj 1:8a094db1347f 87 struct dirent *ent = new struct dirent;
elijahsj 1:8a094db1347f 88
elijahsj 1:8a094db1347f 89 rewind();
elijahsj 1:8a094db1347f 90 while (read(ent) > 0) {
elijahsj 1:8a094db1347f 91 size += 1;
elijahsj 1:8a094db1347f 92 }
elijahsj 1:8a094db1347f 93 seek(off);
elijahsj 1:8a094db1347f 94
elijahsj 1:8a094db1347f 95 delete ent;
elijahsj 1:8a094db1347f 96 return size;
elijahsj 1:8a094db1347f 97 }
elijahsj 1:8a094db1347f 98
elijahsj 1:8a094db1347f 99 /** Closes the directory.
elijahsj 1:8a094db1347f 100 *
elijahsj 1:8a094db1347f 101 * @returns
elijahsj 1:8a094db1347f 102 * 0 on success,
elijahsj 1:8a094db1347f 103 * -1 on error.
elijahsj 1:8a094db1347f 104 */
elijahsj 1:8a094db1347f 105 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::close")
elijahsj 1:8a094db1347f 106 virtual int closedir() { return close(); };
elijahsj 1:8a094db1347f 107
elijahsj 1:8a094db1347f 108 /** Return the directory entry at the current position, and
elijahsj 1:8a094db1347f 109 * advances the position to the next entry.
elijahsj 1:8a094db1347f 110 *
elijahsj 1:8a094db1347f 111 * @returns
elijahsj 1:8a094db1347f 112 * A pointer to a dirent structure representing the
elijahsj 1:8a094db1347f 113 * directory entry at the current position, or NULL on reaching
elijahsj 1:8a094db1347f 114 * end of directory or error.
elijahsj 1:8a094db1347f 115 */
elijahsj 1:8a094db1347f 116 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::read")
elijahsj 1:8a094db1347f 117 virtual struct dirent *readdir()
elijahsj 1:8a094db1347f 118 {
elijahsj 1:8a094db1347f 119 static struct dirent ent;
elijahsj 1:8a094db1347f 120 return (read(&ent) > 0) ? &ent : NULL;
elijahsj 1:8a094db1347f 121 }
elijahsj 1:8a094db1347f 122
elijahsj 1:8a094db1347f 123 /** Resets the position to the beginning of the directory.
elijahsj 1:8a094db1347f 124 */
elijahsj 1:8a094db1347f 125 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::rewind")
elijahsj 1:8a094db1347f 126 virtual void rewinddir() { rewind(); }
elijahsj 1:8a094db1347f 127
elijahsj 1:8a094db1347f 128 /** Returns the current position of the DirHandle.
elijahsj 1:8a094db1347f 129 *
elijahsj 1:8a094db1347f 130 * @returns
elijahsj 1:8a094db1347f 131 * the current position,
elijahsj 1:8a094db1347f 132 * -1 on error.
elijahsj 1:8a094db1347f 133 */
elijahsj 1:8a094db1347f 134 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::tell")
elijahsj 1:8a094db1347f 135 virtual off_t telldir() { return tell(); }
elijahsj 1:8a094db1347f 136
elijahsj 1:8a094db1347f 137 /** Sets the position of the DirHandle.
elijahsj 1:8a094db1347f 138 *
elijahsj 1:8a094db1347f 139 * @param location The location to seek to. Must be a value returned by telldir.
elijahsj 1:8a094db1347f 140 */
elijahsj 1:8a094db1347f 141 MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::seek")
elijahsj 1:8a094db1347f 142 virtual void seekdir(off_t location) { seek(location); }
elijahsj 1:8a094db1347f 143 };
elijahsj 1:8a094db1347f 144
elijahsj 1:8a094db1347f 145
elijahsj 1:8a094db1347f 146 } // namespace mbed
elijahsj 1:8a094db1347f 147
elijahsj 1:8a094db1347f 148 #endif /* MBED_DIRHANDLE_H */