Kyle Wengryn / platform

update

DirHandle.h@0:bfff72fb3650, 2021-04-08 (annotated)

Committer:
kwengryn3
Date:
Thu Apr 08 16:43:07 2021 +0000
Revision:
0:bfff72fb3650
update;

Who changed what in which revision?

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