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