From aed581890b3b0c9321b088121e0bc36c052a62ff Mon Sep 17 00:00:00 2001 From: Gloria Date: Mon, 14 Nov 2022 18:03:16 +0800 Subject: [PATCH] Update docs against 10464 Signed-off-by: wusongqing --- .../reference/apis/js-apis-zlib.md | 280 +++++++++++++++--- .../reference/errorcodes/errorcode-zlib.md | 40 +++ 2 files changed, 276 insertions(+), 44 deletions(-) create mode 100644 en/application-dev/reference/errorcodes/errorcode-zlib.md diff --git a/en/application-dev/reference/apis/js-apis-zlib.md b/en/application-dev/reference/apis/js-apis-zlib.md index 75ac7f144e..967def0ecb 100644 --- a/en/application-dev/reference/apis/js-apis-zlib.md +++ b/en/application-dev/reference/apis/js-apis-zlib.md @@ -1,31 +1,32 @@ -# Zip +# zlib + +The **zlib** module provides APIs for file compression and decompression. > **NOTE** > > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. -## Constraints - -None ## Modules to Import ```javascript import zlib from '@ohos.zlib'; ``` -## zlib.zipFile -zipFile(inFile:string, outFile:string, options: Options): Promise<void> +## zlib.zipFile(deprecated) +zipFile(inFile: string, outFile: string, options: Options): Promise<void> Zips a file. This API uses a promise to return the result. +> This API is deprecated since API version 9. You are advised to use [zlib.compressFile](#zlibcompressfile9) instead. + **System capability**: SystemCapability.BundleManager.Zlib **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------- | ---- | ------------------------------------------------------------ | -| inFile | string | Yes | Path of the folder or file to zip. For details about the path, see [FA Model](js-apis-Context.md) and [Stage Model](js-apis-application-context.md).| -| outFile | string | Yes | Path of the zipped file. The file name extension is .zip. | +| inFile | string | Yes | Path of the folder or file to zip. For details about the path, see [FA Model](js-apis-Context.md) or [Stage Model](js-apis-application-context.md).| +| outFile | string | Yes | Path of the zipped file. The file name extension is .zip. | | options | [Options](#options) | No | Optional parameters for the zip operation. | **Return value** @@ -36,59 +37,59 @@ Zips a file. This API uses a promise to return the result. **Example 1** -```javascript - +```typescript // Zip a file. -import zlib from '@ohos.zlib' -var inFile = "/xxx/filename.xxx"; -var outFile = "/xxx/xxx.zip"; -var options = { +import zlib from '@ohos.zlib'; +let inFile = '/xxx/filename.xxx'; +let outFile = '/xxx/xxx.zip'; +let options = { level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION, memLevel: zlib.MemLevel.MEM_LEVEL_DEFAULT, strategy: zlib.CompressStrategy.COMPRESS_STRATEGY_DEFAULT_STRATEGY }; zlib.zipFile(inFile, outFile, options).then((data) => { - console.log("zipFile result: " + data); -}).catch((err)=>{ - console.log("catch((err)=>" + err); + console.log('zipFile result is ' + JSON.Stringify(data)); +}).catch((err) => { + console.log('error is ' + JSON.Stringify(err)); }); - ``` **Example 2** -``` +```typescript // Zip a folder. -import zlib from '@ohos.zlib' -var inFile = "/xxx/xxx"; -var outFile = "/xxx/xxx.zip"; -var options = { +import zlib from '@ohos.zlib'; +let inFile = '/xxx/xxx'; +let outFile = '/xxx/xxx.zip'; +let options = { level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION, memLevel: zlib.MemLevel.MEM_LEVEL_DEFAULT, strategy: zlib.CompressStrategy.COMPRESS_STRATEGY_DEFAULT_STRATEGY }; zlib.zipFile(inFile , outFile, options).then((data) => { - console.log("zipFile result: " + data); + console.log('zipFile result is ' + JSON.Stringify(data)); }).catch((err)=>{ - console.log("catch((err)=>" + err); + console.log('error is ' + JSON.Stringify(err)); }); ``` -## zlib.unzipFile +## zlib.unzipFile(deprecated) unzipFile(inFile:string, outFile:string, options: Options): Promise<void> Unzips a file. This API uses a promise to return the result. +> This API is deprecated since API version 9. You are advised to use [zlib.decompressFile](#zlibdecompressfile9) instead. + **System capability**: SystemCapability.BundleManager.Zlib **Parameters** | Name | Type | Mandatory| Description | | ------- | ------------------- | ---- | ------------------------------------------------------------ | -| inFile | string | Yes | Path of the folder or file to zip. For details about the path, see [FA Model](js-apis-Context.md) and [Stage Model](js-apis-application-context.md).| +| inFile | string | Yes | Path of the folder or file to unzip. For details about the path, see [FA Model](js-apis-Context.md) or [Stage Model](js-apis-application-context.md).| | outFile | string | Yes | Path of the unzipped file. | | options | [Options](#options) | No | Optional parameters for the unzip operation. | @@ -100,11 +101,11 @@ Unzips a file. This API uses a promise to return the result. **Example** -```javascript +```typescript // Unzip a file. -import zlib from '@ohos.zlib' -var inFile = "/xx/xxx.zip"; -var outFile = "/xxx"; +import zlib from '@ohos.zlib'; +let inFile = '/xx/xxx.zip'; +let outFile = '/xxx'; let options = { level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION, @@ -112,11 +113,202 @@ let options = { strategy: zlib.CompressStrategy.COMPRESS_STRATEGY_DEFAULT_STRATEGY }; zlib.unzipFile(inFile, outFile, options).then((data) => { - console.log("unzipFile result: " + data); + console.log('unzipFile result is ' + JSON.Stringify(data)); }).catch((err)=>{ - console.log("catch((err)=>" + err); + console.log('error is ' + JSON.Stringify(err)); }) - +``` + +## zlib.compressFile9+ + +compressFile(inFile: string, outFile: string, options: Options, callback: AsyncCallback\): void; + +Compresses a file. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BundleManager.Zlib + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------------------- | ------------------- | ---- | ------------------------------------------------------------ | +| inFile | string | Yes | Path of the folder or file to compress. For details about the path, see [FA Model](js-apis-Context.md) or [Stage Model](js-apis-application-context.md).| +| outFile | string | Yes | Path of the compressed file. | +| options | [Options](#options) | Yes | Compression parameters. | +| AsyncCallback<**void**> | callback | No | Callback used to return the result. If the operation is successful, **null** is returned; otherwise, a specific error code is returned. | + +**Error codes** + +| ID| Error Message | +| ------ | -------------------------------------- | +| 401 | wrong param type | +| 900001 | The Input source file is invalid. | +| 900002 | The Input destination file is invalid. | + +**Example** + +```typescript +// Compress a file. +// The path used in the code must be the application sandbox path, for example, /data/storage/el2/base/haps. You can obtain the path through context. +import zlib from '@ohos.zlib'; +let inFile = '/xxx/filename.xxx'; +let outFile = '/xxx/xxx.zip'; +let options = { + level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION, + memLevel: zlib.MemLevel.MEM_LEVEL_DEFAULT, + strategy: zlib.CompressStrategy.COMPRESS_STRATEGY_DEFAULT_STRATEGY +}; + +try { + zlib.compressFile(inFile, outFile, options, (errData) => { + if (erData !== null) { + console.log(`errData is errCode:${errData.errCode} message:${errData.message}`); + } + }) +} catch(errData) { + console.log(`errData is errCode:${errData.errCode} message:${errData.message}`); +} +``` + +compressFile(inFile: string, outFile: string, options: Options): Promise\; + +Compresses a file. This API uses a promise to return the result. + +**System capability**: SystemCapability.BundleManager.Zlib + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------- | ---- | ------------------------------------------------------------ | +| inFile | string | Yes | Path of the folder or file to compress. For details about the path, see [FA Model](js-apis-Context.md) or [Stage Model](js-apis-application-context.md).| +| outFile | string | Yes | Path of the compressed file. | +| options | [Options](#options) | Yes | Compression parameters. | + +**Error codes** + +| ID| Error Message | +| ------ | -------------------------------------- | +| 401 | wrong param type | +| 900001 | The Input source file is invalid. | +| 900002 | The Input destination file is invalid. | + +```typescript +// Compress a file. +// The path used in the code must be the application sandbox path, for example, /data/storage/el2/base/haps. You can obtain the path through context. +import zlib from '@ohos.zlib'; +let inFile = '/xxx/filename.xxx'; +let outFile = '/xxx/xxx.zip'; +let options = { + level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION, + memLevel: zlib.MemLevel.MEM_LEVEL_DEFAULT, + strategy: zlib.CompressStrategy.COMPRESS_STRATEGY_DEFAULT_STRATEGY +}; + +try { + zlib.compressFile(inFile, outFile, options).then((data) => { + console.info('compressFile success'); + }).catch((errData) => { + console.log(`errData is errCode:${errData.errCode} message:${errData.message}`); + }) +} catch(errData) { + console.log(`errData is errCode:${errData.errCode} message:${errData.message}`); +} +``` + + + +## zlib.decompressFile9+ + +decompressFile(inFile: string, outFile: string, options: Options, callback: AsyncCallback\): void; + +Decompresses a file. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.BundleManager.Zlib + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------------------- | ------------------- | ---- | ------------------------------------------------------------ | +| inFile | string | Yes | Path of the file to decompress. For details about the path, see [FA Model](js-apis-Context.md) or [Stage Model](js-apis-application-context.md).| +| outFile | string | Yes | Path of the decompressed file. | +| options | [Options](#options) | Yes | Decompression parameters. | +| AsyncCallback<**void**> | callback | No | Callback used to return the result. If the operation is successful, **null** is returned; otherwise, a specific error code is returned. | + +**Error codes** + +| ID| Error Message | +| ------ | -------------------------------------- | +| 401 | wrong param type | +| 900001 | The Input source file is invalid. | +| 900002 | The Input destination file is invalid. | + +**Example** + +```typescript +// Decompress a file. +// The path used in the code must be the application sandbox path, for example, /data/storage/el2/base/haps. You can obtain the path through context. +import zlib from '@ohos.zlib'; +let inFile = '/xx/xxx.zip'; +let outFile = '/xxx'; +let options = { + level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION, + memLevel: zlib.MemLevel.MEM_LEVEL_DEFAULT, + strategy: zlib.CompressStrategy.COMPRESS_STRATEGY_DEFAULT_STRATEGY +}; + +try { + zlib.decompressFile(inFile, outFile, options, (errData) => { + if (erData !== null) { + console.log(`errData is errCode:${errData.errCode} message:${errData.message}`); + } + }) +} catch(errData) { + console.log(`errData is errCode:${errData.errCode} message:${errData.message}`); +} +``` + +decompressFile(inFile: string, outFile: string, options: Options): Promise\; + +Decompress a file. This API uses a promise to return the result. + +**System capability**: SystemCapability.BundleManager.Zlib + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------- | ---- | ------------------------------------------------------------ | +| inFile | string | Yes | Path of the file to decompress. For details about the path, see [FA Model](js-apis-Context.md) or [Stage Model](js-apis-application-context.md).| +| outFile | string | Yes | Path of the decompressed file. | +| options | [Options](#options) | Yes | Decompression parameters. | + +**Error codes** + +| ID| Error Message | +| ------ | -------------------------------------- | +| 401 | wrong param type | +| 900001 | The Input source file is invalid. | +| 900002 | The Input destination file is invalid. | + +```typescript +// Decompress a file. +// The path used in the code must be the application sandbox path, for example, /data/storage/el2/base/haps. You can obtain the path through context. +import zlib from '@ohos.zlib'; +let inFile = '/xx/xxx.zip'; +let outFile = '/xxx'; +let options = { + level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION, + memLevel: zlib.MemLevel.MEM_LEVEL_DEFAULT, + strategy: zlib.CompressStrategy.COMPRESS_STRATEGY_DEFAULT_STRATEGY +}; + +try { + zlib.deCompressFile(inFile, outFile, options).then((data) => { + console.info('deCompressFile success'); + }).catch((errData) => { + console.log(`errData is errCode:${errData.errCode} message:${errData.message}`); + }) +} catch(errData) { + console.log(`errData is errCode:${errData.errCode} message:${errData.message}`); +} ``` ## Options @@ -129,16 +321,6 @@ zlib.unzipFile(inFile, outFile, options).then((data) => { | memLevel | MemLevel | No | See [zip.MemLevel](#zipmemlevel). | | strategy | CompressStrategy | No | See [zip.CompressStrategy](#zipcompressstrategy).| -## zip.MemLevel - -**System capability**: SystemCapability.BundleManager.Zlib - -| Name | Value | Description | -| ----------------- | ---- | -------------------------------- | -| MEM_LEVEL_MIN | 1 | Minimum memory used by the **zip** API during compression.| -| MEM_LEVEL_MAX | 9 | Maximum memory used by the **zip** API during compression.| -| MEM_LEVEL_DEFAULT | 8 | Default memory used by the **zip** API during compression.| - ## zip.CompressLevel **System capability**: SystemCapability.BundleManager.Zlib @@ -150,6 +332,16 @@ zlib.unzipFile(inFile, outFile, options).then((data) => { | COMPRESS_LEVEL_BEST_COMPRESSION | 9 | Compression level 9 that gives the best compression. | | COMPRESS_LEVEL_DEFAULT_COMPRESSION | -1 | Default compression level. | +## zip.MemLevel + +**System capability**: SystemCapability.BundleManager.Zlib + +| Name | Value | Description | +| ----------------- | ---- | -------------------------------- | +| MEM_LEVEL_MIN | 1 | Minimum memory used by the **zip** API during compression.| +| MEM_LEVEL_MAX | 9 | Maximum memory used by the **zip** API during compression.| +| MEM_LEVEL_DEFAULT | 8 | Default memory used by the **zip** API during compression.| + ## zip.CompressStrategy **System capability**: SystemCapability.BundleManager.Zlib diff --git a/en/application-dev/reference/errorcodes/errorcode-zlib.md b/en/application-dev/reference/errorcodes/errorcode-zlib.md new file mode 100644 index 0000000000..ea2b330abe --- /dev/null +++ b/en/application-dev/reference/errorcodes/errorcode-zlib.md @@ -0,0 +1,40 @@ +# zlib Error Codes + +## 900001 Invalid Source File + +**Error Message** + +The input source file is invalid. + +**Description** + +This error code is reported when the source file passed in the **compress** or **decompress** API is invalid. + +**Possible Causes** + +When the **compress** API is called, the file to compress does not exist. When the **decompress** API is called, the file to decompress does not exist. + +**Procedure** + +1. Check whether the source file exists. +2. Check whether the path of the source file exists and whether the path is the correct sandbox path. + +## 900002 Invalid Destination File + +**Error Message** + +The input destination file is invalid. + +**Description** + +This error code is reported when the destination file passed in the **compress** or **decompress** API is invalid. + +**Possible Causes** + +1. When the **compress** API is called, the passed destination file path is invalid, for example, a non-exist sandbox path. +2. When the **decompress** API is called, the destination folder does not exist. + +**Procedure** + +1. Check whether the destination file path is correct. If not, enter the correct sandbox path. +2. Check whether the destination folder exists. If not, create the folder. -- GitLab