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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.