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-2013 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/platform.h"
22 #include "platform/FileHandle.h"
23 #include "platform/NonCopyable.h"
24 
25 namespace mbed {
26 /** \addtogroup platform */
27 /** @{*/
28 /**
29  * \defgroup platform_DirHandle DirHandle functions
30  * @{
31  */
32 
33 
34 /** Represents a directory stream. An opendir function returns
35  * objects of this type. The core functions are read and seek,
36  * but only a subset needs to be provided.
37  *
38  * If a FileSystemLike class defines the opendir method, then you
39  * can access the directories of an object of that type by either:
40  * @code
41  * DIR *d = opendir("/example/directory");
42  * @endcode
43  * or
44  * @code
45  * DIR *d = opendir("/example");
46  * @endcode
47  * to open the root of the file system.
48  *
49  * The root directory is considered to contain all FileHandle and
50  * FileSystem objects, so the DIR pointer returned by opendir("/")
51  * reflects this.
52  *
53  * @note to create a directory, @see Dir
54  * @note Synchronization level: Set by subclass
55  */
56 class DirHandle : private NonCopyable<DirHandle> {
57 public:
58  virtual ~DirHandle() {}
59 
60  /** Read the next directory entry
61  *
62  * @param ent The directory entry to fill out
63  * @return 1 on reading a filename, 0 at end of directory, negative error on failure
64  */
65  virtual ssize_t read(struct dirent *ent) = 0;
66 
67  /** Close a directory
68  *
69  * @return 0 on success, negative error code on failure
70  */
71  virtual int close() = 0;
72 
73  /** Set the current position of the directory
74  *
75  * @param offset Offset of the location to seek to,
76  * must be a value returned from tell
77  */
78  virtual void seek(off_t offset) = 0;
79 
80  /** Get the current position of the directory
81  *
82  * @return Position of the directory that can be passed to rewind
83  */
84  virtual off_t tell() = 0;
85 
86  /** Rewind the current position to the beginning of the directory
87  */
88  virtual void rewind() = 0;
89 
90  /** Get the sizeof the directory
91  *
92  * @return Number of files in the directory
93  */
94  virtual size_t size()
95  {
96  off_t off = tell();
97  size_t size = 0;
98  struct dirent *ent = new struct dirent;
99 
100  rewind();
101  while (read(ent) > 0) {
102  size += 1;
103  }
104  seek(off);
105 
106  delete ent;
107  return size;
108  }
109 
110  /** Closes the directory.
111  *
112  * @returns
113  * 0 on success,
114  * -1 on error.
115  * @deprecated Replaced by `int DirHandle::close()'
116  */
117  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::close")
118  virtual int closedir()
119  {
120  return close();
121  };
122 
123  /** Returns the directory entry at the current position, and
124  * advances the position to the next entry.
125  *
126  * @returns
127  * A pointer to a dirent structure representing the
128  * directory entry at the current position, or NULL on reaching
129  * end of directory or error.
130  * @deprecated Replaced by `ssize_t DirHandle::read(struct dirent *ent)
131  */
132  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::read")
133  virtual struct dirent *readdir()
134  {
135  static struct dirent ent;
136  return (read(&ent) > 0) ? &ent : NULL;
137  }
138 
139  /** Resets the position to the beginning of the directory.
140  * @deprecated Replaced by `void DirHandle::rewind()'
141  */
142  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::rewind")
143  virtual void rewinddir()
144  {
145  rewind();
146  }
147 
148  /** Returns the current position of the DirHandle.
149  *
150  * @returns
151  * the current position,
152  * -1 on error.
153  * @deprecated Replaced by `off_t DirHandle::tell()'
154  */
155  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::tell")
156  virtual off_t telldir()
157  {
158  return tell();
159  }
160 
161  /** Sets the position of the DirHandle.
162  *
163  * @param location The location to seek to. Must be a value returned by telldir.
164  * @deprecated Replaced by `void DirHandle::seek(off_t offset)'
165  */
166  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::seek")
167  virtual void seekdir(off_t location)
168  {
169  seek(location);
170  }
171 };
172 
173 /**@}*/
174 
175 /**@}*/
176 } // namespace mbed
177 
178 #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:56
mbed::DirHandle::rewinddir
virtual void rewinddir()
Resets the position to the beginning of the directory.
Definition: DirHandle.h:143
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:168
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:94
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:133
mbed::DirHandle::telldir
virtual off_t telldir()
Returns the current position of the DirHandle.
Definition: DirHandle.h:156
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:118
mbed::DirHandle::seekdir
virtual void seekdir(off_t location)
Sets the position of the DirHandle.
Definition: DirHandle.h:167
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:379
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.