The Archive API provides functions to create and manage archive files. You can extract files, add a file to an archive file, and so on.
For more information about how to use Archive API, see File Archiving Guide.
Since: 2.3
File reference for an archive file. It can be either a File object or a virtual path.
typedef (DOMString or File) FileReference;
Enumeration for the compression level.
enum ArchiveCompressionLevel {"STORE", "FAST", "NORMAL", "BEST"};
The ArchiveManagerObject interface defines what is instantiated in the Tizen object.
[NoInterfaceObject] interface ArchiveManagerObject { readonly attribute ArchiveManager archive; };
Tizen implements ArchiveManagerObject;
The tizen.archive object allows access to the Archive API.
The ArchiveFileOptions dictionary represents the option to decide if an archive file can be overwritten when an archive file is opened.
dictionary ArchiveFileOptions { boolean overwrite; };
boolean overwrite
Indicates whether opening an archive file for writing can overwrite the contents of the existing file.
The default value is false
See description of the mode argument of the open() method.
The ArchiveFileEntryOptions dictionary controls behavior when adding a file to an archive.
dictionary ArchiveFileEntryOptions { DOMString destination; boolean stripSourceDirectory; ArchiveCompressionLevel compressionLevel; };
DOMString destination
Path where ArchiveFileEntry should be stored in an archive file.
Remark : If destination is not set, then the root directory of archive will be used (equivalent to destination = "").
boolean stripSourceDirectory
Controls whether leading directory information is stripped from the source file name before storing.
The virtual root is always removed. To omit all the remaining directory names, set stripSourceDirectory to true.
Remark : The default value is false.
ArchiveCompressionLevel compressionLevel
Compression level.
Remark : The default compression level is NORMAL.
The ArchiveManager interface provides methods for global operations related to ArchiveFile.
[NoInterfaceObject] interface ArchiveManager { long open(FileReference file, FileMode mode, ArchiveFileSuccessCallback onsuccess, optional ErrorCallback? onerror, optional ArchiveFileOptions? options) raises(WebAPIException); void abort(long operationIdentifier) raises(WebAPIException); };
open
Opens the archive file. After this operation, it is possible to add or get files to and from the archive.
long open(FileReference file, FileMode mode, ArchiveFileSuccessCallback onsuccess, optional ErrorCallback? onerror, optional ArchiveFileOptions? options);
The errorCallback is launched with these error types:
Use mode depending on which operation are intended:
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
Return value:
long Task ID which can be used to cancel the operation with abort()
Exceptions:
with error type TypeMismatchError, if parameter type does not match.
with error type SecurityError, if the application does not have the privilege to call this method.
Code example:
function successCallback(archive) { console.log("Success, can now read from archive " + archive); } function errorCallback(error) { console.log(error); } tizen.archive.open("downloads/some_archive.zip", "r", successCallback, errorCallback);
abort
Cancels an operation with the given identifier.
void abort(long operationIdentifier);
function openSuccess(archive) { operationId = archive.extractAll("downloads/extracted"); tizen.archive.abort(operationId); } tizen.archive.open("downloads/some_archive.zip", "r", openSuccess);
The ArchiveFile interface provides access to member files of the archive file.
interface ArchiveFile { readonly attribute FileMode mode; readonly attribute unsigned long long? decompressedSize; long add(FileReference sourceFile, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror, optional ArchiveFileProgressCallback? onprogress, optional ArchiveFileEntryOptions? options) raises(WebAPIException); long extractAll(FileReference destinationDirectory, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror, optional ArchiveFileProgressCallback? onprogress, optional boolean? overwrite) raises(WebAPIException); long getEntries(ArchiveFileEntryArraySuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); long getEntryByName(DOMString name, ArchiveFileEntrySuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void close() raises(WebAPIException); };
add
Adds a new member file to ArchiveFile.
long add(FileReference sourceFile, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror, optional ArchiveFileProgressCallback? onprogress, optional ArchiveFileEntryOptions? options);
If sourceFile refers to a directory, the directory and its content will be added to ArchiveFile.
Name stored for new entries is constructed from sourceFile according to the stripSourceDirectory and destination options. Names are constructed as follows:
with error type TypeMismatchError, if parameter is of the wrong type.
with error type InvalidStateError, if ArchiveFile is not open.
with error type InvalidAccessError, if the file mode is "r".
function errorCallback(error) { console.log(error); } function successCallback() { console.log("done"); } function progressCallback(opId, val, name) { console.log("opId: " + opId + " with progress val: " + val); } function createSuccess(archive) { archive.add("downloads/file.txt", successCallback, errorCallback, progressCallback); } tizen.archive.open("downloads/new_archive.zip", "w", createSuccess);
extractAll
Extracts every file from this ArchiveFile to a given directory.
long extractAll(FileReference destinationDirectory, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror, optional ArchiveFileProgressCallback? onprogress, optional boolean? overwrite);
All extracted files will be located in the given directory.
The overwrite attribute determines whether extracted files can overwrite existing files.
with error type InvalidAccessError, if the file mode is "w" or "a".
function errorCallback(error) { console.log(error); } function successCallback() { console.log("done"); } function progressCallback(opId, val, name) { console.log("extracting operation (: " + opId + ") is in progress (" + (val * 100).toFixed(1) + "%)"); } function openSuccess(archive) { archive.extractAll("music", successCallback, errorCallback, progressCallback); } tizen.archive.open("downloads/some_archive.zip", "r", openSuccess);
getEntries
Retrieves information about the member files in ArchiveFile.
long getEntries(ArchiveFileEntryArraySuccessCallback onsuccess, optional ErrorCallback? onerror);
Privilege: http://tizen.org/privilege/filesystem.read
function errorCallback(error) { console.log(error); } function getEntriesSuccess(entries) { console.log("Entries length: " + entries.length); for (var i=0; i < entries.length; i++) { console.log(entries[i].name); } } function openSuccess(archive) { archive.getEntries(getEntriesSuccess, errorCallback); } tizen.archive.open("downloads/some_archive.zip", "r", openSuccess, errorCallback);
getEntryByName
Retrieves information about ArchiveFileEntry with the specified name in ArchiveFile.
long getEntryByName(DOMString name, ArchiveFileEntrySuccessCallback onsuccess, optional ErrorCallback? onerror);
with error type InvalidStateError, if ArchiveFile is not opened.
function errorCallback(error) { console.log(error); } function getEntrySuccess(entry) { console.log("Entry: " + entry.name + " size: " + entry.size); } function openSuccess(archive) { archive.getEntryByName("arch/my_file.txt", getEntrySuccess, errorCallback); } tizen.archive.open("downloads/some_archive.zip", "r", openSuccess);
close
Closes the ArchiveFile.
void close();
Call this method when the archive file is not used any more. Once you call this method, the archive file object will not be available and any further operation attempt results in an InvalidStateError. Calling close() on an archive file object which is already closed does not raise any exception.
The ArchiveFileEntry interface provides access to ArchiveFile member information and file data.
interface ArchiveFileEntry { readonly attribute DOMString name; readonly attribute unsigned long long size; readonly attribute unsigned long long? compressedSize; readonly attribute Date modified; long extract(FileReference destinationDirectory, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror, optional ArchiveFileProgressCallback? onprogress, optional boolean? stripName, optional boolean? overwrite) raises(WebAPIException); };
Date and time stored with the member file. This is usually the modification date of the file. Since: 2.3
extract
Extracts ArchiveFileEntry to the given location.
long extract(FileReference destinationDirectory, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror, optional ArchiveFileProgressCallback? onprogress, optional boolean? stripName, optional boolean? overwrite);
with error type InvalidValuesError, if directory parameter does not represent a directory.
function errorCallback(error) { console.log(error); } function extractSuccessCallback() { console.log("done"); } function getEntrySuccess(entry) { entry.extract("downloads/extract", extractSuccessCallback, errorCallback); } function openSuccess(archive) { archive.getEntryByName("my_file.txt", getEntrySuccess, errorCallback); } tizen.archive.open("downloads/some_archive.zip", "r", openSuccess, errorCallback);
The ArchiveFileSuccessCallback interface provides a SuccessCallback for the ArchiveManager::open() method.
[Callback=FunctionOnly, NoInterfaceObject] interface ArchiveFileSuccessCallback { void onsuccess(ArchiveFile archive); };
onsuccess
Called when the archive file with the given name is ready to use.
void onsuccess(ArchiveFile archive);
The ArchiveFileEntrySuccessCallback interface provides a SuccessCallback for the ArchiveFile::getEntryByName() method.
[Callback=FunctionOnly, NoInterfaceObject] interface ArchiveFileEntrySuccessCallback { void onsuccess(ArchiveFileEntry entry); };
Called when the file with the given name through getEntryByName() is found successfully.
void onsuccess(ArchiveFileEntry entry);
The ArchiveFileEntryArraySuccessCallback interface provides a SuccessCallback for the ArchiveFile::getEntries() method.
[Callback=FunctionOnly, NoInterfaceObject] interface ArchiveFileEntryArraySuccessCallback { void onsuccess(ArchiveFileEntry[] entries); };
Called when all file entries in the archive file are retrieved successfully.
void onsuccess(ArchiveFileEntry[] entries);
The ArchiveFileProgressCallback interface provides a ProgressCallback for ArchiveFile and ArchiveFileEntry methods.
[Callback=FunctionOnly, NoInterfaceObject] interface ArchiveFileProgressCallback { void onprogress(long operationIdentifier, double value, DOMString filename); };
onprogress
Called to signal compressing or extracting operation progress.
void onprogress(long operationIdentifier, double value, DOMString filename);
module Archive { typedef (DOMString or File) FileReference; enum ArchiveCompressionLevel {"STORE", "FAST", "NORMAL", "BEST"}; [NoInterfaceObject] interface ArchiveManagerObject { readonly attribute ArchiveManager archive; }; Tizen implements ArchiveManagerObject; dictionary ArchiveFileOptions { boolean overwrite; }; dictionary ArchiveFileEntryOptions { DOMString destination; boolean stripSourceDirectory; ArchiveCompressionLevel compressionLevel; }; [NoInterfaceObject] interface ArchiveManager { long open(FileReference file, FileMode mode, ArchiveFileSuccessCallback onsuccess, optional ErrorCallback? onerror, optional ArchiveFileOptions? options) raises(WebAPIException); void abort(long operationIdentifier) raises(WebAPIException); }; interface ArchiveFile { readonly attribute FileMode mode; readonly attribute unsigned long long? decompressedSize; long add(FileReference sourceFile, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror, optional ArchiveFileProgressCallback? onprogress, optional ArchiveFileEntryOptions? options) raises(WebAPIException); long extractAll(FileReference destinationDirectory, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror, optional ArchiveFileProgressCallback? onprogress, optional boolean? overwrite) raises(WebAPIException); long getEntries(ArchiveFileEntryArraySuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); long getEntryByName(DOMString name, ArchiveFileEntrySuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void close() raises(WebAPIException); }; interface ArchiveFileEntry { readonly attribute DOMString name; readonly attribute unsigned long long size; readonly attribute unsigned long long? compressedSize; readonly attribute Date modified; long extract(FileReference destinationDirectory, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror, optional ArchiveFileProgressCallback? onprogress, optional boolean? stripName, optional boolean? overwrite) raises(WebAPIException); }; [Callback=FunctionOnly, NoInterfaceObject] interface ArchiveFileSuccessCallback { void onsuccess(ArchiveFile archive); }; [Callback=FunctionOnly, NoInterfaceObject] interface ArchiveFileEntrySuccessCallback { void onsuccess(ArchiveFileEntry entry); }; [Callback=FunctionOnly, NoInterfaceObject] interface ArchiveFileEntryArraySuccessCallback { void onsuccess(ArchiveFileEntry[] entries); }; [Callback=FunctionOnly, NoInterfaceObject] interface ArchiveFileProgressCallback { void onprogress(long operationIdentifier, double value, DOMString filename); }; };