1# @ohos.file.securityLabel (数据标签)
2
3该模块提供文件数据安全等级的相关功能：向应用程序提供查询、设置文件数据安全等级的JS接口。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { securityLabel } from '@kit.CoreFileKit';
13```
14
15## 使用说明
16
17使用该功能模块对文件/目录进行操作前，需要先获取其应用沙箱路径，获取方式及其接口用法请参考：
18
19
20  ```ts
21  import { UIAbility } from '@kit.AbilityKit';
22  import { window } from '@kit.ArkUI';
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
32使用该功能模块对文件/目录进行操作前，需要先获取其应用沙箱路径，获取方式及其接口用法请参考：[应用上下文Context-获取应用文件路径](../../application-models/application-context-stage.md#获取应用文件路径)
33
34## DataLevel
35
36type DataLevel = 's0' | 's1' | 's2' | 's3' | 's4' |
37
38数据安全级别。
39
40**系统能力**：SystemCapability.FileManagement.File.FileIO
41
42## securityLabel.setSecurityLabel
43
44setSecurityLabel(path:string, type:DataLevel):Promise<void>
45
46以异步方法设置数据标签，数据标签安全等级仅可由低向高或平级设置，以Promise形式返回结果。
47
48**系统能力**：SystemCapability.FileManagement.File.FileIO
49
50**参数：**
51
52| 参数名    | 类型       | 必填 | 说明                                         |
53| --------- | ------    | ---- | -------------------------------------------- |
54| path      | string    | 是   | 文件路径                                     |
55| type      | [DataLevel](#datalevel) | 是   | 文件等级属性，只支持"s0","s1","s2","s3","s4" |
56
57**返回值：**
58
59  | 类型                | 说明             |
60  | ------------------- | ---------------- |
61  | Promise<void> | Promise实例，用于异步获取结果。本调用将返回空值。|
62
63**错误码：**
64
65以下错误码的详细介绍请参见[基础文件IO错误码](errorcode-filemanagement.md#基础文件io错误码)。
66
67| 错误码ID | 错误信息 |
68| -------- | -------- |
69| 13900001 | Operation not permitted |
70| 13900007 | Arg list too long |
71| 13900015 | File exists |
72| 13900020 | Invalid argument |
73| 13900025 | No space left on device |
74| 13900037 | No data available |
75| 13900041 | Quota exceeded |
76| 13900042 | Unknown error |
77
78**示例：**
79
80  ```ts
81  import { BusinessError } from '@kit.BasicServicesKit';
82  let filePath = pathDir + '/test.txt';
83  securityLabel.setSecurityLabel(filePath, "s0").then(() => {
84    console.info("setSecurityLabel successfully");
85  }).catch((err: BusinessError) => {
86    console.error("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
87  });
88  ```
89
90## securityLabel.setSecurityLabel
91
92setSecurityLabel(path:string, type:DataLevel, callback: AsyncCallback<void>):void
93
94以异步方法设置数据标签，数据标签安全等级仅可由低向高或平级设置，以callback形式返回结果。
95
96**系统能力**：SystemCapability.FileManagement.File.FileIO
97
98**参数：**
99
100| 参数名    | 类型                      | 必填 | 说明                                         |
101| --------- | ------------------------- | ---- | -------------------------------------------- |
102| path      | string                    | 是   | 文件路径                                     |
103| type      | DataLevel                 | 是   | 文件等级属性，只支持"s0","s1","s2","s3","s4" |
104| callback  | AsyncCallback<void> | 是   | 是否设置数据标签之后的回调                   |
105
106**错误码：**
107
108以下错误码的详细介绍请参见[基础文件IO错误码](errorcode-filemanagement.md#基础文件io错误码)。
109
110| 错误码ID | 错误信息 |
111| -------- | -------- |
112| 13900001 | Operation not permitted |
113| 13900007 | Arg list too long |
114| 13900015 | File exists |
115| 13900020 | Invalid argument |
116| 13900025 | No space left on device |
117| 13900037 | No data available |
118| 13900041 | Quota exceeded |
119| 13900042 | Unknown error |
120
121**示例：**
122
123  ```ts
124  import { BusinessError } from '@kit.BasicServicesKit';
125  let filePath = pathDir + '/test.txt';
126  securityLabel.setSecurityLabel(filePath, "s0", (err: BusinessError) => {
127    if (err) {
128      console.error("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
129    } else {
130      console.info("setSecurityLabel successfully.");
131    }
132  });
133  ```
134
135## securityLabel.setSecurityLabelSync
136
137setSecurityLabelSync(path:string, type:DataLevel):void
138
139以同步方法设置数据标签，数据标签安全等级仅可由低向高或平级设置。
140
141**系统能力**：SystemCapability.FileManagement.File.FileIO
142
143**参数：**
144
145| 参数名    | 类型   | 必填 | 说明                                         |
146| --------- | ------ | ---- | -------------------------------------------- |
147| path      | string | 是   | 文件路径                                     |
148| type      | DataLevel | 是   | 文件等级属性，只支持"s0","s1","s2","s3","s4" |
149
150**错误码：**
151
152以下错误码的详细介绍请参见[基础文件IO错误码](errorcode-filemanagement.md#基础文件io错误码)。
153
154| 错误码ID | 错误信息 |
155| -------- | -------- |
156| 13900001 | Operation not permitted |
157| 13900007 | Arg list too long |
158| 13900015 | File exists |
159| 13900020 | Invalid argument |
160| 13900025 | No space left on device |
161| 13900037 | No data available |
162| 13900041 | Quota exceeded |
163| 13900042 | Unknown error |
164
165**示例：**
166
167```ts
168let filePath = pathDir + '/test.txt';
169securityLabel.setSecurityLabelSync(filePath, "s0");
170```
171
172## securityLabel.getSecurityLabel
173
174getSecurityLabel(path:string):Promise<string>
175
176异步方法获取数据标签，若未设置过数据标签安全等级则默认返回“s3”，以Promise形式返回结果。
177
178**系统能力**：SystemCapability.FileManagement.File.FileIO
179
180**参数：**
181
182  | 参数名 | 类型   | 必填 | 说明     |
183  | ------ | ------ | ---- | -------- |
184  | path   | string | 是   | 文件路径 |
185
186**返回值：**
187
188  | 类型                  | 说明         |
189  | --------------------- | ------------ |
190  | Promise<string> | 返回数据标签 |
191
192**错误码：**
193
194以下错误码的详细介绍请参见[基础文件IO错误码](errorcode-filemanagement.md#基础文件io错误码)。
195
196| 错误码ID | 错误信息 |
197| -------- | -------- |
198| 13900001 | Operation not permitted |
199| 13900007 | Arg list too long |
200| 13900015 | File exists |
201| 13900020 | Invalid argument |
202| 13900025 | No space left on device |
203| 13900037 | No data available |
204| 13900041 | Quota exceeded |
205| 13900042 | Unknown error |
206
207**示例：**
208
209  ```ts
210  import { BusinessError } from '@kit.BasicServicesKit';
211  let filePath = pathDir + '/test.txt';
212  securityLabel.getSecurityLabel(filePath).then((type: string) => {
213    console.log("getSecurityLabel successfully, Label: " + type);
214  }).catch((err: BusinessError) => {
215    console.error("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
216  });
217  ```
218
219## securityLabel.getSecurityLabel
220
221getSecurityLabel(path:string, callback:AsyncCallback<string>): void
222
223异步方法获取数据标签，若未设置过数据标签安全等级则默认返回“s3”，以callback形式返回结果。
224
225**系统能力**：SystemCapability.FileManagement.File.FileIO
226
227**参数：**
228
229  | 参数名   | 类型                        | 必填 | 说明                       |
230  | -------- | --------------------------- | ---- | -------------------------- |
231  | path     | string                      | 是   | 文件路径                   |
232  | callback | AsyncCallback<string> | 是   | 异步获取数据标签之后的回调 |
233
234**错误码：**
235
236以下错误码的详细介绍请参见[基础文件IO错误码](errorcode-filemanagement.md#基础文件io错误码)。
237
238| 错误码ID | 错误信息 |
239| -------- | -------- |
240| 13900001 | Operation not permitted |
241| 13900007 | Arg list too long |
242| 13900015 | File exists |
243| 13900020 | Invalid argument |
244| 13900025 | No space left on device |
245| 13900037 | No data available |
246| 13900041 | Quota exceeded |
247| 13900042 | Unknown error |
248
249**示例：**
250
251  ```ts
252  import { BusinessError } from '@kit.BasicServicesKit';
253  let filePath = pathDir + '/test.txt';
254  securityLabel.getSecurityLabel(filePath, (err: BusinessError, type: string) => {
255    if (err) {
256      console.error("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
257    } else {
258      console.log("getSecurityLabel successfully, Label: " + type);
259    }
260  });
261  ```
262
263## securityLabel.getSecurityLabelSync
264
265getSecurityLabelSync(path:string):string
266
267以同步方法获取数据标签，若未设置过数据标签安全等级则默认返回“s3”。
268
269**系统能力**：SystemCapability.FileManagement.File.FileIO
270
271**参数：**
272
273| 参数名 | 类型   | 必填 | 说明     |
274| ------ | ------ | ---- | -------- |
275| path   | string | 是   | 文件路径 |
276
277**返回值：**
278
279| 类型   | 说明         |
280| ------ | ------------ |
281| string | 返回数据标签 |
282
283**错误码：**
284
285以下错误码的详细介绍请参见[基础文件IO错误码](errorcode-filemanagement.md#基础文件io错误码)。
286
287| 错误码ID | 错误信息 |
288| -------- | -------- |
289| 13900001 | Operation not permitted |
290| 13900007 | Arg list too long |
291| 13900015 | File exists |
292| 13900020 | Invalid argument |
293| 13900025 | No space left on device |
294| 13900037 | No data available |
295| 13900041 | Quota exceeded |
296| 13900042 | Unknown error |
297
298**示例：**
299
300```ts
301let filePath = pathDir + '/test.txt';
302let type = securityLabel.getSecurityLabelSync(filePath);
303console.log("getSecurityLabel successfully, Label: " + type);
304```
305