inc/FIoDirEnumerator.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   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
  17 /**
  18  * @file        FIoDirEnumerator.h
  19  * @brief       This is the header file for the %DirEnumerator class.
  20  *
  21  * This header file contains the declarations of the %DirEnumerator class.
  22  */
  23
  24 #ifndef _FIO_DIR_ENUMERATOR_H_
  25 #define _FIO_DIR_ENUMERATOR_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseColIEnumerator.h>
  29
  30 namespace Tizen { namespace Io
  31 {
  32
  33 class DirEntry;
  34
  35 /**
  36  * @class       DirEnumerator
  37  * @brief       This class provides methods to access the collection of a specific directory entry list.
  38  *
  39  * @since       2.0
  40  *
  41  * @final       This class is not intended for extension.
  42  *
  43  * The %DirEnumerator class provides methods to access the collection of a specific directory entry list.
  44  * Generally, %DirEnumerator is instantiated by the Directory::ReadN() method,
  45  * and used to get the %DirEntry instances that have information pertaining to the directory.
  46  *
  47  * For more information on the class features,
  48  * see <a href="../org.tizen.native.appprogramming/html/guide/io/io_namespace.htm">Io Guide</a>.
  49  *
  50  * @see         Tizen::Io::Directory
  51  * @see     Tizen::Io::DirEntry
  52  * @see     Tizen::Io::File
  53  *
  54  * The following example demonstrates how to use the %DirEnumerator class.
  55  *
  56  * @code
  57 #include <FBase.h>
  58 #include <FIo.h>
  59
  60 using namespace Tizen::Base;
  61 using namespace Tizen::Io;
  62
  63 int main(void)
  64 {
  65         String dirName(L"data/test");
  66         Directory dir;
  67         DirEnumerator *pDirEnum = null;
  68         result r = E_SUCCESS;
  69
  70         // Open the directory
  71         r = dir.Construct(Tizen::App::App::GetInstance()->GetAppRootPath() + dirName);
  72         if (IsFailed(r))
  73         {
  74                 goto CATCH;
  75         }
  76
  77         // Read all the directory entries
  78         pDirEnum = dir.ReadN();
  79         if (!pDirEnum)
  80         {
  81                 goto CATCH;
  82         }
  83
  84         // Loop through all the directory entries
  85         while (pDirEnum->MoveNext() == E_SUCCESS)
  86         {
  87                 DirEntry dirEntry = pDirEnum->GetCurrentDirEntry();
  88
  89                 // Do something...
  90         }
  91
  92         // Delete the enumerator
  93         delete pDirEnum;
  94
  95         AppLog("Succeeded");
  96
  97         // The opened directory is closed automatically when the destructor of the Directory class is invoked.
  98         return 0;
  99
 100 CATCH:
 101         if (pDirEnum)
 102         {
 103                 delete pDirEnum;
 104         }
 105         AppLog("Failed...");
 106         return -1;
 107 }
 108  * @endcode
 109  *
 110  */
 111 class _OSP_EXPORT_ DirEnumerator
 112         : public Tizen::Base::Object
 113         , public Tizen::Base::Collection::IEnumerator
 114 {
 115
 116 public:
 117         /**
 118         * This destructor overrides Tizen::Base::Object::~Object().
 119         *
 120         * @since        2.0
 121         */
 122         virtual ~DirEnumerator(void);
 123
 124         /**
 125         * Gets the value of the DirEntry instance in the currently accessed directory.
 126         *
 127         * @since                        2.0
 128         *
 129         * @return                       A reference to the DirEntry instance
 130         * @exception            E_SUCCESS                       The method is successful.
 131         * @exception        E_INVALID_STATE             The current position of the collection is not valid.
 132         * @remarks                      Use the MoveNext() method to get information from another file or directory to the currently accessed directory. @n
 133         *                                       The specific error code can be accessed using the GetLastResult() method.
 134         */
 135         DirEntry GetCurrentDirEntry(void) const;
 136
 137         /**
 138         * Gets the pointer to the object at the current position of a directory entry collection.
 139         *
 140         * @since                    2.0
 141         *
 142         * @return                       A pointer to the DirEntry instance, @n
 143         *                                       else @c null if the current position of the collection is invalid
 144         * @remarks                      Use the MoveNext() method to get information of another file or directory in the currently accessed directory.
 145         */
 146         virtual Tizen::Base::Object* GetCurrent(void) const;
 147
 148         /**
 149         * Moves the current position of the collection to the next position in the currently accessed directory. @n
 150         * When %DirEnumerator is instantiated, its initial position is set to @c -1. @n
 151         * Therefore, calling the GetCurrentDirEntry() method without a call to MoveNext() throws an E_INVALID_STATE exception,
 152         * and returns a reference to an empty DirEntry instance. @n
 153         * Similarly, calling the GetCurrent() method without a call to MoveNext() returns a @c null pointer to indicate an error condition.
 154         *
 155         * @since                        2.0
 156         *
 157         * @return                       An error code
 158         * @exception            E_SUCCESS                       The method is successful.
 159         * @exception        E_INVALID_ARG               Either of the following conditions has occurred: @n
 160         *                                                                               - The length of the specified path is @c 0 or exceeds
 161         *                                                                                 system limitations. @n
 162         *                                                                               - The specified path is invalid. @n
 163         *                                                                               - The file handle is invalid (the file is closed by another method).
 164         * @exception        E_FILE_NOT_FOUND    An entry for the specified file or path cannot be found.
 165         * @exception        E_MAX_EXCEEDED              The number of opened files has exceeded the maximum limit.
 166         * @exception        E_END_OF_FILE               There are no more directory entries to read.
 167         * @exception        E_ILLEGAL_ACCESS    Access is denied due to insufficient permission.
 168         * @exception            E_IO                            Either of the following conditions has occurred: @n
 169         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 170         *                                                                               - %File corruption is detected.
 171         */
 172         virtual result MoveNext(void);
 173
 174         /**
 175         * Resets the current position of the collection to @c -1.
 176         *
 177         * @since                        2.0
 178         *
 179         * @return                       An error code
 180         * @exception            E_SUCCESS                       The method is successful.
 181         * @exception            E_INVALID_ARG           The file handle is invalid (the file is closed by another method).
 182         */
 183         virtual result Reset(void);
 184
 185 private:
 186         /**
 187         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 188         *
 189         * @since        2.0
 190         */
 191         DirEnumerator(void);
 192
 193         /**
 194         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 195         *
 196         * @since        2.0
 197         */
 198         DirEnumerator(const DirEnumerator& source);
 199
 200         /**
 201         * This is the copy constructor for this class.
 202         *
 203         * @since        2.0
 204         */
 205         DirEnumerator(const Tizen::Base::String& dirPath);
 206
 207         /**
 208         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 209         *
 210         * @since        2.0
 211         */
 212         DirEnumerator& operator =(const DirEnumerator& source);
 213
 214         DirEntry* __pCurDirEntry;
 215         class _DirEnumeratorImpl* __pDirEnumeratorImpl;
 216
 217         friend class _DirEnumeratorImpl;
 218
 219 }; // DirEnumerator
 220
 221 }} // Tizen::Io
 222
 223 #endif // _FIO_DIR_ENUMERATOR_H_
 224