inc/FBaseUtilFileUnzipper.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                FBaseUtilFileUnzipper.h
  19  * @brief               This is the header file for %FileUnzipper class.
  20  *
  21  * This header file contains the declarations of the %FileUnzipper class.
  22  */
  23
  24 #ifndef _FBASE_UTIL_FILE_UNZIPPER_H_
  25 #define _FBASE_UTIL_FILE_UNZIPPER_H_
  26
  27
  28 #include <FBaseString.h>
  29 #include <FBaseUtilZipEntry.h>
  30
  31
  32 namespace Tizen { namespace Base { namespace Utility
  33 {
  34
  35 /**
  36  * @class       FileUnzipper
  37  * @brief       This class provides methods that decompress data from a zip-archive using zlib.
  38  *
  39  * @since 2.0
  40  *
  41  * The %FileUnzipper class provides an unzip operation for a simple and efficient file-based access to a zip-archive.
  42  * It is possible to extract a zipped file completely or partially and access the entry of a zip-archive.
  43  *
  44  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/utility_namespace.htm">Utility</a>.
  45  *
  46  * The following example demonstrates how to use the %FileUnzipper class.
  47  * @code
  48  *      #include <FBase.h>
  49  *
  50  *      using namespace Tizen::App;
  51  *      using namespace Tizen::Base;
  52  *      using namespace Tizen::Base::Utility;
  53  *
  54  *      void
  55  *      MyClass::FileUnzipperSample(void)
  56  *      {
  57  *              int count = 0;
  58  *
  59  *              FileUnzipper unzip;
  60  *              String dataPath = App::GetInstance()->GetAppDataPath();
  61  *              unzip.Construct(dataPath + L"sample.zip");
  62  *
  63  *              // Unzips the zip-archive fully
  64  *              unzip.UnzipTo(dataPath);
  65  *
  66  *              // Unzips the file from the zip-archive
  67  *              unzip.UnzipTo(dataPath + L"Sample/", L"data1.txt");
  68  *
  69  *              // Gets the number of entries
  70  *              count = unzip.GetEntryCount();
  71  *
  72  *      }
  73  * @endcode
  74  */
  75
  76 class _OSP_EXPORT_ FileUnzipper
  77         : public Tizen::Base::Object
  78 {
  79 public:
  80         /**
  81          * The object is not fully constructed after this constructor is called. @n
  82          * For full construction, the Construct() method must be called right after calling this constructor.
  83          *
  84          * @since 2.0
  85          */
  86         FileUnzipper(void);
  87
  88         /**
  89          * This destructor overrides Tizen::Base::Object::~Object().
  90          *
  91          * @since 2.0
  92          */
  93         virtual ~FileUnzipper(void);
  94
  95         /**
  96          * Initializes this instance of %FileUnzipper with the specified filepath. @n
  97          * This method opens a zip file in the read mode.
  98          *
  99          * @if OSPCOMPAT
 100          * @brief <i> [Compatibility] </i>
 101          * @endif
 102          * @since 2.0
 103          * @if OSPCOMPAT
 104          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 105          *                                      For more information, see @ref CompIoPathPage "here".
 106          * @endif
 107          *
 108          * @return                      An error code
 109          * @param [in]          filePath                The path of the file to open or create
 110          * @exception           E_SUCCESS               The method is successful.
 111          * @exception           E_INVALID_ARG           Either of the following conditions has occurred: @n
 112          *                                                                              - The length of the specified path is @c 0 or exceeds system limitations. @n
 113          *                                                                              - The specified path contains prohibited character(s). @n
 114          *                                                                              - The specified path is invalid.
 115          * @exception           E_ILLEGAL_ACCESS        The specified file path is inaccessible as per the %Tizen platform policy.
 116          * @exception           E_FILE_NOT_FOUND        The specified file cannot be found or accessed.
 117          * @exception           E_IO                    An unexpected device failure has occurred.
 118          * @remarks                     The paths for @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"data" and @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"trusted" are not supported.
 119          * @see                         Tizen::Io::File
 120          */
 121         result Construct(const String& filePath);
 122
 123         /**
 124          * Unzips a zip file at the specified path or destination.
 125          *
 126          * @if OSPCOMPAT
 127          * @brief <i> [Compatibility] </i>
 128          * @endif
 129          * @since 2.0
 130          * @if OSPCOMPAT
 131          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 132          *                                      For more information, see @ref CompIoPathPage "here".
 133          * @endif
 134          *
 135          * @return                      An error code
 136          * @param [in]          dirPath                         A directory path to unzip
 137          * @exception           E_SUCCESS                       The method is successful.
 138          * @exception           E_INVALID_ARG           Either of the following conditions has occurred: @n
 139          *                                                                              - The length of the specified path is @c 0 or exceeds system limitations. @n
 140          *                                                                              - The specified path contains prohibited character(s). @n
 141          *                                                                              - The specified path is invalid.
 142          * @exception           E_ILLEGAL_ACCESS        The specified path is not permitted, or
 143          *                                                                              access is denied due to insufficient permission.
 144          * @exception           E_IO                            An unexpected device failure has occurred.
 145          * @remarks                     The paths for @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"data" and @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"trusted" are not supported.
 146          * @remarks                     This operation consumes a lot of time if the zip-archive contains large number of files or
 147          *                                      directories.
 148          *                      In such cases, it is recommended to call this method in a separate thread.
 149          * @see                         Tizen::Io::File
 150          */
 151         result UnzipTo(const String& dirPath) const;
 152
 153         /**
 154          * Unzips a zip entry from a zip-archive to the specified path.
 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                         A directory path to unzip
 167          * @param [in]          zipEntryName            A zip entry name that could be a file or directory name
 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        The specified path is not permitted, or
 174          *                                                                              access is denied due to insufficient permission.
 175          * @exception           E_FILE_NOT_FOUND        The entry of the specified file or path cannot be found in the archive.
 176          * @exception           E_IO                            An unexpected device failure has occurred.
 177          * @remarks                     The paths for @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"data" and @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"trusted" are not supported.
 178          * @remarks                     If the value of @c zipEntryName is a directory name present in the archive, this method
 179          *                                      creates an empty directory. @n
 180          *                                      For example, UnzipTo(Tizen::App::App::GetInstance()->GetAppDataPath() + L"Test/", L"/someDir/") will create @b '[AppDataPath]/Test/someDir'
 181          *                                      directory only, and the files or subdirectories under @b 'someDir' will not be extracted.
 182          * @see                         Tizen::Io::File
 183          */
 184         result UnzipTo(const String& dirPath, const String& zipEntryName) const;
 185
 186         /**
 187          * Gets the number of entries present in a zip-archive.
 188          *
 189          * @since 2.0
 190          *
 191          * @return                      The number of entries present in a zip-archive, @n
 192          *                                      else @c -1 in case of an error
 193          * @exception           E_SUCCESS                       The method is successful.
 194          * @exception           E_IO                            An unexpected device failure has occurred.
 195          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 196          */
 197         int GetEntryCount(void) const;
 198
 199         /**
 200          * Gets the number of files present in a zip-archive.
 201          *
 202          * @since 2.0
 203          *
 204          * @return                      The number of files present in a zip-archive, @n
 205          *                                      else @c -1 in case of an error
 206          * @exception           E_SUCCESS                       The method is successful.
 207          * @exception           E_IO                            An unexpected device failure has occurred.
 208          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 209          */
 210         int GetFileCount(void) const;
 211
 212         /**
 213          * Gets the number of directories present in a zip-archive.
 214          *
 215          * @since 2.0
 216          *
 217          * @return                      The number of directories present in a zip-archive, @n
 218          *                                      else @c -1 in case of an error
 219          * @exception           E_SUCCESS                       The method is successful.
 220          * @exception           E_IO                            An unexpected device failure has occurred.
 221          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 222          */
 223         int GetDirectoryCount(void) const;
 224
 225         /**
 226          * Gets a zip entry associated with the file or directory name passed as parameter.
 227          *
 228          * @since 2.0
 229          *
 230          * @return                      An error code
 231          * @param [in]          zipEntryName            A zip entry name that could be a file or directory name
 232          * @param [out]         entry                           A reference to the ZipEntry
 233          * @exception           E_SUCCESS                       The method is successful.
 234          * @exception           E_INVALID_ARG           Either of the following conditions has occurred: @n
 235          *                                                                              - The length of the specified path is @c 0 or exceeds system limitations. @n
 236          *                                                                              - The specified path contains prohibited character(s). @n
 237          *                                                                              - The specified path is invalid.
 238          * @exception           E_FILE_NOT_FOUND        The entry of the specified file or path cannot be found in the archive.
 239          * @exception           E_IO                            An unexpected device failure has occurred.
 240          * @remarks                     If the value of @c zipEntryName is a directory name, it must have a suffix '/'.
 241          *                                      For example, @b Tizen::App::App::GetInstance()->GetAppDataPath() + L"Test/" or @b Tizen::App::App::GetInstance()->GetAppDataPath() + L"Test/DATA/".
 242          */
 243         result GetEntry(const String& zipEntryName, ZipEntry& entry) const;
 244
 245         /**
 246          * Gets a zip entry associated with the index from the root directory.
 247          *
 248          * @since 2.0
 249          *
 250          * @return                      An error code
 251          * @param [in]      index                               An index of the zip entry to access @n
 252          *                                                                              The index starts from @c 0.
 253          * @param [out]         entry                           A reference to the ZipEntry
 254          * @exception           E_SUCCESS                       The method is successful.
 255          * @exception           E_INVALID_ARG           The specified index is out of range, or an invalid index is passed.
 256          * @exception           E_IO                            An unexpected device failure has occurred.
 257          */
 258         result GetEntry(int index, ZipEntry& entry) const;
 259
 260
 261 private:
 262         /**
 263          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 264          *
 265          * @param [in]  fileUnzipper    The instance of the %FileUnzipper class to copy from
 266          * @remarks             This constructor is hidden.
 267          */
 268         FileUnzipper(const FileUnzipper& fileUnzipper);
 269
 270         /**
 271          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 272          *
 273          * @param [in]  fileUnzipper    An instance of %FileUnzipper
 274          * @remarks             This operator is hidden.
 275          */
 276         FileUnzipper& operator =(const FileUnzipper& fileUnzipper);
 277
 278
 279         friend class _FileUnzipperImpl;
 280         class _FileUnzipperImpl* __pFileUnzipperImpl;
 281
 282 }; // FileUnzipper
 283
 284 }}} // Tizen::Base::Utility
 285
 286 #endif // _FBASE_UTIL_FILE_UNZIPPER_H_