DirHandle.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef MBED_DIRHANDLE_H
00018 #define MBED_DIRHANDLE_H
00019 
00020 #include <stdint.h>
00021 #include "platform/platform.h"
00022 #include "platform/FileHandle.h"
00023 #include "platform/NonCopyable.h"
00024 
00025 namespace mbed {
00026 /** \addtogroup platform */
00027 /** @{*/
00028 /**
00029  * \defgroup platform_DirHandle DirHandle functions
00030  * @{
00031  */
00032 
00033 
00034 /** Represents a directory stream. An opendir function returns
00035  *  objects of this type. The core functions are read and seek,
00036  *  but only a subset needs to be provided.
00037  *
00038  *  If a FileSystemLike class defines the opendir method, then you
00039  *  can access the directories of an object of that type by either:
00040  *  @code
00041  *  DIR *d  = opendir("/example/directory");
00042  *  @endcode
00043  *  or
00044  *  @code
00045  *  DIR *d = opendir("/example");
00046  *  @endcode
00047  *  to open the root of the file system.
00048  *
00049  *  The root directory is considered to contain all FileHandle and
00050  *  FileSystem objects, so the DIR pointer returned by opendir("/")
00051  *  reflects this.
00052  *
00053  *  @note to create a directory, @see Dir
00054  *  @note Synchronization level: Set by subclass
00055  */
00056 class DirHandle : private NonCopyable<DirHandle> {
00057 public:
00058     virtual ~DirHandle() {}
00059 
00060     /** Read the next directory entry
00061      *
00062      *  @param ent      The directory entry to fill out
00063      *  @return         1 on reading a filename, 0 at end of directory, negative error on failure
00064      */
00065     virtual ssize_t read(struct dirent *ent) = 0;
00066 
00067     /** Close a directory
00068      *
00069      *  @return          0 on success, negative error code on failure
00070      */
00071     virtual int close() = 0;
00072 
00073     /** Set the current position of the directory
00074      *
00075      *  @param offset   Offset of the location to seek to,
00076      *                  must be a value returned from tell
00077      */
00078     virtual void seek(off_t offset) = 0;
00079 
00080     /** Get the current position of the directory
00081      *
00082      *  @return         Position of the directory that can be passed to rewind
00083      */
00084     virtual off_t tell() = 0;
00085 
00086     /** Rewind the current position to the beginning of the directory
00087      */
00088     virtual void rewind() = 0;
00089 
00090     /** Get the sizeof the directory
00091      *
00092      *  @return         Number of files in the directory
00093      */
00094     virtual size_t size()
00095     {
00096         off_t off = tell();
00097         size_t size = 0;
00098         struct dirent *ent = new struct dirent;
00099 
00100         rewind();
00101         while (read(ent) > 0) {
00102             size += 1;
00103         }
00104         seek(off);
00105 
00106         delete ent;
00107         return size;
00108     }
00109 
00110     /** Closes the directory.
00111      *
00112      *  @returns
00113      *    0 on success,
00114      *   -1 on error.
00115      *  @deprecated Replaced by `int DirHandle::close()'
00116      */
00117     MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::close")
00118     virtual int closedir()
00119     {
00120         return close();
00121     };
00122 
00123     /** Returns the directory entry at the current position, and
00124      *  advances the position to the next entry.
00125      *
00126      * @returns
00127      *  A pointer to a dirent structure representing the
00128      *  directory entry at the current position, or NULL on reaching
00129      *  end of directory or error.
00130      * @deprecated Replaced by `ssize_t DirHandle::read(struct dirent *ent)
00131      */
00132     MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::read")
00133     virtual struct dirent *readdir()
00134     {
00135         static struct dirent ent;
00136         return (read(&ent) > 0) ? &ent : NULL;
00137     }
00138 
00139     /** Resets the position to the beginning of the directory.
00140      * @deprecated Replaced by `void DirHandle::rewind()'
00141      */
00142     MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::rewind")
00143     virtual void rewinddir()
00144     {
00145         rewind();
00146     }
00147 
00148     /** Returns the current position of the DirHandle.
00149      *
00150      * @returns
00151      *   the current position,
00152      *  -1 on error.
00153      * @deprecated Replaced by `off_t DirHandle::tell()'
00154      */
00155     MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::tell")
00156     virtual off_t telldir()
00157     {
00158         return tell();
00159     }
00160 
00161     /** Sets the position of the DirHandle.
00162      *
00163      *  @param location The location to seek to. Must be a value returned by telldir.
00164      *  @deprecated Replaced by `void DirHandle::seek(off_t offset)'
00165      */
00166     MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by DirHandle::seek")
00167     virtual void seekdir(off_t location)
00168     {
00169         seek(location);
00170     }
00171 };
00172 
00173 /**@}*/
00174 
00175 /**@}*/
00176 } // namespace mbed
00177 
00178 #endif /* MBED_DIRHANDLE_H */