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