• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.file.hash (File Hash Processing)
2
3The **FileHash** module implements hash processing on files.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```ts
12import Hash from '@ohos.file.hash';
13```
14
15## Guidelines
16
17Before using the APIs provided by this module to perform operations on a file or directory, obtain the application sandbox path of the file or directory as follows:
18
19
20  ```ts
21  import UIAbility from '@ohos.app.ability.UIAbility';
22  import window from '@ohos.window';
23
24  export default class EntryAbility extends UIAbility {
25    onWindowStageCreate(windowStage: window.WindowStage) {
26      let context = this.context;
27      let pathDir = context.filesDir;
28    }
29  }
30  ```
31
32For details about how to obtain the application sandbox path, see [Obtaining Application File Paths](../../application-models/application-context-stage.md#obtaining-application-file-paths).
33
34
35## Hash.hash
36
37hash(path: string, algorithm: string): Promise<string>
38
39Calculates a hash value for a file. This API uses a promise to return the result.
40
41**System capability**: SystemCapability.FileManagement.File.FileIO
42
43**Parameters**
44
45| Name   | Type  | Mandatory| Description                                                        |
46| --------- | ------ | ---- | ------------------------------------------------------------ |
47| path      | string | Yes  | Path of the file in the application sandbox.                            |
48| algorithm | string | Yes  | Algorithm used to calculate the hash value. The value can be **md5**, **sha1**, or **sha256**. **sha256** is recommended for security purposes.|
49
50**Return value**
51
52| Type                   | Description                        |
53| --------------------- | -------------------------- |
54| Promise<string> | Promise used to return the hash value. The hash value is a hexadecimal string consisting of digits and uppercase letters.|
55
56**Error codes**
57
58For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes).
59
60| ID| Error Message|
61| -------- | -------- |
62| 13900020 | Invalid argument |
63| 13900042 | Unknown error |
64
65**Example**
66
67  ```ts
68  import { BusinessError } from '@ohos.base';
69  let filePath = pathDir + "/test.txt";
70  Hash.hash(filePath, "sha256").then((str: string) => {
71    console.info("calculate file hash succeed:" + str);
72  }).catch((err: BusinessError) => {
73    console.error("calculate file hash failed with error message: " + err.message + ", error code: " + err.code);
74  });
75  ```
76
77## Hash.hash
78
79hash(path: string, algorithm: string, callback: AsyncCallback<string>): void
80
81Calculates a hash value for a file. This API uses an asynchronous callback to return the result.
82
83**System capability**: SystemCapability.FileManagement.File.FileIO
84
85**Parameters**
86
87| Name   | Type                       | Mandatory| Description                                                        |
88| --------- | --------------------------- | ---- | ------------------------------------------------------------ |
89| path      | string                      | Yes  | Path of the file in the application sandbox.                            |
90| algorithm | string                      | Yes  | Algorithm used to calculate the hash value. The value can be **md5**, **sha1**, or **sha256**. **sha256** is recommended for security purposes.|
91| callback  | AsyncCallback<string> | Yes  | Callback invoked to return the hash value obtained. The hash value is a hexadecimal string consisting of digits and uppercase letters.|
92
93**Error codes**
94
95For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes).
96
97| ID| Error Message|
98| -------- | -------- |
99| 13900020 | Invalid argument |
100| 13900042 | Unknown error |
101
102**Example**
103
104  ```ts
105  import { BusinessError } from '@ohos.base';
106  let filePath = pathDir + "/test.txt";
107  Hash.hash(filePath, "sha256", (err: BusinessError, str: string) => {
108    if (err) {
109      console.error("calculate file hash failed with error message: " + err.message + ", error code: " + err.code);
110    } else {
111      console.info("calculate file hash succeed:" + str);
112    }
113  });
114  ```
115