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