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