2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FBaseUtilFileUnzipper.h
19 * @brief This is the header file for %FileUnzipper class.
21 * This header file contains the declarations of the %FileUnzipper class.
24 #ifndef _FBASE_UTIL_FILE_UNZIPPER_H_
25 #define _FBASE_UTIL_FILE_UNZIPPER_H_
28 #include <FBaseString.h>
29 #include <FBaseUtilZipEntry.h>
32 namespace Tizen { namespace Base { namespace Utility
37 * @brief This class provides methods that decompress data from a zip-archive using zlib.
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.
44 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/utility_namespace.htm">Utility</a>.
46 * The following example demonstrates how to use the %FileUnzipper class.
50 * using namespace Tizen::App;
51 * using namespace Tizen::Base;
52 * using namespace Tizen::Base::Utility;
55 * MyClass::FileUnzipperSample(void)
60 * String dataPath = App::GetInstance()->GetAppDataPath();
61 * unzip.Construct(dataPath + L"sample.zip");
63 * // Unzips the zip-archive fully
64 * unzip.UnzipTo(dataPath);
66 * // Unzips the file from the zip-archive
67 * unzip.UnzipTo(dataPath + L"Sample/", L"data1.txt");
69 * // Gets the number of entries
70 * count = unzip.GetEntryCount();
76 class _OSP_EXPORT_ FileUnzipper
77 : public Tizen::Base::Object
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.
89 * This destructor overrides Tizen::Base::Object::~Object().
93 virtual ~FileUnzipper(void);
96 * Initializes this instance of %FileUnzipper with the specified filepath. @n
97 * The %Construct() method opens a zip file in the read mode.
100 * @brief <i> [Compatibility] </i>
104 * @compatibility This method has compatibility issues with OSP compatible applications. @n
105 * For more information, see @ref CompIoPathPage "here".
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
121 result Construct(const String& filePath);
124 * Unzips a zip file at the specified path or destination.
127 * @brief <i> [Compatibility] </i>
131 * @compatibility This method has compatibility issues with OSP compatible applications. @n
132 * For more information, see @ref CompIoPathPage "here".
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.
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
150 * In such cases, it is recommended to call this method in a separate thread.
151 * @see Tizen::Io::File
153 result UnzipTo(const String& dirPath) const;
156 * Unzips a zip entry from a zip-archive to the specified path.
159 * @brief <i> [Compatibility] </i>
163 * @compatibility This method has compatibility issues with OSP compatible applications. @n
164 * For more information, see @ref CompIoPathPage "here".
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.
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
188 result UnzipTo(const String& dirPath, const String& zipEntryName) const;
191 * Gets the number of entries present in a zip-archive.
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.
201 int GetEntryCount(void) const;
204 * Gets the number of files present in a zip-archive.
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.
214 int GetFileCount(void) const;
217 * Gets the number of directories present in a zip-archive.
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.
227 int GetDirectoryCount(void) const;
230 * Gets a zip entry associated with the file or directory name passed as a parameter.
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/".
247 result GetEntry(const String& zipEntryName, ZipEntry& entry) const;
250 * Gets a zip entry associated with the index from the root directory.
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.
262 result GetEntry(int index, ZipEntry& entry) const;
267 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
269 * @param [in] fileUnzipper The instance of the %FileUnzipper class to copy from
270 * @remarks This constructor is hidden.
272 FileUnzipper(const FileUnzipper& fileUnzipper);
275 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
277 * @param [in] fileUnzipper An instance of %FileUnzipper
278 * @remarks This operator is hidden.
280 FileUnzipper& operator =(const FileUnzipper& fileUnzipper);
283 friend class _FileUnzipperImpl;
284 class _FileUnzipperImpl* __pFileUnzipperImpl;
288 }}} // Tizen::Base::Utility
290 #endif // _FBASE_UTIL_FILE_UNZIPPER_H_