inc/FIoDirEnumerator.h

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