1# @ohos.file.securityLabel (Data Label) 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 9The **securityLabel** module provides APIs for managing data security levels of files, including obtaining and setting file security levels. 10 11> **NOTE** 12> 13> 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. 14 15## Modules to Import 16 17```ts 18import { securityLabel } from '@kit.CoreFileKit'; 19``` 20 21## How to Use 22 23Before 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: 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 38For details about how to obtain the application sandbox path, see [Obtaining Application File Paths](../../application-models/application-context-stage.md#obtaining-application-file-paths). 39 40## DataLevel 41 42type DataLevel = 's0' | 's1' | 's2' | 's3' | 's4' 43 44Defines the data security level. 45 46**System capability**: SystemCapability.FileManagement.File.FileIO 47 48## securityLabel.setSecurityLabel 49 50setSecurityLabel(path:string, type:DataLevel):Promise<void> 51 52Sets a security label for a file. The security label cannot be changed from a higher level to a lower level. This API uses a promise to return the result. 53 54**System capability**: SystemCapability.FileManagement.File.FileIO 55 56**Parameters** 57 58| Name | Type | Mandatory| Description | 59| --------- | ------ | ---- | -------------------------------------------- | 60| path | string | Yes | File path. | 61| type | [DataLevel](#datalevel) | Yes | Security label to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.| 62 63**Return value** 64 65 | Type | Description | 66 | ------------------- | ---------------- | 67 | Promise<void> | Promise that returns no value.| 68 69**Error codes** 70 71For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes). 72 73| ID| Error Message| 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**Example** 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 100Sets a security label for a file. The security label cannot be changed from a higher level to a lower level. This API uses an asynchronous callback to return the result. 101 102**System capability**: SystemCapability.FileManagement.File.FileIO 103 104**Parameters** 105 106| Name | Type | Mandatory| Description | 107| --------- | ------------------------- | ---- | -------------------------------------------- | 108| path | string | Yes | File path. | 109| type | [DataLevel](#datalevel) | Yes | Security label to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.| 110| callback | AsyncCallback<void> | Yes | Callback used to return the security label set. | 111 112**Error codes** 113 114For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes). 115 116| ID| Error Message| 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**Example** 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 145Sets a security label for a file. This API returns the result synchronously. The security label cannot be changed from a higher level to a lower level. 146 147**System capability**: SystemCapability.FileManagement.File.FileIO 148 149**Parameters** 150 151| Name | Type | Mandatory| Description | 152| --------- | ------ | ---- | -------------------------------------------- | 153| path | string | Yes | File path. | 154| type | [DataLevel](#datalevel) | Yes | Security label to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.| 155 156**Error codes** 157 158For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes). 159 160| ID| Error Message| 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**Example** 172 173```ts 174let filePath = pathDir + '/test.txt'; 175securityLabel.setSecurityLabelSync(filePath, "s0"); 176``` 177 178## securityLabel.getSecurityLabel 179 180getSecurityLabel(path:string):Promise<string> 181 182Obtains the security label. If no security label has been set for the file, **s3** is returned by default. This API uses a promise to return the result. 183 184**System capability**: SystemCapability.FileManagement.File.FileIO 185 186**Parameters** 187 188 | Name| Type | Mandatory| Description | 189 | ------ | ------ | ---- | -------- | 190 | path | string | Yes | File path.| 191 192**Return value** 193 194 | Type | Description | 195 | --------------------- | ------------ | 196 | Promise<string> | Security label obtained.| 197 198**Error codes** 199 200For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes). 201 202| ID| Error Message| 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**Example** 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 229Obtains the security label. If no security label has been set for the file, **s3** is returned by default. This API uses an asynchronous callback to return the result. 230 231**System capability**: SystemCapability.FileManagement.File.FileIO 232 233**Parameters** 234 235 | Name | Type | Mandatory| Description | 236 | -------- | --------------------------- | ---- | -------------------------- | 237 | path | string | Yes | File path. | 238 | callback | AsyncCallback<string> | Yes | Callback used to return the security label obtained.| 239 240**Error codes** 241 242For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes). 243 244| ID| Error Message| 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**Example** 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 273Obtains the security label. This API returns the result synchronously. If no security label has been set for the file, **s3** is returned by default. 274 275**System capability**: SystemCapability.FileManagement.File.FileIO 276 277**Parameters** 278 279| Name| Type | Mandatory| Description | 280| ------ | ------ | ---- | -------- | 281| path | string | Yes | File path.| 282 283**Return value** 284 285| Type | Description | 286| ------ | ------------ | 287| string | Security label obtained.| 288 289**Error codes** 290 291For details about the error codes, see [Basic File IO Error Codes](errorcode-filemanagement.md#basic-file-io-error-codes). 292 293| ID| Error Message| 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**Example** 305 306```ts 307let filePath = pathDir + '/test.txt'; 308let type = securityLabel.getSecurityLabelSync(filePath); 309console.log("getSecurityLabel successfully, Label: " + type); 310``` 311