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          * The %Construct() 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:
 112          *                                                                              - The length of the specified path is either @c 0 or exceeds system limitations.
 113          *                                                                              - The specified path contains prohibited character(s).
 114          *                                                                              - The specified path is invalid.
 115          * @exception           E_ILLEGAL_ACCESS        The specified @c filePath 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                         The directory path to unzip
 137          * @exception           E_SUCCESS                       The method is successful.
 138          * @exception           E_INVALID_ARG           Either of the following conditions has occurred:
 139          *                                                                              - The length of the specified path is either @c 0 or exceeds system limitations.
 140          *                                                                              - The specified path contains prohibited character(s).
 141          *                                                                              - The specified path is invalid.
 142          * @exception           E_ILLEGAL_ACCESS        Either of the following conditions has occurred:
 143          *                                                                              - The specified path is not permitted.
 144          *                                                                              - The access is denied due to insufficient permission.
 145          * @exception           E_IO                            An unexpected device failure has occurred.
 146          * @remarks
 147          *                                      - The paths for @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"data" and @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"trusted" are not supported.
 148          *                                      - This operation consumes a lot of time if the zip-archive contains large number of files or
 149          *                                      directories. @n
 150          *                                      In such cases, it is recommended to call this method in a separate thread.
 151          * @see                         Tizen::Io::File
 152          */
 153         result UnzipTo(const String& dirPath) const;
 154
 155         /**
 156          * Unzips a zip entry from a zip-archive to the specified path.
 157          *
 158          * @if OSPCOMPAT
 159          * @brief                       <i> [Compatibility] </i>
 160          * @endif
 161          * @since 2.0
 162          * @if OSPCOMPAT
 163          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 164          *                                      For more information, see @ref CompIoPathPage "here".
 165          * @endif
 166          *
 167          * @return                      An error code
 168          * @param [in]          dirPath                         The directory path to unzip
 169          * @param [in]          zipEntryName            The zip entry name that could be a file or a directory name
 170          * @exception           E_SUCCESS                       The method is successful.
 171          * @exception           E_INVALID_ARG           Either of the following conditions has occurred:
 172          *                                                                              - The length of the specified path is either @c 0 or exceeds system limitations. @n
 173          *                                                                              - The specified path contains prohibited character(s).
 174          *                                                                              - The specified path is invalid.
 175          * @exception           E_ILLEGAL_ACCESS        Either of the following conditions has occurred:
 176          *                                                                              - The specified path is not permitted.
 177          *                                                                              - The access is denied due to insufficient permission.
 178          * @exception           E_FILE_NOT_FOUND        The entry of the specified file or path cannot be found in the archive.
 179          * @exception           E_IO                            An unexpected device failure has occurred.
 180          * @remarks
 181          *                                      - The paths for @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"data" and @b Tizen::App::AppManager::GetAppSharedPath(appId) + L"trusted" are not supported.
 182          *                                      - If the value of @c zipEntryName is a directory name present in the archive, this method
 183          *                                      creates an empty directory. @n
 184          *                                      For example, UnzipTo(Tizen::App::App::GetInstance()->GetAppDataPath() + L"Test/", L"/someDir/") will create @b '[AppDataPath]/Test/someDir'
 185          *                                      directory only, and the files or subdirectories under @b 'someDir' are not extracted.
 186          * @see                         Tizen::Io::File
 187          */
 188         result UnzipTo(const String& dirPath, const String& zipEntryName) const;
 189
 190         /**
 191          * Gets the number of entries present in a zip-archive.
 192          *
 193          * @since 2.0
 194          *
 195          * @return                      The number of entries present in a zip-archive, @n
 196          *                                      else @c -1 in case of an error
 197          * @exception           E_SUCCESS                       The method is successful.
 198          * @exception           E_IO                            An unexpected device failure has occurred.
 199          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 200          */
 201         int GetEntryCount(void) const;
 202
 203         /**
 204          * Gets the number of files present in a zip-archive.
 205          *
 206          * @since 2.0
 207          *
 208          * @return                      The number of files present in a zip-archive, @n
 209          *                                      else @c -1 in case of an error
 210          * @exception           E_SUCCESS                       The method is successful.
 211          * @exception           E_IO                            An unexpected device failure has occurred.
 212          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 213          */
 214         int GetFileCount(void) const;
 215
 216         /**
 217          * Gets the number of directories present in a zip-archive.
 218          *
 219          * @since 2.0
 220          *
 221          * @return                      The number of directories present in a zip-archive, @n
 222          *                                      else @c -1 in case of an error
 223          * @exception           E_SUCCESS                       The method is successful.
 224          * @exception           E_IO                            An unexpected device failure has occurred.
 225          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 226          */
 227         int GetDirectoryCount(void) const;
 228
 229         /**
 230          * Gets a zip entry associated with the file or directory name passed as a parameter.
 231          *
 232          * @since 2.0
 233          *
 234          * @return                      An error code
 235          * @param [in]          zipEntryName            The zip entry name that could be a file or directory name
 236          * @param [out]         entry                           A reference to the ZipEntry
 237          * @exception           E_SUCCESS                       The method is successful.
 238          * @exception           E_INVALID_ARG           Either of the following conditions has occurred:
 239          *                                                                              - The length of the specified path is either @c 0 or exceeds system limitations.
 240          *                                                                              - The specified path contains prohibited character(s).
 241          *                                                                              - The specified path is invalid.
 242          * @exception           E_FILE_NOT_FOUND        The entry of the specified file or path cannot be found in the archive.
 243          * @exception           E_IO                            An unexpected device failure has occurred.
 244          * @remarks             If the value of @c zipEntryName is a directory name, it must have a suffix '/'. @n
 245          *                              For example, @b Tizen::App::App::GetInstance()->GetAppDataPath() + L"Test/" or @b Tizen::App::App::GetInstance()->GetAppDataPath() + L"Test/DATA/".
 246          */
 247         result GetEntry(const String& zipEntryName, ZipEntry& entry) const;
 248
 249         /**
 250          * Gets a zip entry associated with the index from the root directory.
 251          *
 252          * @since 2.0
 253          *
 254          * @return                      An error code
 255          * @param [in]      index                               The index of the zip entry to access @n
 256          *                                                                              The index starts from @c 0.
 257          * @param [out]         entry                           A reference to the ZipEntry
 258          * @exception           E_SUCCESS                       The method is successful.
 259          * @exception           E_INVALID_ARG           The specified index is either invalid or out of the valid range.
 260          * @exception           E_IO                            An unexpected device failure has occurred.
 261          */
 262         result GetEntry(int index, ZipEntry& entry) const;
 263
 264
 265 private:
 266         /**
 267          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 268          *
 269          * @param [in]  fileUnzipper    The instance of the %FileUnzipper class to copy from
 270          * @remarks             This constructor is hidden.
 271          */
 272         FileUnzipper(const FileUnzipper& fileUnzipper);
 273
 274         /**
 275          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 276          *
 277          * @param [in]  fileUnzipper    An instance of %FileUnzipper
 278          * @remarks             This operator is hidden.
 279          */
 280         FileUnzipper& operator =(const FileUnzipper& fileUnzipper);
 281
 282
 283         friend class _FileUnzipperImpl;
 284         class _FileUnzipperImpl* __pFileUnzipperImpl;
 285
 286 }; // FileUnzipper
 287
 288 }}} // Tizen::Base::Utility
 289
 290 #endif // _FBASE_UTIL_FILE_UNZIPPER_H_