DirHandle.h

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