DirHandle.h

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