1# @ohos.file.securityLabel (Data Label) 2 3The **securityLabel** module provides APIs for managing data security levels of files, including obtaining and setting file security levels. 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 securityLabel from '@ohos.file.securityLabel'; 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## securityLabel.setSecurityLabel 36 37setSecurityLabel(path:string, type:DataLevel):Promise<void> 38 39Sets a security label 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 target file. | 48| type | DataLevel | Yes | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.| 49 50**Return value** 51 52| Type | Description | 53| ------------------- | ---------------- | 54| Promise<void> | Promise that returns no value.| 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| 13900001 | Operation not permitted | 63| 13900007 | Arg list too long | 64| 13900015 | File exists | 65| 13900020 | Invalid argument | 66| 13900025 | No space left on device | 67| 13900037 | No data available | 68| 13900041 | Quota exceeded | 69| 13900042 | Unknown error | 70 71**Example** 72 73 ```ts 74 import { BusinessError } from '@ohos.base'; 75 let filePath = pathDir + '/test.txt'; 76 securityLabel.setSecurityLabel(filePath, "s0").then(() => { 77 console.info("setSecurityLabel successfully"); 78 }).catch((err: BusinessError) => { 79 console.error("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code); 80 }); 81 ``` 82 83## securityLabel.setSecurityLabel 84 85setSecurityLabel(path:string, type:DataLevel, callback: AsyncCallback<void>):void 86 87Sets a security label for a file. This API uses an asynchronous callback to return the result. 88 89**System capability**: SystemCapability.FileManagement.File.FileIO 90 91**Parameters** 92 93| Name | Type | Mandatory| Description | 94| --------- | ------------------------- | ---- | -------------------------------------------- | 95| path | string | Yes | Path of the target file. | 96| type | DataLevel | Yes | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.| 97| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 98 99**Error codes** 100 101For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 102 103| ID| Error Message| 104| -------- | -------- | 105| 13900001 | Operation not permitted | 106| 13900007 | Arg list too long | 107| 13900015 | File exists | 108| 13900020 | Invalid argument | 109| 13900025 | No space left on device | 110| 13900037 | No data available | 111| 13900041 | Quota exceeded | 112| 13900042 | Unknown error | 113 114**Example** 115 116 ```ts 117 import { BusinessError } from '@ohos.base'; 118 let filePath = pathDir + '/test.txt'; 119 securityLabel.setSecurityLabel(filePath, "s0", (err: BusinessError) => { 120 if (err) { 121 console.error("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code); 122 } else { 123 console.info("setSecurityLabel successfully."); 124 } 125 }); 126 ``` 127 128## securityLabel.setSecurityLabelSync 129 130setSecurityLabelSync(path:string, type:DataLevel):void 131 132Sets a security label for a file. This API returns the result synchronously. 133 134**System capability**: SystemCapability.FileManagement.File.FileIO 135 136**Parameters** 137 138| Name | Type | Mandatory| Description | 139| --------- | ------ | ---- | -------------------------------------------- | 140| path | string | Yes | Path of the target file. | 141| type | DataLevel | Yes | File security level to set, which can be **s0**, **s1**, **s2**, **s3**, or **s4**.| 142 143**Error codes** 144 145For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 146 147| ID| Error Message| 148| -------- | -------- | 149| 13900001 | Operation not permitted | 150| 13900007 | Arg list too long | 151| 13900015 | File exists | 152| 13900020 | Invalid argument | 153| 13900025 | No space left on device | 154| 13900037 | No data available | 155| 13900041 | Quota exceeded | 156| 13900042 | Unknown error | 157 158**Example** 159 160```ts 161let filePath = pathDir + '/test.txt'; 162securityLabel.setSecurityLabelSync(filePath, "s0"); 163``` 164 165## securityLabel.getSecurityLabel 166 167getSecurityLabel(path:string):Promise<string> 168 169Obtains the security label of a file. This API uses a promise to return the result. 170 171**System capability**: SystemCapability.FileManagement.File.FileIO 172 173**Parameters** 174 175| Name| Type | Mandatory| Description | 176| ------ | ------ | ---- | -------- | 177| path | string | Yes | Path of the target file.| 178 179**Return value** 180 181| Type | Description | 182| --------------------- | ------------ | 183| Promise<string> | Security label obtained.| 184 185**Error codes** 186 187For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 188 189| ID| Error Message| 190| -------- | -------- | 191| 13900001 | Operation not permitted | 192| 13900007 | Arg list too long | 193| 13900015 | File exists | 194| 13900020 | Invalid argument | 195| 13900025 | No space left on device | 196| 13900037 | No data available | 197| 13900041 | Quota exceeded | 198| 13900042 | Unknown error | 199 200**Example** 201 202 ```ts 203 import { BusinessError } from '@ohos.base'; 204 let filePath = pathDir + '/test.txt'; 205 securityLabel.getSecurityLabel(filePath).then((type: string) => { 206 console.log("getSecurityLabel successfully, Label: " + type); 207 }).catch((err: BusinessError) => { 208 console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code); 209 }); 210 ``` 211 212## securityLabel.getSecurityLabel 213 214getSecurityLabel(path:string, callback:AsyncCallback<string>): void 215 216Obtains the security label of a file. This API uses an asynchronous callback to return the result. 217 218**System capability**: SystemCapability.FileManagement.File.FileIO 219 220**Parameters** 221 222| Name | Type | Mandatory| Description | 223| -------- | --------------------------- | ---- | -------------------------- | 224| path | string | Yes | Path of the target file. | 225| callback | AsyncCallback<string> | Yes | Callback invoked to return the security label obtained.| 226 227**Error codes** 228 229For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 230 231| ID| Error Message| 232| -------- | -------- | 233| 13900001 | Operation not permitted | 234| 13900007 | Arg list too long | 235| 13900015 | File exists | 236| 13900020 | Invalid argument | 237| 13900025 | No space left on device | 238| 13900037 | No data available | 239| 13900041 | Quota exceeded | 240| 13900042 | Unknown error | 241 242**Example** 243 244 ```ts 245 import { BusinessError } from '@ohos.base'; 246 let filePath = pathDir + '/test.txt'; 247 securityLabel.getSecurityLabel(filePath, (err: BusinessError, type: string) => { 248 if (err) { 249 console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code); 250 } else { 251 console.log("getSecurityLabel successfully, Label: " + type); 252 } 253 }); 254 ``` 255 256## securityLabel.getSecurityLabelSync 257 258getSecurityLabelSync(path:string):string 259 260Obtains the security label of a file. This API returns the result synchronously. 261 262**System capability**: SystemCapability.FileManagement.File.FileIO 263 264**Parameters** 265 266| Name| Type | Mandatory| Description | 267| ------ | ------ | ---- | -------- | 268| path | string | Yes | Path of the target file.| 269 270**Return value** 271 272| Type | Description | 273| ------ | ------------ | 274| string | Security label obtained.| 275 276**Error codes** 277 278For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). 279 280| ID| Error Message| 281| -------- | -------- | 282| 13900001 | Operation not permitted | 283| 13900007 | Arg list too long | 284| 13900015 | File exists | 285| 13900020 | Invalid argument | 286| 13900025 | No space left on device | 287| 13900037 | No data available | 288| 13900041 | Quota exceeded | 289| 13900042 | Unknown error | 290 291**Example** 292 293```ts 294let filePath = pathDir + '/test.txt'; 295let type = securityLabel.getSecurityLabelSync(filePath); 296console.log("getSecurityLabel successfully, Label: " + type); 297``` 298