1# @ohos.telephony.esim (eSIM卡管理) (系统接口) 2<!--Kit: Telephony Kit--> 3<!--Subsystem: Telephony--> 4<!--Owner: @yangyannanyangyannan--> 5<!--Designer: @ghxbob--> 6<!--Tester: @weitiantian--> 7<!--Adviser: @zhang_yixin13--> 8 9穿戴设备支持eSIM，电话服务提供API给eSIM卡管理和eSIM卡服务使用。 10 11> **说明：** 12> 13> 本模块首批接口从API version 18开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.telephony.esim (eSIM卡管理)](js-apis-esim.md)。 15 16## 导入模块 17 18```ts 19import { eSIM } from '@kit.TelephonyKit'; 20``` 21 22## eSIM.getEid<sup>18+</sup> 23 24getEid\(slotId: number\): Promise\<string\> 25 26获取指定卡槽标识eUICC硬件的EID。 27 28**系统接口：** 此接口为系统接口。 29 30**需要权限**： ohos.permission.GET_TELEPHONY_ESIM_STATE 31 32**系统能力**：SystemCapability.Telephony.CoreService.Esim 33 34**参数：** 35 36| 参数名 | 类型 | 必填 | 说明 | 37| ------ | ------ | ---- | -------------------------------------- | 38| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 39 40**返回值：** 41 42| 类型 | 说明 | 43| --------------------- | ---------------------------------- | 44| Promise\<string\> | 返回指定卡槽标识eUICC硬件的EID。 | 45 46**错误码：** 47 48以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 49 50| 错误码ID | 错误信息 | 51| --------------------- | ---------------------------------- | 52| 201 | Permission denied. | 53| 202 | Non-system applications use system APIs. | 54| 401 | Invalid parameter value.| 55| 801 | Capability not supported. | 56|3120001| Service connection failed. | 57|3120002| System internal error. | 58 59**示例：** 60 61```ts 62import { eSIM } from '@kit.TelephonyKit'; 63 64let eid: string = eSIM.getEid(0); 65console.log(`the EID is:` + eid); 66``` 67 68## eSIM.getOsuStatus<sup>18+</sup> 69 70getOsuStatus\(slotId: number\): Promise\<OsuStatus\> 71 72获取指定卡槽操作系统升级的状态。使用Promise异步回调。 73 74**系统接口：** 此接口为系统接口。 75 76**需要权限**： ohos.permission.GET_TELEPHONY_ESIM_STATE 77 78**系统能力**：SystemCapability.Telephony.CoreService.Esim 79 80**参数：** 81 82| 参数名 | 类型 | 必填 | 说明 | 83| ------ | ------ | ---- | -------------------------------------- | 84| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 85 86**返回值：** 87 88| 类型 | 说明 | 89| --------------------- | ---------------------------------- | 90| Promise\<[OsuStatus](#osustatus18)\> | Promise对象，返回操作系统升级的状态。<br/> 1. 正在升级。 <br/> 2. 升级失败。<br/> 3. 升级成功。<br/> 4. 当前版本是最新版本。<br/> 5. 升级服务不可用。 | 91 92**错误码：** 93 94以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 95 96| 错误码ID | 错误信息 | 97| --------------------- | ---------------------------------- | 98| 201 | Permission denied. | 99| 202 | Non-system applications use system APIs. | 100| 401 | Invalid parameter value.| 101| 801 | Capability not supported. | 102|3120001| Service connection failed. | 103|3120002| System internal error. | 104 105**示例：** 106 107```ts 108import { BusinessError } from '@kit.BasicServicesKit'; 109import { eSIM } from '@kit.TelephonyKit'; 110 111eSIM.getOsuStatus(0).then(() => { 112 console.log(`getOsuStatus invoking succeeded.`); 113}).catch((err: BusinessError) => { 114 console.error(`getOsuStatus, promise: err->${JSON.stringify(err)}`); 115}); 116``` 117 118## eSIM.startOsu<sup>18+</sup> 119 120startOsu\(slotId: number\): Promise\<OsuStatus\> 121 122如果指定卡槽的操作系统不是最新的，则执行操作系统升级。使用Promise异步回调。 123 124**系统接口：** 此接口为系统接口。 125 126**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 127 128**系统能力**：SystemCapability.Telephony.CoreService.Esim 129 130**参数：** 131 132| 参数名 | 类型 | 必填 | 说明 | 133| ------ | ------ | ---- | -------------------------------------- | 134| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 135 136**返回值：** 137 138| 类型 | 说明 | 139| --------------------- | ---------------------------------- | 140| Promise\<[OsuStatus](#osustatus18)\> | Promise对象，返回操作系统升级的状态。<br/> 1. 正在升级。 <br/> 2. 升级失败。<br/> 3. 升级成功。<br/> 4. 当前版本是最新版本。<br/> 5. 升级服务不可用。 | 141 142**错误码：** 143 144以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 145 146| 错误码ID | 错误信息 | 147| --------------------- | ---------------------------------- | 148| 201 | Permission denied. | 149| 202 | Non-system applications use system APIs. | 150| 401 | Invalid parameter value.| 151| 801 | Capability not supported. | 152|3120001| Service connection failed. | 153|3120002| System internal error. | 154 155**示例：** 156 157```ts 158import { BusinessError } from '@kit.BasicServicesKit'; 159import { eSIM } from '@kit.TelephonyKit'; 160 161eSIM.startOsu(0).then(() => { 162 console.log(`startOsu invoking succeeded.`); 163}).catch((err: BusinessError) => { 164 console.error(`startOsu, ErrorState: err->${JSON.stringify(err)}`); 165}); 166``` 167 168## eSIM.getDownloadableProfileMetadata<sup>18+</sup> 169 170getDownloadableProfileMetadata\(slotId: number, portIndex: number, profile: DownloadableProfile, forceDisableProfile: boolean\): Promise\<GetDownloadableProfileMetadataResult\> 171 172填充可下载配置文件的元数据。使用Promise异步回调。 173 174**系统接口：** 此接口为系统接口。 175 176**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 177 178**系统能力**：SystemCapability.Telephony.CoreService.Esim 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| ------ | ------ | ----- |------------------------------------------------------------------------------------------------------| 184| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 185| portIndex | number | 是 | 插槽的端口索引。 | 186| profile | [DownloadableProfile](./js-apis-esim.md#downloadableprofile18) | 是 | 可下载的配置文件信息。 | 187| forceDisableProfile | boolean | 是 | 是否可直接去激活配置文件。true表示切换配置文件时，如果需要去激活当前的配置文件，则可以直接操作。false表示如果需要去激活当前的配置文件，则会返回错误，并得到用户授权后再继续调用该接口，执行切换配置文件操作。 | 188 189**返回值：** 190 191| 类型 | 说明 | 192| --------------------- | ---------------------------------- | 193| Promise\<[GetDownloadableProfileMetadataResult](#getdownloadableprofilemetadataresult18)\> | Promise对象，返回填充可下载配置文件的元数据。 | 194 195**错误码：** 196 197以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 198 199| 错误码ID | 错误信息 | 200| --------------------- | ---------------------------------- | 201| 201 | Permission denied. | 202| 202 | Non-system applications use system APIs. | 203| 401 | Invalid parameter value.| 204| 801 | Capability not supported. | 205|3120001| Service connection failed. | 206|3120002| System internal error. | 207 208**示例：** 209 210```ts 211import { BusinessError } from '@kit.BasicServicesKit'; 212import { eSIM } from '@kit.TelephonyKit'; 213 214let profile: eSIM.DownloadableProfile = { 215 activationCode:'1', 216 confirmationCode:'1', 217 carrierName:'test', 218 accessRules:[{ 219 certificateHashHexStr:'test', 220 packageName:'com.example.testcoreservice', 221 accessType:0 222 }] 223}; 224 225eSIM.getDownloadableProfileMetadata(0, 0, profile, true).then((data: eSIM.GetDownloadableProfileMetadataResult) => { 226 console.log(`getDownloadableProfileMetadata, GetDownloadableProfileMetadataResult: data->${JSON.stringify(data)}`); 227}).catch((err: BusinessError) => { 228 console.error(`getDownloadableProfileMetadata, GetDownloadableProfileMetadataResult: err->${JSON.stringify(err)}`); 229}); 230``` 231 232## eSIM.getDownloadableProfiles<sup>18+</sup> 233 234getDownloadableProfiles\(slotId: number, portIndex: number, 235forceDisableProfile: boolean\): Promise\<GetDownloadableProfilesResult\> 236 237获取可用的可下载配置文件列表。使用Promise异步回调。 238 239**系统接口：** 此接口为系统接口。 240 241**需要权限**： ohos.permission.GET_TELEPHONY_ESIM_STATE 242 243**系统能力**：SystemCapability.Telephony.CoreService.Esim 244 245**参数：** 246 247| 参数名 | 类型 | 必填 | 说明 | 248| ------ | ------ | ----- | ----- | 249| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 250| portIndex | number | 是 | 插槽的端口索引。 | 251| forceDisableProfile | boolean | 是 | 是否可直接去激活配置文件。true表示切换配置文件时，如果需要去激活当前的配置文件，则可以直接操作。false表示如果需要去激活当前的配置文件，则会返回错误，并得到用户授权后再继续调用该接口，执行切换配置文件操作。| 252 253**返回值：** 254 255| 类型 | 说明 | 256| --------------------- | ---------------------------------- | 257| Promise\<[GetDownloadableProfilesResult](#getdownloadableprofilesresult18)\> | Promise对象，返回可下载配置文件列表。 | 258 259**错误码：** 260 261以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 262 263| 错误码ID | 错误信息 | 264| --------------------- | ---------------------------------- | 265| 201 | Permission denied. | 266| 202 | Non-system applications use system APIs. | 267| 401 | Invalid parameter value.| 268| 801 | Capability not supported. | 269|3120001| Service connection failed. | 270|3120002| System internal error. | 271 272**示例：** 273 274```ts 275import { BusinessError } from '@kit.BasicServicesKit'; 276import { eSIM } from '@kit.TelephonyKit'; 277 278eSIM.getDownloadableProfiles(0, 0, true).then((data: eSIM.GetDownloadableProfilesResult) => { 279 console.log(`getDownloadableProfiles, GetDownloadableProfilesResult: data->${JSON.stringify(data)}`); 280}).catch((err: BusinessError) => { 281 console.error(`getDownloadableProfiles, GetDownloadableProfilesResult: err->${JSON.stringify(err)}`); 282}); 283``` 284 285## eSIM.downloadProfile<sup>18+</sup> 286 287downloadProfile\(slotId: number, portIndex: number, profile: DownloadableProfile, 288configuration: DownloadConfiguration\): Promise\<DownloadProfileResult\> 289 290下载配置文件。使用Promise异步回调。 291 292**系统接口：** 此接口为系统接口。 293 294**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 295 296**系统能力**：SystemCapability.Telephony.CoreService.Esim 297 298**参数：** 299 300| 参数名 | 类型 | 必填 | 说明 | 301| ------ | ------ | ----- | ----- | 302| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 303| portIndex | number | 是 | 插槽的端口索引。 | 304| profile | [DownloadableProfile](./js-apis-esim.md#downloadableprofile18) | 是 | 可下载的配置文件信息。 | 305| configuration | [DownloadConfiguration](#downloadconfiguration18) | 是 | 下载的配置信息。 | 306 307**返回值：** 308 309| 类型 | 说明 | 310| --------------------- | ---------------------------------- | 311| Promise\<[DownloadProfileResult](#downloadprofileresult18)\> | Promise对象，返回下载配置文件的结果。 | 312 313**错误码：** 314 315以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 316 317| 错误码ID | 错误信息 | 318| --------------------- | ---------------------------------- | 319| 201 | Permission denied. | 320| 202 | Non-system applications use system APIs. | 321| 401 | Invalid parameter value.| 322| 801 | Capability not supported. | 323|3120001| Service connection failed. | 324|3120002| System internal error. | 325 326**示例：** 327 328```ts 329import { BusinessError } from '@kit.BasicServicesKit'; 330import { eSIM } from '@kit.TelephonyKit'; 331 332let profile: eSIM.DownloadableProfile = { 333 activationCode:'1', 334 confirmationCode:'1', 335 carrierName:'test', 336 accessRules:[{ 337 certificateHashHexStr:'test', 338 packageName:'com.example.testcoreservice', 339 accessType:0 340 }] 341}; 342 343let configuration: eSIM.DownloadConfiguration = { 344 switchAfterDownload: true, 345 forceDisableProfile: true, 346 isPprAllowed: true, 347}; 348 349eSIM.downloadProfile(0, 0, profile, configuration).then((data: eSIM.DownloadProfileResult) => { 350 console.log(`downloadProfile, DownloadProfileResult: data->${JSON.stringify(data)}`); 351}).catch((err: BusinessError) => { 352 console.error(`downloadProfile, DownloadProfileResult: err->${JSON.stringify(err)}`); 353}); 354``` 355 356## eSIM.getEuiccProfileInfoList<sup>18+</sup> 357 358getEuiccProfileInfoList\(slotId: number\): Promise\<GetEuiccProfileInfoListResult\> 359 360获取配置文件信息列表。使用Promise异步回调。 361 362**系统接口：** 此接口为系统接口。 363 364**需要权限**： ohos.permission.GET_TELEPHONY_ESIM_STATE 365 366**系统能力**：SystemCapability.Telephony.CoreService.Esim 367 368**参数：** 369 370| 参数名 | 类型 | 必填 | 说明 | 371| ------ | ------ | ----- | ----- | 372| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 373 374**返回值：** 375 376| 类型 | 说明 | 377| --------------------- | ---------------------------------- | 378| Promise\<[GetEuiccProfileInfoListResult](#geteuiccprofileinfolistresult18)\> | Promise对象，返回配置文件信息列表。 | 379 380**错误码：** 381 382以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 383 384| 错误码ID | 错误信息 | 385| --------------------- | ---------------------------------- | 386| 201 | Permission denied. | 387| 202 | Non-system applications use system APIs. | 388| 401 | Invalid parameter value.| 389| 801 | Capability not supported. | 390|3120001| Service connection failed. | 391|3120002| System internal error. | 392 393**示例：** 394 395```ts 396import { BusinessError } from '@kit.BasicServicesKit'; 397import { eSIM } from '@kit.TelephonyKit'; 398 399eSIM.getEuiccProfileInfoList(0).then((data: eSIM.GetEuiccProfileInfoListResult) => { 400 console.log(`getEuiccProfileInfoList, GetEuiccProfileInfoListResult: data->${JSON.stringify(data)}`); 401}).catch((err: BusinessError) => { 402 console.error(`getEuiccProfileInfoList, GetEuiccProfileInfoListResult: err->${JSON.stringify(err)}`); 403}); 404``` 405 406## eSIM.getEuiccInfo<sup>18+</sup> 407 408getEuiccInfo\(slotId: number\): Promise\<EuiccInfo\> 409 410获取eUICC信息。使用Promise异步回调。 411 412**系统接口：** 此接口为系统接口。 413 414**需要权限**： ohos.permission.GET_TELEPHONY_ESIM_STATE 415 416**系统能力**：SystemCapability.Telephony.CoreService.Esim 417 418**参数：** 419 420| 参数名 | 类型 | 必填 | 说明 | 421| ------ | ------ | ----- | ----- | 422| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 423 424**返回值：** 425 426| 类型 | 说明 | 427| --------------------- | ---------------------------------- | 428| Promise\<[EuiccInfo](#euiccinfo18)\> | Promise对象，返回eUicc信息。 | 429 430**错误码：** 431 432以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 433 434| 错误码ID | 错误信息 | 435| --------------------- | ---------------------------------- | 436| 201 | Permission denied. | 437| 202 | Non-system applications use system APIs. | 438| 401 | Invalid parameter value.| 439| 801 | Capability not supported. | 440|3120001| Service connection failed. | 441|3120002| System internal error. | 442 443**示例：** 444 445```ts 446import { BusinessError } from '@kit.BasicServicesKit'; 447import { eSIM } from '@kit.TelephonyKit'; 448 449eSIM.getEuiccInfo(0).then((data: eSIM.EuiccInfo) => { 450 console.log(`getEuiccInfo, EuiccInfo: data->${JSON.stringify(data)}`); 451}).catch((err: BusinessError) => { 452 console.error(`getEuiccInfo, EuiccInfo: err->${JSON.stringify(err)}`); 453}); 454``` 455 456## eSIM.deleteProfile<sup>18+</sup> 457 458deleteProfile\(slotId: number, iccid: string\): Promise\<ResultCode\> 459 460删除配置文件。使用Promise异步回调。 461 462**系统接口：** 此接口为系统接口。 463 464**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 465 466**系统能力**：SystemCapability.Telephony.CoreService.Esim 467 468**参数：** 469 470| 参数名 | 类型 | 必填 | 说明 | 471| ------ | ------ | ----- | ----- | 472| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 473| iccid | string | 是 | 配置文件的Id。 | 474 475**返回值：** 476 477| 类型 | 说明 | 478| --------------------- | ---------------------------------- | 479| Promise\<[ResultCode](#resultcode18)\> | Promise对象，返回删除配置文件的结果码。 | 480 481**错误码：** 482 483以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 484 485| 错误码ID | 错误信息 | 486| --------------------- | ---------------------------------- | 487| 201 | Permission denied. | 488| 202 | Non-system applications use system APIs. | 489| 401 | Invalid parameter value.| 490| 801 | Capability not supported. | 491|3120001| Service connection failed. | 492|3120002| System internal error. | 493 494**示例：** 495 496```ts 497import { BusinessError } from '@kit.BasicServicesKit'; 498import { eSIM } from '@kit.TelephonyKit'; 499 500eSIM.deleteProfile(0, testId).then(() => { 501 console.log(`deleteProfile invoking succeeded.`); 502}).catch((err: BusinessError) => { 503 console.error(`deleteProfile, ErrorState: err->${JSON.stringify(err)}`); 504}); 505``` 506 507## eSIM.switchToProfile<sup>18+</sup> 508 509switchToProfile\(slotId: number, portIndex: number, iccid: string, 510forceDisableProfile: boolean\): Promise\<ResultCode\> 511 512切换到(启用)给定的配置文件。使用Promise异步回调。 513 514**系统接口：** 此接口为系统接口。 515 516**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 517 518**系统能力**：SystemCapability.Telephony.CoreService.Esim 519 520**参数：** 521 522| 参数名 | 类型 | 必填 | 说明 | 523| ------ | ------ | ----- | ----- | 524| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 525| portIndex | number | 是 | 插槽的端口索引。 | 526| iccid | string | 是 | 配置文件的Id。 | 527| forceDisableProfile | boolean | 是 | 是否可直接去激活配置文件。true表示切换配置文件时，如果需要去激活当前的配置文件，则可以直接操作。false表示如果需要去激活当前的配置文件，则会返回错误，并得到用户授权后再继续调用该接口，执行切换配置文件操作。| 528 529**返回值：** 530 531| 类型 | 说明 | 532| --------------------- | ---------------------------------- | 533| Promise\<[ResultCode](#resultcode18)\> | Promise对象，返回切换配置文件的结果码。 | 534 535**错误码：** 536 537以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 538 539| 错误码ID | 错误信息 | 540| --------------------- | ---------------------------------- | 541| 201 | Permission denied. | 542| 202 | Non-system applications use system APIs. | 543| 401 | Invalid parameter value.| 544| 801 | Capability not supported. | 545|3120001| Service connection failed. | 546|3120002| System internal error. | 547 548**示例：** 549 550```ts 551import { BusinessError } from '@kit.BasicServicesKit'; 552import { eSIM } from '@kit.TelephonyKit'; 553 554eSIM.switchToProfile(0, 0, testId, true).then(() => { 555 console.log(`switchToProfile invoking succeeded.`); 556}).catch((err: BusinessError) => { 557 console.error(`switchToProfile, ErrorState: err->${JSON.stringify(err)}`); 558}); 559``` 560 561## eSIM.setProfileNickname<sup>18+</sup> 562 563setProfileNickname\(slotId: number, iccid: string, nickname: string\): Promise\<ResultCode\> 564 565设置给定配置文件的昵称。使用Promise异步回调。 566 567**系统接口：** 此接口为系统接口。 568 569**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 570 571**系统能力**：SystemCapability.Telephony.CoreService.Esim 572 573**参数：** 574 575| 参数名 | 类型 | 必填 | 说明 | 576| ------ | ------ | ----- | ----- | 577| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 578| iccid | string | 是 | 配置文件的Id。 | 579| nickname | string | 是 | 昵称。 | 580 581**返回值：** 582 583| 类型 | 说明 | 584| --------------------- | ---------------------------------- | 585| Promise\<[ResultCode](#resultcode18)\> | Promise对象，返回设置昵称的结果码。 | 586 587**错误码：** 588 589以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 590 591| 错误码ID | 错误信息 | 592| --------------------- | ---------------------------------- | 593| 201 | Permission denied. | 594| 202 | Non-system applications use system APIs. | 595| 401 | Invalid parameter value.| 596| 801 | Capability not supported. | 597|3120001| Service connection failed. | 598|3120002| System internal error. | 599 600**示例：** 601 602```ts 603import { BusinessError } from '@kit.BasicServicesKit'; 604import { eSIM } from '@kit.TelephonyKit'; 605 606eSIM.setProfileNickname(0, testId, testName).then(() => { 607 console.log(`setProfileNickname invoking succeeded.`); 608}).catch((err: BusinessError) => { 609 console.error(`setProfileNickname, ErrorState: err->${JSON.stringify(err)}`); 610}); 611``` 612 613## eSIM.resetMemory<sup>18+</sup> 614 615resetMemory\(slotId: number, options?: ResetOption\): Promise\<ResultCode\> 616 617清除所有特定配置文件并重置eUICC。使用Promise异步回调。 618 619**系统接口：** 此接口为系统接口。 620 621**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 622 623**系统能力**：SystemCapability.Telephony.CoreService.Esim 624 625**参数：** 626 627| 参数名 | 类型 | 必填 | 说明 | 628| ------ | ------ | ----- | ----- | 629| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 630| options | [ResetOption](#resetoption18) | 否 | 重置状态。 | 631 632**返回值：** 633 634| 类型 | 说明 | 635| --------------------- | ---------------------------------- | 636| Promise\<[ResultCode](#resultcode18)\> | Promise对象，返回重置的结果码。 | 637 638**错误码：** 639 640以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 641 642| 错误码ID | 错误信息 | 643| --------------------- | ---------------------------------- | 644| 201 | Permission denied. | 645| 202 | Non-system applications use system APIs. | 646| 401 | Invalid parameter value.| 647| 801 | Capability not supported. | 648|3120001| Service connection failed. | 649|3120002| System internal error. | 650 651**示例：** 652 653```ts 654import { BusinessError } from '@kit.BasicServicesKit'; 655import { eSIM } from '@kit.TelephonyKit'; 656 657eSIM.resetMemory(0).then(() => { 658 console.log(`resetMemory invoking succeeded.`); 659}).catch((err: BusinessError) => { 660 console.error(`resetMemory, ErrorState: err->${JSON.stringify(err)}`); 661}); 662``` 663 664## eSIM.reserveProfilesForFactoryRestore<sup>18+</sup> 665 666reserveProfilesForFactoryRestore\(slotId: number\): Promise\<ResultCode\> 667 668恢复出厂设置，并保留profiles。使用Promise异步回调。 669 670**系统接口：** 此接口为系统接口。 671 672**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 673 674**系统能力**：SystemCapability.Telephony.CoreService.Esim 675 676**参数：** 677 678| 参数名 | 类型 | 必填 | 说明 | 679| ------ | ------ | ----- | ----- | 680| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 681 682**返回值：** 683 684| 类型 | 说明 | 685| --------------------- | ---------------------------------- | 686| Promise\<[ResultCode](#resultcode18)\> | Promise对象，返回恢复出厂设置的结果码。 | 687 688**错误码：** 689 690以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 691 692| 错误码ID | 错误信息 | 693| --------------------- | ---------------------------------- | 694| 201 | Permission denied. | 695| 202 | Non-system applications use system APIs. | 696| 401 | Invalid parameter value.| 697| 801 | Capability not supported. | 698|3120001| Service connection failed. | 699|3120002| System internal error. | 700 701**示例：** 702 703```ts 704import { BusinessError } from '@kit.BasicServicesKit'; 705import { eSIM } from '@kit.TelephonyKit'; 706 707eSIM.reserveProfilesForFactoryRestore(0).then(() => { 708 console.log(`reserveProfilesForFactoryRestore invoking succeeded.`); 709}).catch((err: BusinessError) => { 710 console.error(`reserveProfilesForFactoryRestore, ErrorState: err->${JSON.stringify(err)}`); 711}); 712``` 713 714## eSIM.setDefaultSmdpAddress<sup>18+</sup> 715 716setDefaultSmdpAddress\(slotId: number, address: string\): Promise\<ResultCode\> 717 718设置或更新eUICC中存储的默认SM-DP+地址。使用Promise异步回调。 719 720**系统接口：** 此接口为系统接口。 721 722**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 723 724**系统能力**：SystemCapability.Telephony.CoreService.Esim 725 726**参数：** 727 728| 参数名 | 类型 | 必填 | 说明 | 729| ------ | ------ | ----- | ----- | 730| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 731| address | string | 是 | 要设置的默认SM-DP+地址。 | 732 733**返回值：** 734 735| 类型 | 说明 | 736| --------------------- | ---------------------------------- | 737| Promise\<[ResultCode](#resultcode18)\> | Promise对象，返回设置默认SM-DP+地址的结果码。 | 738 739**错误码：** 740 741以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 742 743| 错误码ID | 错误信息 | 744| --------------------- | ---------------------------------- | 745| 201 | Permission denied. | 746| 202 | Non-system applications use system APIs. | 747| 401 | Invalid parameter value.| 748| 801 | Capability not supported. | 749|3120001| Service connection failed. | 750|3120002| System internal error. | 751 752**示例：** 753 754```ts 755import { BusinessError } from '@kit.BasicServicesKit'; 756import { eSIM } from '@kit.TelephonyKit'; 757 758eSIM.setDefaultSmdpAddress(0, testAddress).then(() => { 759 console.log(`setDefaultSmdpAddress invoking succeeded.`); 760}).catch((err: BusinessError) => { 761 console.error(`setDefaultSmdpAddress, ErrorState: err->${JSON.stringify(err)}`); 762}); 763``` 764 765## eSIM.getDefaultSmdpAddress<sup>18+</sup> 766 767getDefaultSmdpAddress\(slotId: number\): Promise\<string\> 768 769获取存储在eUICC中的默认SM-DP+地址。使用Promise异步回调。 770 771**系统接口：** 此接口为系统接口。 772 773**需要权限**： ohos.permission.GET_TELEPHONY_ESIM_STATE 774 775**系统能力**：SystemCapability.Telephony.CoreService.Esim 776 777**参数：** 778 779| 参数名 | 类型 | 必填 | 说明 | 780| ------ | ------ | ----- | ----- | 781| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 782 783**返回值：** 784 785| 类型 | 说明 | 786| --------------------- | ---------------------------------- | 787| Promise\<string\> | Promise对象，返回SM-DP+地址。 | 788 789**错误码：** 790 791以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 792 793| 错误码ID | 错误信息 | 794| --------------------- | ---------------------------------- | 795| 201 | Permission denied. | 796| 202 | Non-system applications use system APIs. | 797| 401 | Invalid parameter value.| 798| 801 | Capability not supported. | 799|3120001| Service connection failed. | 800|3120002| System internal error. | 801 802**示例：** 803 804```ts 805import { BusinessError } from '@kit.BasicServicesKit'; 806import { eSIM } from '@kit.TelephonyKit'; 807 808eSIM.getDefaultSmdpAddress(0).then((data: string) => { 809 console.log(`getDefaultSmdpAddress, result: data->${JSON.stringify(data)}`); 810}).catch((err: BusinessError) => { 811 console.error(`getDefaultSmdpAddress, ErrorState: err->${JSON.stringify(err)}`); 812}); 813``` 814 815## eSIM.cancelSession<sup>18+</sup> 816 817cancelSession\(slotId: number, transactionId: string, cancelReason: CancelReason\): Promise\<ResultCode\> 818 819取消会话。使用Promise异步回调。 820 821**系统接口：** 此接口为系统接口。 822 823**需要权限**： ohos.permission.SET_TELEPHONY_ESIM_STATE 824 825**系统能力**：SystemCapability.Telephony.CoreService.Esim 826 827**参数：** 828 829| 参数名 | 类型 | 必填 | 说明 | 830| ------ | ------ | ----- | ----- | 831| slotId | number | 是 | 卡槽ID。<br/>- 0：卡槽1。<br/>- 1：卡槽2。 | 832| transactionId | string | 是 | 业务ID。| 833| cancelReason | [CancelReason](#cancelreason18) | 是 | 取消会话的原因。| 834 835**返回值：** 836 837| 类型 | 说明 | 838| --------------------- | ---------------------------------- | 839| Promise\<[ResultCode](#resultcode18)\> | Promise对象，返回取消会话的结果码。 | 840 841**错误码：** 842 843以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 844 845| 错误码ID | 错误信息 | 846| --------------------- | ---------------------------------- | 847| 201 | Permission denied. | 848| 202 | Non-system applications use system APIs. | 849| 401 | Invalid parameter value.| 850| 801 | Capability not supported. | 851|3120001| Service connection failed. | 852|3120002| System internal error. | 853 854**示例：** 855 856```ts 857import { BusinessError } from '@kit.BasicServicesKit'; 858import { eSIM } from '@kit.TelephonyKit'; 859 860let transactionId = ''; 861eSIM.cancelSession(0, transactionId, eSIM.CancelReason.CANCEL_REASON_END_USER_REJECTION) 862 .then((data: eSIM.ResultCode) => { 863 console.log(`cancelSession, result: data->${JSON.stringify(data)}`); 864 }) 865 .catch((err: BusinessError) => { 866 console.error(`cancelSession execution failed: err->${JSON.stringify(err)}`); 867 }); 868``` 869 870## GetDownloadableProfileMetadataResult<sup>18+</sup> 871 872获取可下载配置文件的元数据。 873 874**系统接口：** 此接口为系统接口。 875 876**系统能力**：SystemCapability.Telephony.CoreService.Esim 877 878| 名称 | 类型 | 必填 | 说明 | 879| ----- |----------------------------------------------------------------| ----- | -----| 880| downloadableProfile | [DownloadableProfile](./js-apis-esim.md#downloadableprofile18) | 是 | 可下载的配置文件信息。 | 881| pprType | number | 是 | 配置文件策略规则类型。 | 882| pprFlag | boolean | 是 | 配置文件是否有策略规则。true表示有策略规则，false表示无策略规则。| 883| iccid | string | 是 | 配置文件的iccId。 | 884| serviceProviderName | string | 是 | 配置文件的服务提供商名称。 | 885| profileName | string | 是 | 配置文件名称。 | 886| profileClass | [ProfileClass](#profileclass18) | 是 | 配置文件类。 | 887| solvableErrors | [SolvableErrors](#solvableerrors18) | 是 | 可解决的错误。 | 888| responseResult | [ResultCode](#resultcode18) | 是 | 操作结果码。 | 889 890## GetDownloadableProfilesResult<sup>18+</sup> 891 892获取默认可下载配置文件的列表。 893 894**系统接口：** 此接口为系统接口。 895 896**系统能力**：SystemCapability.Telephony.CoreService.Esim 897 898| 名称 | 类型 | 必填 | 说明 | 899| ----- |-------------------------------------------------------------------------| ----- | -----| 900| responseResult | [ResultCode](#resultcode18) | 是 | 返回操作结果码。 | 901| downloadableProfiles | Array\<[DownloadableProfile](./js-apis-esim.md#downloadableprofile18)\> | 是 | 可下载配置文件数组。 | 902 903## DownloadProfileResult<sup>18+</sup> 904 905下载配置文件的结果。 906 907**系统接口：** 此接口为系统接口。 908 909**系统能力**：SystemCapability.Telephony.CoreService.Esim 910 911| 名称 | 类型 | 必填 | 说明 | 912| ----- |-------------------------------------| ----- | -----| 913| responseResult | [ResultCode](#resultcode18) | 是 | 操作结果码。 | 914| solvableErrors | [SolvableErrors](#solvableerrors18) | 是 | 可解决错误。 | 915| cardId | number | 是 | 获取卡Id。 | 916 917## GetEuiccProfileInfoListResult<sup>18+</sup> 918 919获取配置文件信息列表。 920 921**系统接口：** 此接口为系统接口。 922 923**系统能力**：SystemCapability.Telephony.CoreService.Esim 924 925| 名称 | 类型 | 必填 | 说明 | 926| ----- |------------------------------------------| ----- | -----| 927| responseResult | [ResultCode](#resultcode18) | 是 | 返回操作结果码。 | 928| profiles | Array\<[EuiccProfile](#euiccprofile18)\> | 是 | 配置文件数组。 | 929| isRemovable | boolean | 是 | eUICC是否可移除。true表示可移除，false表示不可移除。| 930 931## OperatorId<sup>18+</sup> 932 933获取eUICC芯片/设备的相关信息。 934 935**系统接口：** 此接口为系统接口。 936 937**系统能力**：SystemCapability.Telephony.CoreService.Esim 938 939| 名称 | 类型 | 必填 | 说明 | 940| ----- | ----- | ----- | -----| 941| mcc | string | 是 | 移动国家代码。 | 942| mnc | string | 是 | 网络代码。 | 943| gid1 | string | 是 | 组id级别1。 | 944| gid2 | string | 是 | 组id级别2。 | 945 946## EuiccProfile<sup>18+</sup> 947 948配置文件信息。 949 950**系统接口：** 此接口为系统接口。 951 952**系统能力**：SystemCapability.Telephony.CoreService.Esim 953 954| 名称 | 类型 | 必填 | 说明 | 955| ----- |-------------------------------------------------------| ----- | -----| 956| iccid | string | 是 | 配置文件的iccId。 | 957| nickName | string | 是 | 昵称。 | 958| serviceProviderName | string | 是 | 配置文件的服务提供商名称。 | 959| profileName | string | 是 | 配置文件名称。 | 960| state | [ProfileState](#profilestate18) | 是 | 配置文件的状态。 | 961| profileClass | [ProfileClass](#profileclass18) | 是 | 配置文件类。 | 962| operatorId | [OperatorId](#operatorid18) | 是 | 配置文件的操作ID。| 963| policyRules | [PolicyRules](#policyrules18) | 是 | 配置文件策略。 | 964| accessRules | Array\<[AccessRule](./js-apis-esim.md#accessrule18)\> | 是 | 配置文件规则。 | 965 966## EuiccInfo<sup>18+</sup> 967 968euicc信息。 969 970**系统接口：** 此接口为系统接口。 971 972**系统能力**：SystemCapability.Telephony.CoreService.Esim 973 974| 名称 | 类型 | 必填 | 说明 | 975| ----- | ----- | ----- | -----| 976| osVersion | string | 是 | 系统版本。 | 977 978## ResetOption<sup>18+</sup> 979 980重置状态。 981 982**系统接口：** 此接口为系统接口。 983 984**系统能力**：SystemCapability.Telephony.CoreService.Esim 985 986| 名称 | 值 | 说明 | 987| ----- | ----- | ----- | 988|DELETE_OPERATIONAL_PROFILES | 1 | 删除所有操作配置文件。 | 989|DELETE_FIELD_LOADED_TEST_PROFILES | 1 << 1 | 删除所有字段加载的测试配置文件。 | 990|RESET_DEFAULT_SMDP_ADDRESS | 1 << 2 | 重置默认SM-DP+地址。 | 991 992## OsuStatus<sup>18+</sup> 993 994操作系统升级状态。 995 996**系统接口：** 此接口为系统接口。 997 998**系统能力**：SystemCapability.Telephony.CoreService.Esim 999 1000| 名称 | 值 | 说明 | 1001| ----- | ----- | ----- | 1002|EUICC_UPGRADE_IN_PROGRESS | 1 | 升级中。 | 1003|EUICC_UPGRADE_FAILED | 2 | 升级失败。 | 1004|EUICC_UPGRADE_SUCCESSFUL | 3 | 升级成功。 | 1005|EUICC_UPGRADE_ALREADY_LATEST | 4 | 当前为最新版本，无需升级 。| 1006|EUICC_UPGRADE_SERVICE_UNAVAILABLE | 5 | 升级服务不可用。 | 1007 1008## ResultCode<sup>18+</sup> 1009 1010结果码。 1011 1012**系统接口：** 此接口为系统接口。 1013 1014**系统能力**：SystemCapability.Telephony.CoreService.Esim 1015 1016| 名称 | 值 | 说明 | 1017| ----- | ----- | ----- | 1018| RESULT_SOLVABLE_ERRORS | -2 | 用户必须解决可解决的错误。 | 1019| RESULT_MUST_DISABLE_PROFILE | -1 | 必须禁用活动配置文件才能执行操作。 | 1020| RESULT_OK | 0 | 成功。 | 1021| RESULT_GET_EID_FAILED | 201 | 获取EID失败。 | 1022| RESULT_ACTIVATION_CODE_CHANGED | 203 | 最终用户确认后，激活码将被更改。 | 1023| RESULT_ACTIVATION_CODE_INVALID | 204 | 激活码无效。 | 1024| RESULT_SMDP_ADDRESS_INVALID | 205 | SM-DP+服务器地址非法。 | 1025| RESULT_EUICC_INFO_INVALID | 206 | 无效的eUICC信息。 | 1026| RESULT_TLS_HANDSHAKE_FAILED | 207 | TLS握手失败。 | 1027| RESULT_CERTIFICATE_IO_ERROR | 208 | 证书网络连接错误。 | 1028| RESULT_CERTIFICATE_RESPONSE_TIMEOUT | 209 | 证书地址无效或响应超时。 | 1029| RESULT_AUTHENTICATION_FAILED | 210 | 鉴权失败。 | 1030| RESULT_RESPONSE_HTTP_FAILED | 211 | HTTP响应失败。 | 1031| RESULT_CONFIRMATION_CODE_INCORRECT | 212 | 确认码不正确。 | 1032| RESULT_EXCEEDED_CONFIRMATION_CODE_TRY_LIMIT | 213 | 已达到最大确认码尝试次数。 | 1033| RESULT_NO_PROFILE_ON_SERVER | 214 | 服务器上没有可供下载的配置文件。 | 1034| RESULT_TRANSACTION_ID_INVALID | 215 | 事务ID无效。 | 1035| RESULT_SERVER_ADDRESS_INVALID | 216 | 服务器地址无效。 | 1036| RESULT_GET_BOUND_PROFILE_PACKAGE_FAILED | 217 | 获取BPP失败。 | 1037| RESULT_USER_CANCEL_DOWNLOAD | 218 | 最终用户取消下载。 | 1038| RESULT_SERVER_UNAVAILABLE | 220 | 运营商服务器不可用。 | 1039| RESULT_PROFILE_NON_DELETE | 223 | PPR禁止删除文件。 | 1040| RESULT_SMDP_ADDRESS_INCORRECT | 226 | 认证响应服务器地址不匹配。 | 1041| RESULT_ANALYZE_AUTHENTICATION_SERVER_RESPONSE_FAILED | 228 | 解析服务器身份验证响应错误。 | 1042| RESULT_ANALYZE_AUTHENTICATION_CLIENT_RESPONSE_FAILED | 229 | 解析客户端身份验证响应错误。 | 1043| RESULT_ANALYZE_AUTHENTICATION_CLIENT_MATCHING_ID_REFUSED | 231 | 由于匹配ID被拒绝，解析客户端身份验证响应错误。 | 1044| RESULT_PROFILE_TYPE_ERROR_AUTHENTICATION_STOPPED | 233 | 由于配置文件类型中的错误，身份验证已停止。 | 1045| RESULT_CARRIER_SERVER_REFUSED_ERRORS | 249 | 运营商服务器拒绝原因码为3.8的错误。 | 1046| RESULT_CERTIFICATE_INVALID | 251 | 证书无效。 | 1047| RESULT_OUT_OF_MEMORY | 263 | 由于内存不足，配置文件安装失败。 | 1048| RESULT_PPR_FORBIDDEN | 268 | PPR规则禁止此操作。 | 1049| RESULT_NOTHING_TO_DELETE | 270 | 没有可删除的配置文件。 | 1050| RESULT_PPR_NOT_MATCH | 276 | 与PPR约束不匹配。 | 1051| RESULT_CAT_BUSY | 283 | 会话正在进行。 | 1052| RESULT_PROFILE_EID_INVALID | 284 | 此eSIM配置文件已被使用或无效。 | 1053| RESULT_DOWNLOAD_TIMEOUT | 287 | 下载超时。 | 1054| RESULT_SGP_22_OTHER | 400 | SGP.22中定义的其他错误。 | 1055 1056## CancelReason<sup>18+</sup> 1057 1058取消会话的原因。 1059 1060**系统接口：** 此接口为系统接口。 1061 1062**系统能力**：SystemCapability.Telephony.CoreService.Esim 1063 1064| 名称 | 值 | 说明 | 1065| ----- | ----- | ----- | 1066|CANCEL_REASON_END_USER_REJECTION | 0 | 最终用户已拒绝下载。 | 1067|CANCEL_REASON_POSTPONED | 1 | 下载已推迟，稍后可以重新启动。 | 1068|CANCEL_REASON_TIMEOUT | 2 | 下载已超时，稍后可以重新启动。 | 1069|CANCEL_REASON_PPR_NOT_ALLOWED | 3 | 由于eUICC上的授权表或其他已安装的配置文件不允许其策略规则，因此无法安装。 | 1070 1071## ProfileState<sup>18+</sup> 1072 1073配置文件状态。 1074 1075**系统接口：** 此接口为系统接口。 1076 1077**系统能力**：SystemCapability.Telephony.CoreService.Esim 1078 1079| 名称 | 值 | 说明 | 1080| ----- | ----- | ----- | 1081|PROFILE_STATE_UNSPECIFIED | -1 | 未设置配置文件状态。 | 1082|PROFILE_STATE_DISABLED | 0 | 禁用配置文件。 | 1083|PROFILE_STATE_ENABLED | 1 | 已启用配置文件。 | 1084 1085## ProfileClass<sup>18+</sup> 1086 1087配置文件类。 1088 1089**系统接口：** 此接口为系统接口。 1090 1091**系统能力**：SystemCapability.Telephony.CoreService.Esim 1092 1093| 名称 | 值 | 说明 | 1094| ----- | ----- | ----- | 1095|PROFILE_CLASS_UNSPECIFIED | -1 | 未设置配置文件类。 | 1096|PROFILE_CLASS_TEST | 0 | 测试配置文件。 | 1097|PROFILE_CLASS_PROVISIONING | 1 | 预加载在eUICC上的配置文件。 | 1098|PROFILE_CLASS_OPERATIONAL | 2 | 可预加载或下载的操作配置文件。 | 1099 1100## PolicyRules<sup>18+</sup> 1101 1102配置文件的策略规则。 1103 1104**系统接口：** 此接口为系统接口。 1105 1106**系统能力**：SystemCapability.Telephony.CoreService.Esim 1107 1108| 名称 | 值 | 说明 | 1109| ----- | ----- | ----- | 1110|POLICY_RULE_DISABLE_NOT_ALLOWED | 1 | 启用此配置文件后，将无法禁用。 | 1111|POLICY_RULE_DELETE_NOT_ALLOWED | 1 << 1 | 无法删除此配置文件。 | 1112|POLICY_RULE_DISABLE_AND_DELETE | 1 << 2 | 禁用后应删除此配置文件。 | 1113 1114## SolvableErrors<sup>18+</sup> 1115 1116可解决错误码。 1117 1118**系统接口：** 此接口为系统接口。 1119 1120**系统能力**：SystemCapability.Telephony.CoreService.Esim 1121 1122| 名称 | 值 | 说明 | 1123| ----- | ----- | ----- | 1124|SOLVABLE_ERROR_NEED_CONFIRMATION_CODE | 1 << 0 | 下载过程需要用户输入确认码。 | 1125|SOLVABLE_ERROR_NEED_POLICY_RULE | 1 << 1 | 下载过程需要用户同意才能允许配置文件策略规则。| 1126 1127## DownloadConfiguration<sup>18+</sup> 1128 1129下载过程中的属性配置。 1130 1131**系统接口：** 此接口为系统接口。 1132 1133**系统能力**：SystemCapability.Telephony.CoreService.Esim 1134 1135| 名称 | 类型 | 必填 | 说明 | 1136| ----- | ----- | ----- | -----| 1137|switchAfterDownload | boolean | 是 | 下载成功后是否启用配置文件。true表示启用，false表示不启用。| 1138|forceDisableProfile | boolean | 是 | 是否可直接去激活配置文件。true表示切换配置文件时，如果需要去激活当前的配置文件，则可以直接操作。false表示如果需要去激活当前的配置文件，则会返回错误，并得到用户授权后再继续调用该接口，执行切换配置文件操作。| 1139|isPprAllowed | boolean | 是 | 是否得到用户授权。true表示得到用户授权，服务提供商可实施配置文件策略规则；false表示未得到用户授权，不允许实施配置文件策略规则。| 1140 1141