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