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
 133         *                                       - Use the MoveNext() method to get information from another file or directory to the currently accessed directory.
 134         *                                       - The specific error code can be accessed using the GetLastResult() method.
 135         */
 136         DirEntry GetCurrentDirEntry(void) const;
 137
 138         /**
 139         * Gets a pointer to the object at the current position of a directory entry collection.
 140         *
 141         * @since                    2.0
 142         *
 143         * @return                       A pointer to the DirEntry instance, @n
 144         *                                       else @c null if the current position of the collection is invalid
 145         * @remarks                      Use the MoveNext() method to get information of another file or directory in the currently accessed directory.
 146         */
 147         virtual Tizen::Base::Object* GetCurrent(void) const;
 148
 149         /**
 150         * Moves the current position of the collection to the next position in the currently accessed directory. @n
 151         * When DirEnumerator is instantiated, its initial position is set to @c -1. @n
 152         * Therefore, calling the GetCurrentDirEntry() method without a call to MoveNext() throws an @c E_INVALID_STATE exception,
 153         * and returns a reference to an empty DirEntry instance. @n
 154         * Similarly, calling the GetCurrent() method without a call to MoveNext() returns a @c null pointer to indicate an error condition.
 155         *
 156         * @since                        2.0
 157         *
 158         * @return                       An error code
 159         * @exception            E_SUCCESS                       The method is successful.
 160         * @exception        E_INVALID_ARG               Either of the following conditions has occurred:
 161         *                                                                               - The length of the specified path is @c 0 or exceeds
 162         *                                                                                 system limitations.
 163         *                                                                               - The specified path is invalid.
 164         *                                                                               - The file handle is invalid (the file is closed by another method).
 165         * @exception        E_FILE_NOT_FOUND    An entry for the specified file or path cannot be found.
 166         * @exception        E_MAX_EXCEEDED              The number of opened files has exceeded the maximum limit.
 167         * @exception        E_END_OF_FILE               There are no more directory entries to read.
 168         * @exception        E_ILLEGAL_ACCESS    Access is denied due to insufficient permission.
 169         * @exception            E_IO                            Either of the following conditions has occurred:
 170         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly.
 171         *                                                                               - %File corruption is detected.
 172         */
 173         virtual result MoveNext(void);
 174
 175         /**
 176         * Resets the current position of the collection to @c -1.
 177         *
 178         * @since                        2.0
 179         *
 180         * @return                       An error code
 181         * @exception            E_SUCCESS                       The method is successful.
 182         * @exception            E_INVALID_ARG           The file handle is invalid (the file is closed by another method).
 183         */
 184         virtual result Reset(void);
 185
 186 private:
 187         /**
 188         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 189         *
 190         * @since        2.0
 191         */
 192         DirEnumerator(void);
 193
 194         /**
 195         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 196         *
 197         * @since        2.0
 198         */
 199         DirEnumerator(const DirEnumerator& source);
 200
 201         /**
 202         * This is the copy constructor for this class.
 203         *
 204         * @since        2.0
 205         */
 206         DirEnumerator(const Tizen::Base::String& dirPath);
 207
 208         /**
 209         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 210         *
 211         * @since        2.0
 212         */
 213         DirEnumerator& operator =(const DirEnumerator& source);
 214
 215         DirEntry* __pCurDirEntry;
 216         class _DirEnumeratorImpl* __pDirEnumeratorImpl;
 217
 218         friend class _DirEnumeratorImpl;
 219
 220 }; // DirEnumerator
 221
 222 }} // Tizen::Io
 223
 224 #endif // _FIO_DIR_ENUMERATOR_H_
 225