inc/FIoDirectory.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        FIoDirectory.h
  19  * @brief       This is the header file for the %Directory class.
  20  *
  21  * This header file contains the declarations of the %Directory class.
  22  */
  23
  24 #ifndef _FIO_DIRECTORY_H_
  25 #define _FIO_DIRECTORY_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseTypes.h>
  29 #include <FBaseString.h>
  30 #include <FBaseDateTime.h>
  31 #include <FBaseColArrayList.h>
  32 #include <FIoDirEntry.h>
  33 #include <FIoDirEnumerator.h>
  34
  35 namespace Tizen { namespace Io
  36 {
  37
  38 /**
  39  * @class       Directory
  40  * @brief       This class provides methods for directory operations.
  41  *
  42  * @since       2.0
  43  *
  44  * @final       This class is not intended for extension.
  45  *
  46  * The %Directory class provides methods for directory operations.
  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::DirEntry
  52  * @see     Tizen::Io::File
  53  *
  54  * The following example demonstrates how to use the %Directory class.
  55  *
  56  * @code
  57 #include <FBase.h>
  58 #include <FIo.h>
  59 #include <FApp.h>
  60
  61 using namespace Tizen::Base;
  62 using namespace Tizen::Io;
  63 using namespace Tizen::App;
  64
  65 int main(void)
  66 {
  67         String dirName;
  68         String modifyName;
  69         Directory* pDir;
  70         DirEnumerator* pDirEnum;
  71         result r = E_SUCCESS;
  72
  73         dirName = App::GetInstance()->GetAppDataPath() + L"test";
  74         modifyName = App::GetInstance()->GetAppDataPath() + L"test2";
  75
  76         //------------------------------------------------
  77         // Directory entry traversal example
  78         //------------------------------------------------
  79         pDir = new Directory; // Allocates the %Directory instance
  80
  81         // Open the directory
  82         r = pDir->Construct(dirName);
  83         if (IsFailed(r))
  84         {
  85                 goto CATCH;
  86         }
  87
  88         // Reads all the directory entries
  89         pDirEnum = pDir->ReadN();
  90         if (!pDirEnum)
  91         {
  92                 goto CATCH;
  93         }
  94
  95         // Loops through all the directory entries
  96         while (pDirEnum->MoveNext() == E_SUCCESS)
  97         {
  98                 DirEntry entry = pDirEnum->GetCurrentDirEntry();
  99
 100                 // Do something...
 101         }
 102
 103         // Releases the %Directory instance.
 104         // The opened directory is closed automatically when the destructor of the %Directory class is invoked.
 105         delete pDir;
 106         pDir = null;
 107
 108         //------------------------------------------------
 109         // Renames the directory example
 110         //------------------------------------------------
 111         r = Directory::Rename(dirName, modifyName);
 112         if (IsFailed(r))
 113         {
 114                 goto CATCH;
 115         }
 116         AppLog("Succeeded!");
 117         return 0;
 118
 119 CATCH:
 120         if (pDir)
 121         {
 122                 delete pDir;
 123         }
 124         AppLog("Failed...");
 125         return -1;
 126 }
 127  * @endcode
 128  *
 129  */
 130
 131 class _OSP_EXPORT_ Directory
 132         : public Tizen::Base::Object
 133 {
 134
 135 public:
 136         /**
 137         * The object is not fully constructed after this constructor is called. @n
 138         * For full construction, the Construct() method must be called right after calling this constructor.
 139         *
 140         * @since        2.0
 141         *
 142         * @remarks      After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 143         */
 144         Directory(void);
 145
 146         /**
 147         * This destructor overrides Tizen::Base::Object::~Object().
 148         *
 149         * @since        2.0
 150         */
 151         virtual ~Directory(void);
 152
 153         /**
 154         * Initializes this instance of %Directory with the specified parameter. @n
 155         * The Construct() method safely opens an existing directory using the specified directory name.
 156         *
 157         * @if OSPCOMPAT
 158         * @brief <i> [Compatibility] </i>
 159         * @endif
 160         * @since                        2.0
 161         * @if OSPCOMPAT
 162         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 163         *                                       For more information, see @ref CompIoPathPage "here".
 164         * @endif
 165         *
 166         * @return                       An error code
 167         * @param[in]            dirPath                         The path to the directory to open
 168         * @exception            E_SUCCESS                       The method is successful.
 169         * @exception            E_INVALID_ARG           Either of the following conditions has occurred:
 170         *                                                                               - The length of the specified path is @c 0 or exceeds system limitations.
 171         *                                                                               - The specified path contains prohibited character(s).
 172         *                                                                               - The specified path is invalid.
 173         * @exception            E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
 174         * @exception            E_FILE_NOT_FOUND        An entry for the specified file or path cannot be found.
 175         * @exception            E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 176         * @exception            E_IO                            Either of the following conditions has occurred:
 177         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly.
 178         *                                                                               - %File corruption is detected.
 179         */
 180         result Construct(const Tizen::Base::String& dirPath);
 181
 182         /**
 183         * Reads all the directory entries from the current directory and then returns a DirEnumerator instance that is used to traverse each directory entry.
 184         *
 185         * @since                        2.0
 186         *
 187         * @return                       A pointer to the DirEnumerator object that provides a way to access the collection of a directory entry list, @n
 188         *                                       else @c null if an exception occurs
 189         * @exception        E_SUCCESS                   The method is successful.
 190         * @exception        E_ILLEGAL_ACCESS    The access is denied due to insufficient permission.
 191         * @exception        E_MAX_EXCEEDED              The number of opened files has exceeded the maximum limit.
 192         * @exception            E_IO                            Either of the following conditions has occurred:
 193         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly.
 194         *                                                                               - %File corruption is detected.
 195         * @remarks
 196         *                                       - The returned enumeration objects should be released by the caller.
 197         *                                       - The specific error code can be accessed using the GetLastResult() method.
 198         */
 199         DirEnumerator* ReadN(void);
 200
 201         /**
 202         * Creates a new directory.
 203         *
 204         * @if OSPCOMPAT
 205         * @brief <i> [Compatibility] </i>
 206         * @endif
 207         * @since                        2.0
 208         * @if OSPCOMPAT
 209         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 210         *                                       For more information, see @ref CompIoPathPage "here".
 211         * @endif
 212         *
 213         * @return                       An error code
 214         * @param[in]            dirPath                                 The path to create the directory
 215         * @param[in]            createParentDirectories Set to @c true to create the non-existing parent directories automatically
 216         *                                           up to the destination, @n
 217         *                                           else @c false to throw an exception in case of absent parent directory
 218         * @exception            E_SUCCESS                               The method is successful.
 219         * @exception            E_INVALID_ARG                   Either of the following conditions has occurred:
 220         *                                                                                       - The length of the specified path is @c 0 or exceeds system limitations.
 221         *                                                                                       - The specified path is invalid.
 222         * @exception            E_ILLEGAL_ACCESS                The access is denied due to insufficient permission.
 223         * @exception            E_FILE_ALREADY_EXIST    The specified file already exists.
 224         * @exception            E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 225         * @exception            E_STORAGE_FULL                  The disk space is full.
 226         * @exception            E_IO                                    Either of the following conditions has occurred:
 227         *                                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 228         *                                                                                       - %File corruption is detected.
 229         */
 230         static result Create(const Tizen::Base::String& dirPath, bool createParentDirectories = false);
 231
 232         /**
 233         * Deletes the directory specified by the path. @n
 234         * When @c recursive is set to be @c true, it removes all the subdirectories and their contents. @n
 235         * When @c false, this method removes the directory only if it is empty.
 236         *
 237         * @if OSPCOMPAT
 238         * @brief <i> [Compatibility] </i>
 239         * @endif
 240         * @since                        2.0
 241         * @if OSPCOMPAT
 242         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 243         *                                       For more information, see @ref CompIoPathPage "here".
 244         * @endif
 245         *
 246         * @return                       An error code
 247         * @param[in]            dirPath                                 The path of the directory to remove
 248         * @param[in]            recursive               Set to @c true to remove the sub-directories recursively, @n
 249         *                                                                                       else @c false
 250         * @exception        E_SUCCESS                           The method is successful.
 251         * @exception        E_INVALID_ARG                       Either of the following conditions has occurred:
 252         *                                                                                       - The length of the specified path is @c 0 or exceeds
 253         *                                                                                         system limitations.
 254         *                                                                                       - The specified @c dirPath is not directory path.
 255         * @exception            E_ILLEGAL_ACCESS                The access is denied due to insufficient permission.
 256         * @exception            E_FILE_NOT_FOUND                The specified @c dirPath cannot be found.
 257         * @exception            E_FILE_ALREADY_EXIST    The specified directory already exists.
 258         * @exception            E_MAX_EXCEEDED                  The number of opened directories has exceeded the maximum limit.
 259         * @exception            E_IO                                    Either of the following conditions has occurred:
 260         *                                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 261         *                                                                                       - %File corruption is detected.
 262         */
 263         static result Remove(const Tizen::Base::String& dirPath, bool recursive = false);
 264
 265         /**
 266         * Renames the specified directory to the specified name. @n
 267         * This method is static. @n
 268         * This method does not create parent directories automatically. For example, @b "/CurrentDir" cannot be moved to
 269         * @b "/NewDir/SubDir" if @b "/NewDir" does not already exist. An E_FILE_NOT_FOUND exception is thrown.
 270         *
 271         * @if OSPCOMPAT
 272         * @brief <i> [Compatibility] </i>
 273         * @endif
 274         * @since                        2.0
 275         * @if OSPCOMPAT
 276         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 277         *                                       For more information, see @ref CompIoPathPage "here".
 278         * @endif
 279         *
 280         * @return                       An error code
 281         * @param[in]            orgDirPath                              The original directory path
 282         * @param[in]            newDirPath                              The new directory path
 283         * @exception            E_SUCCESS                               The method is successful.
 284         * @exception            E_INVALID_ARG                   Either of the following conditions has occurred:
 285         *                                                                                       - The length of the specified path is @c 0 or exceeds system limitations.
 286         *                                                                                       - The specified path is invalid.
 287         * @exception            E_ILLEGAL_ACCESS                The access is denied due to insufficient permission.
 288         * @exception            E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 289         * @exception            E_FILE_ALREADY_EXIST    The specified file already exists.
 290         * @exception            E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 291         * @exception            E_STORAGE_FULL                  The disk space is full.
 292         * @exception            E_IO                                    Either of the following conditions has occurred:
 293         *                                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 294         *                                                                                       - %File corruption is detected.
 295         */
 296         static result Rename(const Tizen::Base::String& orgDirPath, const Tizen::Base::String& newDirPath);
 297
 298 private:
 299         /**
 300         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 301         *
 302         * @since        2.0
 303         */
 304         Directory(const Directory& rhs);
 305
 306         /**
 307         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 308         *
 309         * @since        2.0
 310         */
 311         Directory& operator =(const Directory& rhs);
 312
 313         class _DirectoryImpl* __pDirectoryImpl;
 314
 315         friend class _DirectoryImpl;
 316
 317 }; // Directory
 318
 319 }} // Tizen::Io
 320
 321 #endif // _FIO_DIRECTORY_H_
 322