1# @ohos.dlpPermission (数据防泄漏) 2 3数据防泄漏（DLP）是系统提供的系统级的数据防泄漏解决方案，提供跨设备的文件的权限管理、加密存储、授权访问等能力。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - @ohos.dlpPermission归属的Kit已由'DataLossPreventionKit'变更为'DataProtectionKit'，建议开发者使用新模块名'@kit.DataProtectionKit'完成模块导入。如果使用'@kit.DataLossPreventionKit'导入，仅能调用改名前的接口，无法使用新增接口。 9 10## 导入模块 11 12```ts 13import { dlpPermission } from '@kit.DataProtectionKit'; 14``` 15 16## dlpPermission.isDLPFile 17 18isDLPFile(fd: number): Promise<boolean> 19 20根据文件的fd，查询该文件是否是DLP文件。使用Promise方式异步返回结果。 21 22**系统能力：** SystemCapability.Security.DataLossPrevention 23 24**参数：** 25 26| 参数名 | 类型 | 必填 | 说明 | 27| -------- | -------- | -------- | -------- | 28| fd | number | 是 | 文件的fd(file descriptor, 文件描述符)。 | 29 30**返回值：** 31| 类型 | 说明 | 32| -------- | -------- | 33| Promise<boolean> | Promise对象。返回true表示是DLP文件，返回false表示非DLP文件。 | 34 35**错误码：** 36 37以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 38 39| 错误码ID | 错误信息 | 40| -------- | -------- | 41| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 42| 19100001 | Invalid parameter value. | 43| 19100011 | The system ability works abnormally. | 44 45**示例：** 46 47```ts 48import { dlpPermission } from '@kit.DataProtectionKit'; 49import { fileIo } from '@kit.CoreFileKit'; 50import { BusinessError } from '@kit.BasicServicesKit'; 51 52let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp"; 53let file = fileIo.openSync(uri); 54 55try { 56 let res = dlpPermission.isDLPFile(file.fd); // 是否加密DLP文件 57 console.info('res', res); 58} catch (err) { 59 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 60} 61fileIo.closeSync(file); 62``` 63 64## dlpPermission.isDLPFile 65 66isDLPFile(fd: number, callback: AsyncCallback<boolean>): void 67 68根据文件的fd，查询该文件是否是DLP文件。使用callback方式异步返回结果。 69 70**系统能力：** SystemCapability.Security.DataLossPrevention 71 72**参数：** 73 74| 参数名 | 类型 | 必填 | 说明 | 75| -------- | -------- | -------- | -------- | 76| fd | number | 是 | 文件的fd。 | 77| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示是DLP文件，返回false表示非DLP文件。 | 78 79**错误码：** 80 81以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 82 83| 错误码ID | 错误信息 | 84| -------- | -------- | 85| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 86| 19100001 | Invalid parameter value. | 87| 19100011 | The system ability works abnormally. | 88 89**示例：** 90 91```ts 92import { dlpPermission } from '@kit.DataProtectionKit'; 93import { fileIo } from '@kit.CoreFileKit'; 94import { BusinessError } from '@kit.BasicServicesKit'; 95 96let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp"; 97let file = fileIo.openSync(uri); 98 99try { 100 dlpPermission.isDLPFile(file.fd, (err, res) => { 101 if (err != undefined) { 102 console.error('isDLPFile error,', err.code, err.message); 103 } else { 104 console.info('res', res); 105 } 106 fileIo.closeSync(file); 107 }); 108} catch (err) { 109 console.error('isDLPFile error,', (err as BusinessError).code, (err as BusinessError).message); 110 fileIo.closeSync(file); 111} 112``` 113 114## dlpPermission.getDLPPermissionInfo 115 116getDLPPermissionInfo(): Promise<DLPPermissionInfo> 117 118查询当前DLP沙箱的权限信息。使用Promise方式异步返回结果。 119 120**系统能力：** SystemCapability.Security.DataLossPrevention 121 122**返回值：** 123 124| 类型 | 说明 | 125| -------- | -------- | 126| Promise<[DLPPermissionInfo](#dlppermissioninfo)> | Promise对象。返回查询的DLP文件的权限信息，无异常则表明查询成功。 | 127 128**错误码：** 129 130以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 131 132| 错误码ID | 错误信息 | 133| -------- | -------- | 134| 19100001 | Invalid parameter value. | 135| 19100006 | No permission to call this API, which is available only for DLP sandbox applications. | 136| 19100011 | The system ability works abnormally. | 137 138**示例：** 139 140```ts 141import { dlpPermission } from '@kit.DataProtectionKit'; 142import { BusinessError } from '@kit.BasicServicesKit'; 143 144try { 145 dlpPermission.isInSandbox().then((inSandbox) => { // 是否在沙箱内 146 if (inSandbox) { 147 let res: Promise<dlpPermission.DLPPermissionInfo> = dlpPermission.getDLPPermissionInfo(); // 获取当前权限信息 148 console.info('res', JSON.stringify(res)); 149 } 150 }); 151} catch (err) { 152 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 153} 154``` 155 156## dlpPermission.getDLPPermissionInfo 157 158getDLPPermissionInfo(callback: AsyncCallback<DLPPermissionInfo>): void 159 160查询当前DLP沙箱的权限信息。使用callback方式异步返回结果。 161 162**系统能力：** SystemCapability.Security.DataLossPrevention 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| -------- | -------- | -------- | -------- | 168| callback | AsyncCallback<[DLPPermissionInfo](#dlppermissioninfo)> | 是 | 回调函数。err为undefine时表示查询成功；否则为错误对象。 | 169 170**错误码：** 171 172以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 173 174| 错误码ID | 错误信息 | 175| -------- | -------- | 176| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 177| 19100001 | Invalid parameter value. | 178| 19100006 | No permission to call this API, which is available only for DLP sandbox applications. | 179| 19100011 | The system ability works abnormally. | 180 181**示例：** 182 183```ts 184import { dlpPermission } from '@kit.DataProtectionKit'; 185import { fileIo } from '@kit.CoreFileKit'; 186import { BusinessError } from '@kit.BasicServicesKit'; 187 188try { 189 dlpPermission.isInSandbox().then((inSandbox) => { // 是否在沙箱内 190 if (inSandbox) { 191 dlpPermission.getDLPPermissionInfo((err, res) => { 192 if (err != undefined) { 193 console.error('getDLPPermissionInfo error,', err.code, err.message); 194 } else { 195 console.info('res', JSON.stringify(res)); 196 } 197 }); // 获取当前权限信息 198 } 199 }); 200} catch (err) { 201 console.error('getDLPPermissionInfo error,', (err as BusinessError).code, (err as BusinessError).message); 202} 203``` 204 205## dlpPermission.getOriginalFileName 206 207getOriginalFileName(fileName: string): string 208 209获取指定DLP文件名的原始文件名。接口为同步接口。 210 211**系统能力：** SystemCapability.Security.DataLossPrevention 212 213**参数：** 214 215| 参数名 | 类型 | 必填 | 说明 | 216| -------- | -------- | -------- | -------- | 217| fileName | string | 是 | 指定要查询的文件名。 | 218 219**返回值：** 220 221| 类型 | 说明 | 222| -------- | -------- | 223| string | 返回DLP文件的原始文件名。例如：DLP文件名为test.txt.dlp，则返回的原始文件名为test.txt。 | 224 225**错误码：** 226 227以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 228 229| 错误码ID | 错误信息 | 230| -------- | -------- | 231| 19100001 | Invalid parameter value. | 232| 19100011 | The system ability works abnormally. | 233 234**示例：** 235 236```ts 237import { dlpPermission } from '@kit.DataProtectionKit'; 238import { BusinessError } from '@kit.BasicServicesKit'; 239 240try { 241 let res = dlpPermission.getOriginalFileName('test.txt.dlp'); // 获取原始文件名 242 console.info('res', res); 243} catch (err) { 244 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 245} 246``` 247 248## dlpPermission.getDLPSuffix 249 250getDLPSuffix(): string 251 252获取DLP文件扩展名。接口为同步接口。 253 254**系统能力：** SystemCapability.Security.DataLossPrevention 255 256**返回值：** 257 258| 类型 | 说明 | 259| -------- | -------- | 260| string | 返回DLP文件扩展名。例如：原文件"text.txt"，返回拓展名为".dlp"，加密后的DLP文件名为"test.txt.dlp"。 | 261 262**错误码：** 263 264以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 265 266| 错误码ID | 错误信息 | 267| -------- | -------- | 268| 19100011 | The system ability works abnormally. | 269 270**示例：** 271 272```ts 273import { dlpPermission } from '@kit.DataProtectionKit'; 274import { BusinessError } from '@kit.BasicServicesKit'; 275 276try { 277 let res = dlpPermission.getDLPSuffix(); // 获取DLP拓展名 278 console.info('res', res); 279} catch (err) { 280 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 281} 282``` 283 284## dlpPermission.on('openDLPFile') 285 286on(type: 'openDLPFile', listener: Callback<AccessedDLPFileInfo>): void 287 288监听打开DLP文件。在当前应用的沙箱应用打开DLP文件时，通知当前应用。 289 290**系统能力：** SystemCapability.Security.DataLossPrevention 291 292**参数：** 293 294| 参数名 | 类型 | 必填 | 说明 | 295| -------- | -------- | -------- | -------- | 296| type | 'openDLPFile' | 是 | 监听事件类型。固定值为'openDLPFile'：打开DLP文件事件。 | 297| listener | Callback<[AccessedDLPFileInfo](#accesseddlpfileinfo)> | 是 | DLP文件打开事件的回调。在当前应用的沙箱应用打开DLP文件时，通知当前应用。 | 298 299**错误码：** 300 301以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 302 303| 错误码ID | 错误信息 | 304| -------- | -------- | 305| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 306| 19100001 | Invalid parameter value. | 307| 19100007 | No permission to call this API, which is available only for non-DLP sandbox applications. | 308| 19100011 | The system ability works abnormally. | 309 310**示例：** 311 312```ts 313import { dlpPermission } from '@kit.DataProtectionKit'; 314import { BusinessError } from '@kit.BasicServicesKit'; 315 316try { 317 dlpPermission.on('openDLPFile', (info: dlpPermission.AccessedDLPFileInfo) => { 318 console.info('openDlpFile event', info.uri, info.lastOpenTime) 319 }); // 订阅 320} catch (err) { 321 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 322} 323``` 324 325## dlpPermission.off('openDLPFile') 326 327off(type: 'openDLPFile', listener?: Callback<AccessedDLPFileInfo>): void 328 329取消监听打开DLP文件。在当前应用的沙箱应用打开DLP文件时，取消通知当前应用。 330 331**系统能力：** SystemCapability.Security.DataLossPrevention 332 333**参数：** 334| 参数名 | 类型 | 必填 | 说明 | 335| -------- | -------- | -------- | -------- | 336| type | 'openDLPFile' | 是 | 监听事件类型。固定值为'openDLPFile'：打开DLP文件事件。 | 337| listener | Callback<[AccessedDLPFileInfo](#accesseddlpfileinfo)> | 否 | DLP文件被打开的事件的回调。在当前应用的沙箱应用打开DLP文件时，取消通知当前应用。默认为空，表示取消该类型事件的所有回调。 | 338 339**错误码：** 340 341以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 342 343| 错误码ID | 错误信息 | 344| -------- | -------- | 345| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 346| 19100001 | Invalid parameter value. | 347| 19100007 | No permission to call this API, which is available only for non-DLP sandbox applications. | 348| 19100011 | The system ability works abnormally. | 349 350**示例：** 351 352```ts 353import { dlpPermission } from '@kit.DataProtectionKit'; 354import { BusinessError } from '@kit.BasicServicesKit'; 355 356try { 357 dlpPermission.off('openDLPFile', (info: dlpPermission.AccessedDLPFileInfo) => { 358 console.info('openDlpFile event', info.uri, info.lastOpenTime) 359 }); // 取消订阅 360} catch (err) { 361 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 362} 363``` 364 365## dlpPermission.isInSandbox 366 367isInSandbox(): Promise<boolean> 368 369查询当前应用是否运行在DLP沙箱环境。使用Promise方式异步返回结果。 370 371**系统能力：** SystemCapability.Security.DataLossPrevention 372 373**返回值：** 374 375| 类型 | 说明 | 376| -------- | -------- | 377| Promise<boolean> | Promise对象。返回当前应用是否运行在沙箱中。 | 378 379**错误码：** 380 381以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 382 383| 错误码ID | 错误信息 | 384| -------- | -------- | 385| 19100001 | Invalid parameter value. | 386| 19100011 | The system ability works abnormally. | 387 388**示例：** 389 390```ts 391import { dlpPermission } from '@kit.DataProtectionKit'; 392import { BusinessError } from '@kit.BasicServicesKit'; 393 394try { 395 let inSandbox = dlpPermission.isInSandbox(); // 是否在沙箱内 396 console.info('res', inSandbox); 397} catch (err) { 398 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 399} 400``` 401 402## dlpPermission.isInSandbox 403 404isInSandbox(callback: AsyncCallback<boolean>): void 405 406查询当前应用是否运行在DLP沙箱环境。使用callback方式异步返回结果。 407 408**系统能力：** SystemCapability.Security.DataLossPrevention 409 410**参数：** 411 412| 参数名 | 类型 | 必填 | 说明 | 413| -------- | -------- | -------- | -------- | 414| callback | AsyncCallback<boolean> | 是 | 回调函数。err为undefine时表示查询成功；否则为错误对象。 | 415 416**错误码：** 417 418以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 419 420| 错误码ID | 错误信息 | 421| -------- | -------- | 422| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 423| 19100001 | Invalid parameter value. | 424| 19100011 | The system ability works abnormally. | 425 426**示例：** 427 428```ts 429import { dlpPermission } from '@kit.DataProtectionKit'; 430import { BusinessError } from '@kit.BasicServicesKit'; 431 432try { 433 dlpPermission.isInSandbox((err, data) => { 434 if (err) { 435 console.error('isInSandbox error,', err.code, err.message); 436 } else { 437 console.info('isInSandbox, data', JSON.stringify(data)); 438 } 439 }); // 是否在沙箱内 440} catch (err) { 441 console.error('isInSandbox error,', (err as BusinessError).code, (err as BusinessError).message); 442} 443``` 444 445## dlpPermission.getDLPSupportedFileTypes 446 447getDLPSupportedFileTypes(): Promise<Array<string>> 448 449查询当前可支持权限设置和校验的文件扩展名类型列表。使用Promise方式异步返回结果。 450 451**系统能力：** SystemCapability.Security.DataLossPrevention 452 453**返回值：** 454 455| 类型 | 说明 | 456| -------- | -------- | 457| Promise<Array<string>> | Promise对象。返回当前可支持权限设置和校验的文件扩展名类型列表。 | 458 459**错误码：** 460 461以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 462 463| 错误码ID | 错误信息 | 464| -------- | -------- | 465| 19100001 | Invalid parameter value. | 466| 19100011 | The system ability works abnormally. | 467 468**示例：** 469 470```ts 471import { dlpPermission } from '@kit.DataProtectionKit'; 472import { BusinessError } from '@kit.BasicServicesKit'; 473 474try { 475 let res = dlpPermission.getDLPSupportedFileTypes(); // 获取支持DLP的文件类型 476 console.info('res', JSON.stringify(res)); 477} catch (err) { 478 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 479} 480``` 481 482## dlpPermission.getDLPSupportedFileTypes 483 484getDLPSupportedFileTypes(callback: AsyncCallback<Array<string>>): void 485 486查询当前可支持权限设置和校验的文件扩展名类型列表。使用callback方式异步返回结果。 487 488**系统能力：** SystemCapability.Security.DataLossPrevention 489 490**参数：** 491 492| 参数名 | 类型 | 必填 | 说明 | 493| -------- | -------- | -------- | -------- | 494| callback | AsyncCallback<Array<string>> | 是 | 回调函数。err为undefine时表示查询成功；否则为错误对象。 | 495 496**错误码：** 497 498以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 499 500| 错误码ID | 错误信息 | 501| -------- | -------- | 502| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 503| 19100001 | Invalid parameter value. | 504| 19100011 | The system ability works abnormally. | 505 506**示例：** 507 508```ts 509import { dlpPermission } from '@kit.DataProtectionKit'; 510import { BusinessError } from '@kit.BasicServicesKit'; 511 512try { 513 dlpPermission.getDLPSupportedFileTypes((err, res) => { 514 if (err != undefined) { 515 console.error('getDLPSupportedFileTypes error,', err.code, err.message); 516 } else { 517 console.info('res', JSON.stringify(res)); 518 } 519 }); // 获取支持DLP的文件类型 520} catch (err) { 521 console.error('getDLPSupportedFileTypes error,', (err as BusinessError).code, (err as BusinessError).message); 522} 523``` 524 525## dlpPermission.setRetentionState 526 527setRetentionState(docUris: Array<string>): Promise<void> 528 529打开DLP文件时自动安装沙箱，关闭DLP文件时自动卸载沙箱。设置沙箱保留状态时DLP文件关闭时自动卸载暂时失效。使用Promise方式异步返回结果。 530 531**系统能力：** SystemCapability.Security.DataLossPrevention 532 533**参数：** 534 535| 参数名 | 类型 | 必填 | 说明 | 536| -------- | -------- | -------- | -------- | 537| docUris | Array<string> | 是 | 表示需要设置保留状态的文件uri列表。 | 538 539**返回值：** 540 541| 类型 | 说明 | 542| -------- | -------- | 543| Promise<void> | Promise对象。无返回结果的Promise对象。 | 544 545**错误码：** 546 547以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 548 549| 错误码ID | 错误信息 | 550| -------- | -------- | 551| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 552| 19100001 | Invalid parameter value. | 553| 19100006 | No permission to call this API, which is available only for DLP sandbox applications. | 554| 19100011 | The system ability works abnormally. | 555 556**示例：** 557 558```ts 559import { dlpPermission } from '@kit.DataProtectionKit'; 560import { BusinessError } from '@kit.BasicServicesKit'; 561 562let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp"; 563try { 564 dlpPermission.isInSandbox().then((inSandbox) => { // 是否在沙箱内 565 if (inSandbox) { 566 dlpPermission.setRetentionState([uri]); // 设置沙箱保留 567 } 568 }); 569} catch (err) { 570 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 571} 572``` 573 574## dlpPermission.setRetentionState 575 576setRetentionState(docUris: Array<string>, callback: AsyncCallback<void>): void 577 578打开DLP文件时自动安装沙箱，关闭DLP文件时自动卸载沙箱。设置沙箱保留状态时DLP文件关闭时自动卸载暂时失效。使用callback方式异步返回结果。 579 580**系统能力：** SystemCapability.Security.DataLossPrevention 581 582**参数：** 583 584| 参数名 | 类型 | 必填 | 说明 | 585| -------- | -------- | -------- | -------- | 586| docUris | Array<string> | 是 | 表示需要设置保留状态的文件uri列表。 | 587| callback | AsyncCallback<void> | 是 | 回调函数。err为undefine时表示设置成功；否则为错误对象。 | 588 589**错误码：** 590 591以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 592 593| 错误码ID | 错误信息 | 594| -------- | -------- | 595| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 596| 19100001 | Invalid parameter value. | 597| 19100006 | No permission to call this API, which is available only for DLP sandbox applications. | 598| 19100011 | The system ability works abnormally. | 599 600**示例：** 601 602```ts 603import { dlpPermission } from '@kit.DataProtectionKit'; 604import { BusinessError } from '@kit.BasicServicesKit'; 605 606let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp"; 607try { 608 dlpPermission.setRetentionState([uri], (err, res) => { 609 if (err != undefined) { 610 console.error('setRetentionState error,', err.code, err.message); 611 } else { 612 console.info('setRetentionState success'); 613 console.info('res', JSON.stringify(res)); 614 } 615 }); // 设置沙箱保留 616} catch (err) { 617 console.error('setRetentionState error,', (err as BusinessError).code, (err as BusinessError).message); 618} 619``` 620 621## dlpPermission.cancelRetentionState 622 623cancelRetentionState(docUris: Array<string>): Promise<void> 624 625取消沙箱保留状态即恢复DLP文件关闭时自动卸载沙箱策略。使用Promise方式异步返回结果。 626 627**系统能力：** SystemCapability.Security.DataLossPrevention 628 629**参数：** 630 631| 参数名 | 类型 | 必填 | 说明 | 632| -------- | -------- | -------- | -------- | 633| docUris | Array<string> | 是 | 表示需要设置保留状态的文件uri列表。 | 634 635**返回值：** 636 637| 类型 | 说明 | 638| -------- | -------- | 639| Promise<void> | Promise对象。无返回结果的Promise对象。 | 640 641**错误码：** 642 643以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 644 645| 错误码ID | 错误信息 | 646| -------- | -------- | 647| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 648| 19100001 | Invalid parameter value. | 649| 19100011 | The system ability works abnormally. | 650 651**示例：** 652 653```ts 654import { dlpPermission } from '@kit.DataProtectionKit'; 655import { BusinessError } from '@kit.BasicServicesKit'; 656 657let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp"; 658try { 659 dlpPermission.cancelRetentionState([uri]); // 取消沙箱保留 660} catch (err) { 661 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 662} 663``` 664 665## dlpPermission.cancelRetentionState 666 667cancelRetentionState(docUris: Array<string>, callback: AsyncCallback<void>): void 668 669取消沙箱保留状态即恢复DLP文件关闭时自动卸载沙箱策略。使用callback方式异步返回结果。 670 671**系统能力：** SystemCapability.Security.DataLossPrevention 672 673**参数：** 674 675| 参数名 | 类型 | 必填 | 说明 | 676| -------- | -------- | -------- | -------- | 677| docUris | Array<string> | 是 | 表示需要设置保留状态的文件uri列表。 | 678| callback | AsyncCallback<void> | 是 | 回调函数。err为undefine时表示设置成功；否则为错误对象。 | 679 680**错误码：** 681 682以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 683 684| 错误码ID | 错误信息 | 685| -------- | -------- | 686| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 687| 19100001 | Invalid parameter value. | 688| 19100011 | The system ability works abnormally. | 689 690**示例：** 691 692```ts 693import { dlpPermission } from '@kit.DataProtectionKit'; 694import { BusinessError } from '@kit.BasicServicesKit'; 695 696let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp"; 697try { 698 dlpPermission.cancelRetentionState([uri], (err, res) => { 699 if (err != undefined) { 700 console.error('cancelRetentionState error,', err.code, err.message); 701 } else { 702 console.info('cancelRetentionState success'); 703 } 704 }); // 取消沙箱保留 705} catch (err) { 706 console.error('cancelRetentionState error,', (err as BusinessError).code, (err as BusinessError).message); 707} 708``` 709 710## dlpPermission.getRetentionSandboxList 711 712getRetentionSandboxList(bundleName?: string): Promise<Array<RetentionSandboxInfo>> 713 714查询指定应用的保留沙箱信息列表。使用Promise方式异步返回结果。 715 716**系统能力：** SystemCapability.Security.DataLossPrevention 717 718**参数：** 719 720| 参数名 | 类型 | 必填 | 说明 | 721| -------- | -------- | -------- | -------- | 722| bundleName | string | 否 | 指定应用包名。默认为空，查询当前应用的保留沙箱信息列表。 | 723 724**返回值：** 725 726| 类型 | 说明 | 727| -------- | -------- | 728| Promise<Array<[RetentionSandboxInfo](#retentionsandboxinfo)>> | Promise对象。返回查询的沙箱信息列表。 | 729 730**错误码：** 731 732以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 733 734| 错误码ID | 错误信息 | 735| -------- | -------- | 736| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 737| 19100001 | Invalid parameter value. | 738| 19100007 | No permission to call this API, which is available only for non-DLP sandbox applications. | 739| 19100011 | The system ability works abnormally. | 740 741**示例：** 742 743```ts 744import { dlpPermission } from '@kit.DataProtectionKit'; 745import { BusinessError } from '@kit.BasicServicesKit'; 746 747try { 748 let res: Promise<Array<dlpPermission.RetentionSandboxInfo>> = dlpPermission.getRetentionSandboxList(); // 获取沙箱保留列表 749 console.info('res', JSON.stringify(res)) 750} catch (err) { 751 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 752} 753``` 754 755## dlpPermission.getRetentionSandboxList 756 757getRetentionSandboxList(bundleName: string, callback: AsyncCallback<Array<RetentionSandboxInfo>>): void 758 759查询指定应用的保留沙箱信息列表。使用callback方式异步返回结果。 760 761**系统能力：** SystemCapability.Security.DataLossPrevention 762 763**参数：** 764 765| 参数名 | 类型 | 必填 | 说明 | 766| -------- | -------- | -------- | -------- | 767| bundleName | string | 是 | 指定应用包名。 | 768| callback | AsyncCallback<Array<[RetentionSandboxInfo](#retentionsandboxinfo)>> | 是 | 回调函数。err为undefine时表示查询成功；否则为错误对象。 | 769 770**错误码：** 771 772以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 773 774| 错误码ID | 错误信息 | 775| -------- | -------- | 776| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 777| 19100001 | Invalid parameter value. | 778| 19100007 | No permission to call this API, which is available only for non-DLP sandbox applications. | 779| 19100011 | The system ability works abnormally. | 780 781**示例：** 782 783```ts 784import { dlpPermission } from '@kit.DataProtectionKit'; 785import { BusinessError } from '@kit.BasicServicesKit'; 786 787try { 788 dlpPermission.getRetentionSandboxList("bundleName", (err, res) => { 789 if (err != undefined) { 790 console.error('getRetentionSandboxList error,', err.code, err.message); 791 } else { 792 console.info('res', JSON.stringify(res)); 793 } 794 }); // 获取沙箱保留列表 795} catch (err) { 796 console.error('getRetentionSandboxList error,', (err as BusinessError).code, (err as BusinessError).message); 797} 798``` 799 800## dlpPermission.getRetentionSandboxList 801 802getRetentionSandboxList(callback: AsyncCallback<Array<RetentionSandboxInfo>>): void 803 804查询指定应用的保留沙箱信息列表。使用callback方式异步返回结果。 805 806**系统能力：** SystemCapability.Security.DataLossPrevention 807 808**参数：** 809 810| 参数名 | 类型 | 必填 | 说明 | 811| -------- | -------- | -------- | -------- | 812| callback | AsyncCallback<Array<[RetentionSandboxInfo](#retentionsandboxinfo)>> | 是 | 回调函数。err为undefine时表示查询成功；否则为错误对象。 | 813 814**错误码：** 815 816以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 817 818| 错误码ID | 错误信息 | 819| -------- | -------- | 820| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 821| 19100001 | Invalid parameter value. | 822| 19100007 | No permission to call this API, which is available only for non-DLP sandbox applications. | 823| 19100011 | The system ability works abnormally. | 824 825**示例：** 826 827```ts 828import { dlpPermission } from '@kit.DataProtectionKit'; 829import { BusinessError } from '@kit.BasicServicesKit'; 830 831try { 832 dlpPermission.getRetentionSandboxList((err, res) => { 833 if (err != undefined) { 834 console.error('getRetentionSandboxList error,', err.code, err.message); 835 } else { 836 console.info('res', JSON.stringify(res)); 837 } 838 }); // 获取沙箱保留列表 839} catch (err) { 840 console.error('getRetentionSandboxList error,', (err as BusinessError).code, (err as BusinessError).message); 841} 842``` 843 844## dlpPermission.getDLPFileAccessRecords 845 846getDLPFileAccessRecords(): Promise<Array<AccessedDLPFileInfo>> 847 848查询最近访问的DLP文件列表。使用Promise方式异步返回结果。 849 850**系统能力：** SystemCapability.Security.DataLossPrevention 851 852**返回值：** 853 854| 类型 | 说明 | 855| -------- | -------- | 856| Promise<Array<[AccessedDLPFileInfo](#accesseddlpfileinfo)>> | Promise对象。返回最近访问的DLP文件列表。 | 857 858**错误码：** 859 860以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 861 862| 错误码ID | 错误信息 | 863| -------- | -------- | 864| 19100001 | Invalid parameter value. | 865| 19100007 | No permission to call this API, which is available only for non-DLP sandbox applications. | 866| 19100011 | The system ability works abnormally. | 867 868**示例：** 869 870```ts 871import { dlpPermission } from '@kit.DataProtectionKit'; 872import { BusinessError } from '@kit.BasicServicesKit'; 873 874try { 875 let res: Promise<Array<dlpPermission.AccessedDLPFileInfo>> = dlpPermission.getDLPFileAccessRecords(); // 获取DLP访问列表 876 console.info('res', JSON.stringify(res)) 877} catch (err) { 878 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 879} 880``` 881 882## dlpPermission.getDLPFileAccessRecords 883 884getDLPFileAccessRecords(callback: AsyncCallback<Array<AccessedDLPFileInfo>>): void 885 886查询最近访问的DLP文件列表。使用callback方式异步返回结果。 887 888**系统能力：** SystemCapability.Security.DataLossPrevention 889 890**参数：** 891 892| 参数名 | 类型 | 必填 | 说明 | 893| -------- | -------- | -------- | -------- | 894| callback | AsyncCallback<Array<[AccessedDLPFileInfo](#accesseddlpfileinfo)>> | 是 | 回调函数。err为undefine时表示查询成功；否则为错误对象。 | 895 896**错误码：** 897 898以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 899 900| 错误码ID | 错误信息 | 901| -------- | -------- | 902| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | 903| 19100001 | Invalid parameter value. | 904| 19100007 | No permission to call this API, which is available only for non-DLP sandbox applications. | 905| 19100011 | The system ability works abnormally. | 906 907**示例：** 908 909```ts 910import { dlpPermission } from '@kit.DataProtectionKit'; 911import { BusinessError } from '@kit.BasicServicesKit'; 912 913try { 914 dlpPermission.getDLPFileAccessRecords((err, res) => { 915 if (err != undefined) { 916 console.error('getDLPFileAccessRecords error,', err.code, err.message); 917 } else { 918 console.info('res', JSON.stringify(res)); 919 } 920 }); // 获取DLP访问列表 921} catch (err) { 922 console.error('getDLPFileAccessRecords error,', (err as BusinessError).code, (err as BusinessError).message); 923} 924``` 925 926## dlpPermission.startDLPManagerForResult<sup>11+</sup> 927 928startDLPManagerForResult(context: common.UIAbilityContext, want: Want): Promise<DLPManagerResult> 929 930在当前UIAbility界面以无边框形式打开DLP权限管理应用。使用Promise方式异步返回结果。 931 932**模型约束：** 此接口仅可在Stage模型下使用。 933 934**系统能力：** SystemCapability.Security.DataLossPrevention 935 936**参数：** 937 938| 参数名 | 类型 | 必填 | 说明 | 939| -------- | -------- | -------- | -------- | 940| context | [common.UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | 是 | 当前窗口UIAbility上下文。 | 941| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 请求对象。 | 942 943**返回值：** 944 945| 类型 | 说明 | 946| -------- | -------- | 947| Promise<[DLPManagerResult](#dlpmanagerresult11)> | Promise对象。打开DLP权限管理应用并退出后的结果。 | 948 949**错误码：** 950 951以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 952 953| 错误码ID | 错误信息 | 954| -------- | -------- | 955| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 956| 19100001 | Invalid parameter value. | 957| 19100011 | The system ability works abnormally. | 958| 19100016 | uri missing in want. | 959| 19100017 | displayName missing in want. | 960 961**示例：** 962 963```ts 964import { dlpPermission } from '@kit.DataProtectionKit'; 965import { common, UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 966import { BusinessError } from '@kit.BasicServicesKit'; 967 968try { 969 let context = getContext() as common.UIAbilityContext; // 获取当前UIAbilityContext 970 let want: Want = { 971 "uri": "file://docs/storage/Users/currentUser/Desktop/1.txt", 972 "parameters": { 973 "displayName": "1.txt" 974 } 975 }; // 请求参数 976 dlpPermission.startDLPManagerForResult(context, want).then((res) => { 977 console.info('res.resultCode', res.resultCode); 978 console.info('res.want', JSON.stringify(res.want)); 979 }); // 打开DLP权限管理应用 980} catch (err) { 981 console.error('error', err.code, err.message); // 失败报错 982} 983``` 984 985## dlpPermission.setSandboxAppConfig<sup>11+<sup> 986setSandboxAppConfig(configInfo: string): Promise<void> 987 988设置沙箱应用配置信息，使用Promise方式异步返回结果。 989 990**系统能力：** SystemCapability.Security.DataLossPrevention 991 992**参数：** 993 994| 参数名 | 类型 | 必填 | 说明 | 995| -------- | -------- | -------- | -------- | 996| configInfo | string | 是 | 沙箱应用配置信息。 | 997 998**返回值：** 999 1000| 类型 | 说明 | 1001| -------- | -------- | 1002| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1003 1004**错误码：** 1005 1006以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 1007 1008| 错误码ID | 错误信息 | 1009| -------- | -------- | 1010| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1011| 19100001 | Invalid parameter value. | 1012| 19100007 | No permission to call this API, which is available only for non-DLP sandbox applications. | 1013| 19100011 | The system ability works abnormally. | 1014| 19100018 | Not authorized application. | 1015 1016**示例：** 1017 1018```ts 1019import { dlpPermission } from '@kit.DataProtectionKit'; 1020import { BusinessError } from '@kit.BasicServicesKit'; 1021 1022try { 1023 dlpPermission.setSandboxAppConfig('configInfo'); // 设置沙箱应用配置信息 1024} catch (err) { 1025 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 1026} 1027``` 1028 1029## dlpPermission.cleanSandboxAppConfig<sup>11+<sup> 1030cleanSandboxAppConfig(): Promise<void> 1031 1032清理沙箱应用配置信息，使用Promise方式异步返回结果。 1033 1034**系统能力：** SystemCapability.Security.DataLossPrevention 1035 1036**返回值：** 1037 1038| 类型 | 说明 | 1039| -------- | -------- | 1040| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1041 1042**错误码：** 1043 1044以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 1045 1046| 错误码ID | 错误信息 | 1047| -------- | -------- | 1048| 19100001 | Invalid parameter value. | 1049| 19100007 | No permission to call this API, which is available only for non-DLP sandbox applications. | 1050| 19100011 | The system ability works abnormally. | 1051| 19100018 | Not authorized application. | 1052 1053**示例：** 1054 1055```ts 1056import { dlpPermission } from '@kit.DataProtectionKit'; 1057import { BusinessError } from '@kit.BasicServicesKit'; 1058 1059try { 1060 dlpPermission.cleanSandboxAppConfig(); // 清理沙箱应用配置信息 1061} catch (err) { 1062 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 1063} 1064``` 1065 1066## dlpPermission.getSandboxAppConfig<sup>11+<sup> 1067getSandboxAppConfig(): Promise<string> 1068 1069获取沙箱应用配置信息，使用Promise方式异步返回结果 1070 1071**系统能力：** SystemCapability.Security.DataLossPrevention 1072 1073**返回值：** 1074| 类型 | 说明 | 1075| -------- | -------- | 1076| Promise<string> | Promise对象。返回沙箱应用配置信息。 | 1077 1078**错误码：** 1079 1080以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 1081 1082| 错误码ID | 错误信息 | 1083| -------- | -------- | 1084| 19100001 | Invalid parameter value. | 1085| 19100011 | The system ability works abnormally. | 1086| 19100018 | Not authorized application. | 1087 1088**示例：** 1089 1090```ts 1091import { dlpPermission } from '@kit.DataProtectionKit'; 1092import { BusinessError } from '@kit.BasicServicesKit'; 1093 1094try { 1095 dlpPermission.getSandboxAppConfig().then((res) => { 1096 console.info('res', JSON.stringify(res)); 1097 }); // 获取沙箱应用配置信息 1098} catch (err) { 1099 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 1100} 1101``` 1102 1103## dlpPermission.isDLPFeatureProvided<sup>12+<sup> 1104isDLPFeatureProvided(): Promise<boolean> 1105 1106查询当前系统是否提供DLP特性，使用Promise方式异步返回结果 1107 1108**系统能力：** SystemCapability.Security.DataLossPrevention 1109 1110**返回值：** 1111| 类型 | 说明 | 1112| -------- | -------- | 1113| Promise<boolean> | Promise对象。返回当前系统是否提供DLP特性。 | 1114 1115**错误码：** 1116 1117以下错误码的详细介绍请参见[DLP服务错误码](errorcode-dlp.md)。 1118 1119| 错误码ID | 错误信息 | 1120| -------- | -------- | 1121| 19100011 | The system ability works abnormally. | 1122 1123**示例：** 1124 1125```ts 1126import { dlpPermission } from '@kit.DataProtectionKit'; 1127import { BusinessError } from '@kit.BasicServicesKit'; 1128 1129dlpPermission.isDLPFeatureProvided().then((res) => { 1130 console.info('res', JSON.stringify(res)); 1131}).catch((err: BusinessError) => { 1132 console.error('error', (err as BusinessError).code, (err as BusinessError).message); // 失败报错 1133}); 1134``` 1135 1136## ActionFlagType 1137 1138可以对DLP文件进行的操作类型枚举。例如：DLP沙箱应用可以根据是否具有操作权限，对其按钮进行置灰 1139 1140**系统能力：** SystemCapability.Security.DataLossPrevention 1141 1142| 名称 | 值 | 说明 | 1143| -------- | -------- | -------- | 1144| ACTION_VIEW | 0x00000001 | 表示文件的查看权限。 | 1145| ACTION_SAVE | 0x00000002 | 表示文件的保存权限。 | 1146| ACTION_SAVE_AS | 0x00000004 | 表示文件的另存为权限。 | 1147| ACTION_EDIT | 0x00000008 | 表示文件的编辑权限。 | 1148| ACTION_SCREEN_CAPTURE | 0x00000010 | 表示文件的截屏权限。 | 1149| ACTION_SCREEN_SHARE | 0x00000020 | 表示文件的共享屏幕权限。 | 1150| ACTION_SCREEN_RECORD | 0x00000040 | 表示文件的录屏权限。 | 1151| ACTION_COPY | 0x00000080 | 表示文件的复制权限。 | 1152| ACTION_PRINT | 0x00000100 | 表示文件的打印权限。 | 1153| ACTION_EXPORT | 0x00000200 | 表示文件的导出权限。 | 1154| ACTION_PERMISSION_CHANGE | 0x00000400 | 表示文件的修改文件权限。 | 1155 1156## DLPFileAccess 1157 1158DLP文件授权类型的枚举。 1159 1160**系统能力：** SystemCapability.Security.DataLossPrevention 1161 1162| 名称 | 值 | 说明 | 1163| -------- | -------- | -------- | 1164| NO_PERMISSION | 0 | 表示无文件权限。 | 1165| READ_ONLY | 1 | 表示文件的只读权限。 | 1166| CONTENT_EDIT | 2 | 表示文件的编辑权限。 | 1167| FULL_CONTROL | 3 | 表示文件的完全控制权限。 | 1168 1169## DLPPermissionInfo 1170 1171表示DLP文件的权限信息。 1172 1173**系统能力：** SystemCapability.Security.DataLossPrevention 1174 1175| 名称 | 类型 | 可读 | 可写 | 说明 | 1176| -------- | -------- | -------- | -------- | -------- | 1177| dlpFileAccess | [DLPFileAccess](#dlpfileaccess) | 是 | 否 | 表示DLP文件针对用户的授权类型，例如：只读 | 1178| flags | number | 是 | 否 | 表示DLP文件的详细操作权限，是不同[ActionFlagType](#actionflagtype)的组合。 | 1179 1180## AccessedDLPFileInfo 1181 1182表示被打开的DLP文件的信息。 1183 1184**系统能力：** SystemCapability.Security.DataLossPrevention 1185 1186| 名称 | 类型 | 可读 | 可写 | 说明 | 1187| -------- | -------- | -------- | -------- | -------- | 1188| uri | string | 是 | 否 | 表示DLP文件的uri。 | 1189| lastOpenTime | number | 是 | 否 | 表示DLP文件最近打开时间。 | 1190 1191## DLPManagerResult<sup>11+</sup> 1192 1193表示打开DLP权限管理应用的结果。 1194 1195**模型约束：** 此接口仅可在Stage模型下使用。 1196 1197**系统能力：** SystemCapability.Security.DataLossPrevention 1198 1199| 名称 | 类型 | 可读 | 可写 | 说明 | 1200| -------- | -------- | -------- | -------- | -------- | 1201| resultCode | number | 是 | 否 | 表示打开DLP权限管理应用并退出后返回的结果码。 | 1202| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 否 | 表示打开DLP权限管理应用并退出后返回的数据。 | 1203 1204## RetentionSandboxInfo 1205 1206保留沙箱的沙箱信息。 1207 1208**系统能力：** SystemCapability.Security.DataLossPrevention 1209 1210| 名称 | 类型 | 可读 | 可写 | 说明 | 1211| -------- | -------- | -------- | -------- | -------- | 1212| appIndex | number | 是 | 否 | 表示DLP沙箱应用索引。 | 1213| bundleName | string | 是 | 否 | 表示应用包名。 | 1214| docUris | Array<string> | 是 | 否 | 表示DLP文件的URI列表。 | 1215 1216