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 to operate on directories.
  41  *
  42  * @since       2.0
  43  *
  44  * @final       This class is not intended for extension.
  45  *
  46  * The %Directory class provides methods to operate on directories.
  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. For full construction, the Construct() method must be called right after calling this constructor.
 138         *
 139         * @since        2.0
 140         *
 141         * @remarks      After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 142         */
 143         Directory(void);
 144
 145         /**
 146         * This destructor overrides Tizen::Base::Object::~Object().
 147         *
 148         * @since        2.0
 149         */
 150         virtual ~Directory(void);
 151
 152         /**
 153         * Initializes this instance of %Directory with the specified parameter. @n
 154         * The Construct() method safely opens an existing directory using the specified directory name.
 155         *
 156         * @if OSPCOMPAT
 157         * @brief <i> [Compatibility] </i>
 158         * @endif
 159         * @since                        2.0
 160         * @if OSPCOMPAT
 161         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 162         *                                       For more information, see @ref CompIoPathPage "here".
 163         * @endif
 164         *
 165         * @return                       An error code
 166         * @param[in]            dirPath                         The path to the directory to open
 167         * @exception            E_SUCCESS                       The method is successful.
 168         * @exception            E_INVALID_ARG           Either of the following conditions has occurred: @n
 169         *                                                                               - The length of the specified path is @c 0 or exceeds system limitations. @n
 170         *                                                                               - The specified path contains prohibited character(s). @n
 171         *                                                                               - The specified path is invalid.
 172         * @exception            E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 173         * @exception            E_FILE_NOT_FOUND        An entry for the specified file or path cannot be found.
 174         * @exception            E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 175         * @exception            E_IO                            Either of the following conditions has occurred: @n
 176         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 177         *                                                                               - %File corruption is detected.
 178         */
 179         result Construct(const Tizen::Base::String& dirPath);
 180
 181         /**
 182         * Reads all the directory entries from the current directory and then returns a DirEnumerator instance that is used to traverse each directory entry.
 183         *
 184         * @since                        2.0
 185         *
 186         * @return                       A pointer to the DirEnumerator object that provides a way to access the collection of a directory entry list, @n
 187         *                                       else @c null if an exception occurs
 188         * @exception        E_SUCCESS                   The method is successful.
 189         * @exception        E_ILLEGAL_ACCESS    Access is denied due to insufficient permission.
 190         * @exception        E_MAX_EXCEEDED              The number of opened files has exceeded the maximum limit.
 191         * @exception            E_IO                            Either of the following conditions has occurred: @n
 192         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 193         *                                                                               - %File corruption is detected.
 194         * @remarks                      The returned enumeration objects should be released by the caller. @n
 195         *                                       The specific error code can be accessed using the GetLastResult() method.
 196         */
 197         DirEnumerator* ReadN(void);
 198
 199         /**
 200         * Creates a new directory.
 201         *
 202         * @if OSPCOMPAT
 203         * @brief <i> [Compatibility] </i>
 204         * @endif
 205         * @since                        2.0
 206         * @if OSPCOMPAT
 207         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 208         *                                       For more information, see @ref CompIoPathPage "here".
 209         * @endif
 210         *
 211         * @return                       An error code
 212         * @param[in]            dirPath                                 The path at which the directory is created
 213         * @param[in]            createParentDirectories Set to @c true if the non-existing parent directories are created automatically
 214         *                                           up to the destination, @n
 215         *                                           else @c false if an absent parent directory causes an exception
 216         * @exception            E_SUCCESS                               The method is successful.
 217         * @exception            E_INVALID_ARG                   Either of the following conditions has occurred: @n
 218         *                                                                                       - The length of the specified path is @c 0 or exceeds system limitations. @n
 219         *                                                                                       - The specified path is invalid.
 220         * @exception            E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 221         * @exception            E_FILE_ALREADY_EXIST    The specified file already exists.
 222         * @exception            E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 223         * @exception            E_STORAGE_FULL                  The disk space is full.
 224         * @exception            E_IO                                    Either of the following conditions has occurred: @n
 225         *                                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 226         *                                                                                       - %File corruption is detected.
 227         */
 228         static result Create(const Tizen::Base::String& dirPath, bool createParentDirectories = false);
 229
 230         /**
 231         * Deletes the directory specified by the path. @n
 232         * When @c recursive is set to be @c true, it removes all the subdirectories and their contents. @n
 233         * When @c false, this method removes the directory only if it is empty.
 234         *
 235         * @if OSPCOMPAT
 236         * @brief <i> [Compatibility] </i>
 237         * @endif
 238         * @since                        2.0
 239         * @if OSPCOMPAT
 240         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 241         *                                       For more information, see @ref CompIoPathPage "here".
 242         * @endif
 243         *
 244         * @return                       An error code
 245         * @param[in]            dirPath                                 The path of the directory to remove
 246         * @param[in]            recursive               Set to @c true to remove the sub-directories recursively, @n
 247         *                                                                                       else @c false
 248         * @exception        E_SUCCESS                           The method is successful.
 249         * @exception        E_INVALID_ARG                       Either of the following conditions has occurred: @n
 250         *                                                                                       - The length of the specified path is @c 0 or exceeds
 251         *                                                                                         system limitations. @n
 252         *                                                                                       - The specified @c dirPath is not directory path.
 253         * @exception            E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 254         * @exception            E_FILE_NOT_FOUND                The specified @c dirPath cannot be found.
 255         * @exception            E_FILE_ALREADY_EXIST    The specified directory already exists.
 256         * @exception            E_MAX_EXCEEDED                  The number of opened directories has exceeded the maximum limit.
 257         * @exception            E_IO                                    Either of the following conditions has occurred: @n
 258         *                                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 259         *                                                                                       - %File corruption is detected.
 260         */
 261         static result Remove(const Tizen::Base::String& dirPath, bool recursive = false);
 262
 263         /**
 264         * Renames the specified directory to the specified name. @n
 265         * This method is static. @n
 266         * This method does not create parent directories automatically. For example, @b "/CurrentDir" cannot be moved to
 267         * @b "/NewDir/SubDir" if @b "/NewDir" does not already exist. An E_FILE_NOT_FOUND exception is thrown.
 268         *
 269         * @if OSPCOMPAT
 270         * @brief <i> [Compatibility] </i>
 271         * @endif
 272         * @since                        2.0
 273         * @if OSPCOMPAT
 274         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 275         *                                       For more information, see @ref CompIoPathPage "here".
 276         * @endif
 277         *
 278         * @return                       An error code
 279         * @param[in]            orgDirPath                              The original directory path
 280         * @param[in]            newDirPath                              The new directory path
 281         * @exception            E_SUCCESS                               The method is successful.
 282         * @exception            E_INVALID_ARG                   Either of the following conditions has occurred: @n
 283         *                                                                                       - The length of the specified path is @c 0 or exceeds system limitations. @n
 284         *                                                                                       - The specified path is invalid.
 285         * @exception            E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 286         * @exception            E_FILE_NOT_FOUND                An entry for the specified file or path cannot be found.
 287         * @exception            E_FILE_ALREADY_EXIST    The specified file already exists.
 288         * @exception            E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 289         * @exception            E_STORAGE_FULL                  The disk space is full.
 290         * @exception            E_IO                                    Either of the following conditions has occurred: @n
 291         *                                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 292         *                                                                                       - %File corruption is detected.
 293         */
 294         static result Rename(const Tizen::Base::String& orgDirPath, const Tizen::Base::String& newDirPath);
 295
 296 private:
 297         /**
 298         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 299         *
 300         * @since        2.0
 301         */
 302         Directory(const Directory& rhs);
 303
 304         /**
 305         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 306         *
 307         * @since        2.0
 308         */
 309         Directory& operator =(const Directory& rhs);
 310
 311         class _DirectoryImpl* __pDirectoryImpl;
 312
 313         friend class _DirectoryImpl;
 314
 315 }; // Directory
 316
 317 }} // Tizen::Io
 318
 319 #endif // _FIO_DIRECTORY_H_
 320