1# @ohos.telephony.esim (eSIM Management) (System API) 2 3The **esim** module provides APIs for eSIM management and eSIM services. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 18. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.telephony.esim (eSIM Management)](js-apis-esim.md). 9 10## Modules to Import 11 12```ts 13import { eSIM } from '@kit.TelephonyKit'; 14``` 15 16## eSIM.getEid<sup>18+</sup> 17 18getEid\(slotId: number\): Promise\<string\> 19 20Obtains the EID of the embedded universal integrated circuit card (eUICC) in the specified slot. 21 22**System API**: This is a system API. 23 24**Required permission**: ohos.permission.GET_TELEPHONY_ESIM_STATE 25 26**System capability**: SystemCapability.Telephony.CoreService.Esim 27 28**Parameters** 29 30| Name| Type | Mandatory| Description | 31| ------ | ------ | ---- | -------------------------------------- | 32| slotId | number | Yes | Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2 | 33 34**Returns** 35 36| Type | Description | 37| --------------------- | ---------------------------------- | 38| string | EID of the eUICC in the specified slot.| 39 40**Error codes** 41 42For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 43 44| ID | Error Message | 45| --------------------- | ---------------------------------- | 46| 201 | Permission denied. | 47| 202 | Non-system applications use system APIs. | 48| 401 | Invalid parameter value.| 49| 801 | Capability not supported. | 50|3120001| Service connection failed. | 51|3120002| System internal error. | 52 53**Example** 54 55```ts 56import { eSIM } from '@kit.TelephonyKit'; 57 58let eid: string = eSIM.getEid(0); 59console.log(`the EID is:` + eid); 60``` 61 62## eSIM.getOsuStatus<sup>18+</sup> 63 64getOsuStatus\(slotId: number\): Promise\<OsuStatus\> 65 66Obtains the OS upgrade status for the eSIM in the specified slot. This API uses a promise to return the result. 67 68**System API**: This is a system API. 69 70**Required permission**: ohos.permission.GET_TELEPHONY_ESIM_STATE 71 72**System capability**: SystemCapability.Telephony.CoreService.Esim 73 74**Parameters** 75 76| Name| Type | Mandatory| Description | 77| ------ | ------ | ---- | -------------------------------------- | 78| slotId | number | Yes | Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 79 80**Returns** 81 82| Type | Description | 83| --------------------- | ---------------------------------- | 84| Promise\<[OsuStatus](#osustatus18)\> | Promise used to return the OS upgrade status.<br> 1. Updating.<br> 2. Update failed.<br> 3. Update succeeded.<br> 4. Already the latest version.<br> 5. Update service unavailable.| 85 86**Error codes** 87 88For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 89 90| ID | Error Message | 91| --------------------- | ---------------------------------- | 92| 201 | Permission denied. | 93| 202 | Non-system applications use system APIs. | 94| 401 | Invalid parameter value.| 95| 801 | Capability not supported. | 96|3120001| Service connection failed. | 97|3120002| System internal error. | 98 99**Example** 100 101```ts 102import { BusinessError } from '@kit.BasicServicesKit'; 103import { eSIM } from '@kit.TelephonyKit'; 104 105eSIM.getOsuStatus(0).then(() => { 106 console.log(`getOsuStatus invoking succeeded.`); 107}).catch((err: BusinessError) => { 108 console.error(`getOsuStatus, promise: err->${JSON.stringify(err)}`); 109}); 110``` 111 112## eSIM.startOsu<sup>18+</sup> 113 114startOsu\(slotId: number\): Promise\<OsuStatus\> 115 116Upgrades the OS if the OS version of the eSIM in the specified slot is not the latest. This API uses a promise to return the result. 117 118**System API**: This is a system API. 119 120**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 121 122**System capability**: SystemCapability.Telephony.CoreService.Esim 123 124**Parameters** 125 126| Name| Type | Mandatory| Description | 127| ------ | ------ | ---- | -------------------------------------- | 128| slotId | number | Yes | Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 129 130**Returns** 131 132| Type | Description | 133| --------------------- | ---------------------------------- | 134| Promise\<[OsuStatus](#osustatus18)\> | Promise used to return the OS upgrade status.<br> 1. Updating.<br> 2. Update failed.<br> 3. Update succeeded.<br> 4. Already the latest version.<br> 5. Update service unavailable.| 135 136**Error codes** 137 138For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 139 140| ID | Error Message | 141| --------------------- | ---------------------------------- | 142| 201 | Permission denied. | 143| 202 | Non-system applications use system APIs. | 144| 401 | Invalid parameter value.| 145| 801 | Capability not supported. | 146|3120001| Service connection failed. | 147|3120002| System internal error. | 148 149**Example** 150 151```ts 152import { BusinessError } from '@kit.BasicServicesKit'; 153import { eSIM } from '@kit.TelephonyKit'; 154 155eSIM.startOsu(0).then(() => { 156 console.log(`startOsu invoking succeeded.`); 157}).catch((err: BusinessError) => { 158 console.error(`startOsu, ErrorState: err->${JSON.stringify(err)}`); 159}); 160``` 161 162## eSIM.getDownloadableProfileMetadata<sup>18+</sup> 163 164getDownloadableProfileMetadata\(slotId: number, portIndex: number, 165 profile: DownloadableProfile, forceDisableProfile: boolean\): Promise\<GetDownloadableProfileMetadataResult\> 166 167Obtains the metadata of the downloadable profile. This API uses a promise to return the result. 168 169**System API**: This is a system API. 170 171**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 172 173**System capability**: SystemCapability.Telephony.CoreService.Esim 174 175**Parameters** 176 177| Name| Type| Mandatory| Description| 178| ------ | ------ | ----- | ----- | 179| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 180| portIndex | number | Yes| Port index of the slot. | 181| profile | [DownloadableProfile](#downloadableprofile18) | Yes| Downloadable profile.| 182| forceDisableProfile | boolean | Yes| Whether to forcibly diable the active SIM. If the value is **true**, the operation can be performed only after the active SIM card is disabled. If the value is **false**, the system displays a message asking the user to agree to the operation.| 183 184**Returns** 185 186| Type | Description | 187| --------------------- | ---------------------------------- | 188| Promise\<[GetDownloadableProfileMetadataResult](#getdownloadableprofilemetadataresult18)\> | Promise used to return the metadata of the downloadable profile.| 189 190**Error codes** 191 192For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 193 194| ID | Error Message | 195| --------------------- | ---------------------------------- | 196| 201 | Permission denied. | 197| 202 | Non-system applications use system APIs. | 198| 401 | Invalid parameter value.| 199| 801 | Capability not supported. | 200|3120001| Service connection failed. | 201|3120002| System internal error. | 202 203**Example** 204 205```ts 206import { BusinessError } from '@kit.BasicServicesKit'; 207import { eSIM } from '@kit.TelephonyKit'; 208 209let profile: eSIM.DownloadableProfile={ 210 activationCode:'1', 211 confirmationCode:'1', 212 carrierName:'test', 213 accessRules:[{ 214 certificateHashHexStr:'test', 215 packageName:'com.example.testcoreservice', 216 accessType:0 217 }] 218}; 219 220eSIM.getDownloadableProfileMetadata(0, 0, profile, true).then((data: eSIM.GetDownloadableProfileMetadataResult) => { 221 console.log(`getDownloadableProfileMetadata, GetDownloadableProfileMetadataResult: data->${JSON.stringify(data)}`); 222}).catch((err: BusinessError) => { 223 console.error(`getDownloadableProfileMetadata, GetDownloadableProfileMetadataResult: err->${JSON.stringify(err)}`); 224}); 225``` 226 227## eSIM.getDownloadableProfiles<sup>18+</sup> 228 229getDownloadableProfiles\(slotId: number, portIndex: number, 230 forceDisableProfile: boolean\): Promise\<GetDownloadableProfilesResult\> 231 232Obtains the list of downloadable profiles. This API uses a promise to return the result. 233 234**System API**: This is a system API. 235 236**Required permission**: ohos.permission.GET_TELEPHONY_ESIM_STATE 237 238**System capability**: SystemCapability.Telephony.CoreService.Esim 239 240**Parameters** 241 242| Name| Type| Mandatory| Description| 243| ------ | ------ | ----- | ----- | 244| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 245| portIndex | number | Yes| Port index of the slot.| 246| forceDisableProfile | boolean | Yes| Whether to forcibly diable the active SIM. If the value is **true**, the operation can be performed only after the active SIM card is disabled. If the value is **false**, the system displays a message asking the user to agree to the operation.| 247 248**Returns** 249 250| Type | Description | 251| --------------------- | ---------------------------------- | 252| Promise\<[GetDownloadableProfilesResult](#getdownloadableprofilesresult18)\> | Promise used to return the list of downloadable profiles.| 253 254**Error codes** 255 256For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 257 258| ID | Error Message | 259| --------------------- | ---------------------------------- | 260| 201 | Permission denied. | 261| 202 | Non-system applications use system APIs. | 262| 401 | Invalid parameter value.| 263| 801 | Capability not supported. | 264|3120001| Service connection failed. | 265|3120002| System internal error. | 266 267**Example** 268 269```ts 270import { BusinessError } from '@kit.BasicServicesKit'; 271import { eSIM } from '@kit.TelephonyKit'; 272 273eSIM.getDownloadableProfiles(0, 0, true).then((data: eSIM.GetDownloadableProfilesResult) => { 274 console.log(`getDownloadableProfiles, GetDownloadableProfilesResult: data->${JSON.stringify(data)}`); 275}).catch((err: BusinessError) => { 276 console.error(`getDownloadableProfiles, GetDownloadableProfilesResult: err->${JSON.stringify(err)}`); 277}); 278``` 279 280## eSIM.downloadProfile<sup>18+</sup> 281 282downloadProfile\(slotId: number, portIndex: number, profile: DownloadableProfile, 283 configuration: DownloadConfiguration\): Promise\<DownloadProfileResult\> 284 285Downloads a profile. This API uses a promise to return the result. 286 287**System API**: This is a system API. 288 289**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 290 291**System capability**: SystemCapability.Telephony.CoreService.Esim 292 293**Parameters** 294 295| Name| Type| Mandatory| Description| 296| ------ | ------ | ----- | ----- | 297| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 298| portIndex | number | Yes| Port index of the slot.| 299| profile | [DownloadableProfile](#downloadableprofile18) | Yes| Downloadable profile.| 300| configuration | [DownloadConfiguration](#downloadconfiguration18) | Yes| Download configuration.| 301 302**Returns** 303 304| Type | Description | 305| --------------------- | ---------------------------------- | 306| Promise\<[DownloadProfileResult](#downloadprofileresult18)\> | Promise used to return the profile download result.| 307 308**Error codes** 309 310For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 311 312| ID | Error Message | 313| --------------------- | ---------------------------------- | 314| 201 | Permission denied. | 315| 202 | Non-system applications use system APIs. | 316| 401 | Invalid parameter value.| 317| 801 | Capability not supported. | 318|3120001| Service connection failed. | 319|3120002| System internal error. | 320 321**Example** 322 323```ts 324import { BusinessError } from '@kit.BasicServicesKit'; 325import { eSIM } from '@kit.TelephonyKit'; 326 327let profile: eSIM.DownloadableProfile={ 328 activationCode:'1', 329 confirmationCode:'1', 330 carrierName:'test', 331 accessRules:[{ 332 certificateHashHexStr:'test', 333 packageName:'com.example.testcoreservice', 334 accessType:0 335 }] 336}; 337 338let configuration: eSIM.DownloadConfiguration = { 339 switchAfterDownload: true, 340 forceDisableProfile: true, 341 isAlowPpr: true, 342}; 343 344eSIM.downloadProfile(0, 0, profile, configuration).then((data: eSIM.DownloadProfileResult) => { 345 console.log(`downloadProfile, DownloadProfileResult: data->${JSON.stringify(data)}`); 346}).catch((err: BusinessError) => { 347 console.error(`downloadProfile, DownloadProfileResult: err->${JSON.stringify(err)}`); 348}); 349``` 350 351## eSIM.getEuiccProfileInfoList<sup>18+</sup> 352 353getEuiccProfileInfoList\(slotId: number\): Promise\<GetEuiccProfileInfoListResult\> 354 355Obtains the profile information list. This API uses a promise to return the result. 356 357**System API**: This is a system API. 358 359**Required permission**: ohos.permission.GET_TELEPHONY_ESIM_STATE 360 361**System capability**: SystemCapability.Telephony.CoreService.Esim 362 363**Parameters** 364 365| Name| Type| Mandatory| Description| 366| ------ | ------ | ----- | ----- | 367| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 368 369**Returns** 370 371| Type | Description | 372| --------------------- | ---------------------------------- | 373| Promise\<[GetEuiccProfileInfoListResult](#geteuiccprofileinfolistresult18)\> | Promise used to return the profile information list.| 374 375**Error codes** 376 377For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 378 379| ID | Error Message | 380| --------------------- | ---------------------------------- | 381| 201 | Permission denied. | 382| 202 | Non-system applications use system APIs. | 383| 401 | Invalid parameter value.| 384| 801 | Capability not supported. | 385|3120001| Service connection failed. | 386|3120002| System internal error. | 387 388**Example** 389 390```ts 391import { BusinessError } from '@kit.BasicServicesKit'; 392import { eSIM } from '@kit.TelephonyKit'; 393 394eSIM.getEuiccProfileInfoList(0).then((data: eSIM.GetEuiccProfileInfoListResult) => { 395 console.log(`getEuiccProfileInfoList, GetEuiccProfileInfoListResult: data->${JSON.stringify(data)}`); 396}).catch((err: BusinessError) => { 397 console.error(`getEuiccProfileInfoList, GetEuiccProfileInfoListResult: err->${JSON.stringify(err)}`); 398}); 399``` 400 401## eSIM.getEuiccInfo<sup>18+</sup> 402 403getEuiccInfo\(slotId: number\): Promise\<EuiccInfo\> 404 405Obtains eUICC information. This API uses a promise to return the result. 406 407**System API**: This is a system API. 408 409**Required permission**: ohos.permission.GET_TELEPHONY_ESIM_STATE 410 411**System capability**: SystemCapability.Telephony.CoreService.Esim 412 413**Parameters** 414 415| Name| Type| Mandatory| Description| 416| ------ | ------ | ----- | ----- | 417| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 418 419**Returns** 420 421| Type | Description | 422| --------------------- | ---------------------------------- | 423| Promise\<[EuiccInfo](#euiccinfo18)\> | Promise used to return the eUICC information.| 424 425**Error codes** 426 427For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 428 429| ID | Error Message | 430| --------------------- | ---------------------------------- | 431| 201 | Permission denied. | 432| 202 | Non-system applications use system APIs. | 433| 401 | Invalid parameter value.| 434| 801 | Capability not supported. | 435|3120001| Service connection failed. | 436|3120002| System internal error. | 437 438**Example** 439 440```ts 441import { BusinessError } from '@kit.BasicServicesKit'; 442import { eSIM } from '@kit.TelephonyKit'; 443 444eSIM.getEuiccInfo(0).then((data: eSIM.EuiccInfo) => { 445 console.log(`getEuiccInfo, EuiccInfo: data->${JSON.stringify(data)}`); 446}).catch((err: BusinessError) => { 447 console.error(`getEuiccInfo, EuiccInfo: err->${JSON.stringify(err)}`); 448}); 449``` 450 451## eSIM.deleteProfile<sup>18+</sup> 452 453deleteProfile\(slotId: number, iccid: string\): Promise\<ResultCode\> 454 455Deletes a profile. This API uses a promise to return the result. 456 457**System API**: This is a system API. 458 459**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 460 461**System capability**: SystemCapability.Telephony.CoreService.Esim 462 463**Parameters** 464 465| Name| Type| Mandatory| Description| 466| ------ | ------ | ----- | ----- | 467| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 468| iccid | string | Yes| Profile ID.| 469 470**Returns** 471 472| Type | Description | 473| --------------------- | ---------------------------------- | 474| Promise\<[ResultCode](#resultcode18)\> | Promise used to return the operation result.| 475 476**Error codes** 477 478For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 479 480| ID | Error Message | 481| --------------------- | ---------------------------------- | 482| 201 | Permission denied. | 483| 202 | Non-system applications use system APIs. | 484| 401 | Invalid parameter value.| 485| 801 | Capability not supported. | 486|3120001| Service connection failed. | 487|3120002| System internal error. | 488 489**Example** 490 491```ts 492import { BusinessError } from '@kit.BasicServicesKit'; 493import { eSIM } from '@kit.TelephonyKit'; 494 495eSIM.deleteProfile(0, testId).then(() => { 496 console.log(`deleteProfile invoking succeeded.`); 497}).catch((err: BusinessError) => { 498 console.error(`deleteProfile, ErrorState: err->${JSON.stringify(err)}`); 499}); 500``` 501 502## eSIM.switchToProfile<sup>18+</sup> 503 504switchToProfile\(slotId: number, portIndex: number, iccid: string, 505 forceDisableProfile: boolean\): Promise\<ResultCode\> 506 507Switches to the specified profile. This API uses a promise to return the result. 508 509**System API**: This is a system API. 510 511**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 512 513**System capability**: SystemCapability.Telephony.CoreService.Esim 514 515**Parameters** 516 517| Name| Type| Mandatory| Description| 518| ------ | ------ | ----- | ----- | 519| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 520| portIndex | number | Yes| Port index of the slot.| 521| iccid | string | Yes| Profile ID. | 522| forceDisableProfile | boolean | Yes| Whether to forcibly diable the active SIM. If the value is **true**, the operation can be performed only after the active SIM card is disabled. If the value is **false**, the system displays a message asking the user to agree to the operation.| 523 524**Returns** 525 526| Type | Description | 527| --------------------- | ---------------------------------- | 528| Promise\<[ResultCode](#resultcode18)\> | Promise used to return the operation result.| 529 530**Error codes** 531 532For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 533 534| ID | Error Message | 535| --------------------- | ---------------------------------- | 536| 201 | Permission denied. | 537| 202 | Non-system applications use system APIs. | 538| 401 | Invalid parameter value.| 539| 801 | Capability not supported. | 540|3120001| Service connection failed. | 541|3120002| System internal error. | 542 543**Example** 544 545```ts 546import { BusinessError } from '@kit.BasicServicesKit'; 547import { eSIM } from '@kit.TelephonyKit'; 548 549eSIM.switchToProfile(0, 0, testId, true).then(() => { 550 console.log(`switchToProfile invoking succeeded.`); 551}).catch((err: BusinessError) => { 552 console.error(`switchToProfile, ErrorState: err->${JSON.stringify(err)}`); 553}); 554``` 555 556## eSIM.setProfileNickname<sup>18+</sup> 557 558setProfileNickname\(slotId: number, iccid: string, nickname: string\): Promise\<ResultCode\> 559 560Sets a nickname for the specified profile. This API uses a promise to return the result. 561 562**System API**: This is a system API. 563 564**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 565 566**System capability**: SystemCapability.Telephony.CoreService.Esim 567 568**Parameters** 569 570| Name| Type| Mandatory| Description| 571| ------ | ------ | ----- | ----- | 572| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 573| iccid | string | Yes| Profile ID.| 574| nickname | string | Yes| Profile nickname.| 575 576**Returns** 577 578| Type | Description | 579| --------------------- | ---------------------------------- | 580| Promise\<[ResultCode](#resultcode18)\> | Promise used to return the operation result.| 581 582**Error codes** 583 584For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 585 586| ID | Error Message | 587| --------------------- | ---------------------------------- | 588| 201 | Permission denied. | 589| 202 | Non-system applications use system APIs. | 590| 401 | Invalid parameter value.| 591| 801 | Capability not supported. | 592|3120001| Service connection failed. | 593|3120002| System internal error. | 594 595**Example** 596 597```ts 598import { BusinessError } from '@kit.BasicServicesKit'; 599import { eSIM } from '@kit.TelephonyKit'; 600 601eSIM.setProfileNickname(0, testId, testName).then(() => { 602 console.log(`setProfileNickname invoking succeeded.`); 603}).catch((err: BusinessError) => { 604 console.error(`setProfileNickname, ErrorState: err->${JSON.stringify(err)}`); 605}); 606``` 607 608## eSIM.resetMemory<sup>18+</sup> 609 610resetMemory\(slotId: number, options?: ResetOption\): Promise\<ResultCode\> 611 612Clears all specific profiles and resets the eUICC. This API uses a promise to return the result. 613 614**System API**: This is a system API. 615 616**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 617 618**System capability**: SystemCapability.Telephony.CoreService.Esim 619 620**Parameters** 621 622| Name| Type| Mandatory| Description| 623| ------ | ------ | ----- | ----- | 624| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 625| options | [ResetOption](#resetoption18) | No| Reset options.| 626 627**Returns** 628 629| Type | Description | 630| --------------------- | ---------------------------------- | 631| Promise\<[ResultCode](#resultcode18)\> | Promise used to return the operation result.| 632 633**Error codes** 634 635For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 636 637| ID | Error Message | 638| --------------------- | ---------------------------------- | 639| 201 | Permission denied. | 640| 202 | Non-system applications use system APIs. | 641| 401 | Invalid parameter value.| 642| 801 | Capability not supported. | 643|3120001| Service connection failed. | 644|3120002| System internal error. | 645 646**Example** 647 648```ts 649import { BusinessError } from '@kit.BasicServicesKit'; 650import { eSIM } from '@kit.TelephonyKit'; 651 652eSIM.resetMemory(0).then(() => { 653 console.log(`resetMemory invoking succeeded.`); 654}).catch((err: BusinessError) => { 655 console.error(`resetMemory, ErrorState: err->${JSON.stringify(err)}`); 656}); 657``` 658 659## eSIM.reserveProfilesForFactoryRestore<sup>18+</sup> 660 661reserveProfilesForFactoryRestore\(slotId: number\): Promise\<ResultCode\> 662 663Restores factory settings and retains profiles. This API uses a promise to return the result. 664 665**System API**: This is a system API. 666 667**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 668 669**System capability**: SystemCapability.Telephony.CoreService.Esim 670 671**Parameters** 672 673| Name| Type| Mandatory| Description| 674| ------ | ------ | ----- | ----- | 675| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 676 677**Returns** 678 679| Type | Description | 680| --------------------- | ---------------------------------- | 681| Promise\<[ResultCode](#resultcode18)\> | Promise used to return the operation result.| 682 683**Error codes** 684 685For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 686 687| ID | Error Message | 688| --------------------- | ---------------------------------- | 689| 201 | Permission denied. | 690| 202 | Non-system applications use system APIs. | 691| 401 | Invalid parameter value.| 692| 801 | Capability not supported. | 693|3120001| Service connection failed. | 694|3120002| System internal error. | 695 696**Example** 697 698```ts 699import { BusinessError } from '@kit.BasicServicesKit'; 700import { eSIM } from '@kit.TelephonyKit'; 701 702eSIM.reserveProfilesForFactoryRestore(0).then(() => { 703 console.log(`reserveProfilesForFactoryRestore invoking succeeded.`); 704}).catch((err: BusinessError) => { 705 console.error(`reserveProfilesForFactoryRestore, ErrorState: err->${JSON.stringify(err)}`); 706}); 707``` 708 709## eSIM.setDefaultSmdpAddress<sup>18+</sup> 710 711setDefaultSmdpAddress\(slotId: number, address: string\): Promise\<ResultCode\> 712 713Sets or updates the default SM-DP+ address stored in the eUICC. This API uses a promise to return the result. 714 715**System API**: This is a system API. 716 717**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 718 719**System capability**: SystemCapability.Telephony.CoreService.Esim 720 721**Parameters** 722 723| Name| Type| Mandatory| Description| 724| ------ | ------ | ----- | ----- | 725| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 726| address | string | Yes| Default SM-DP+ address.| 727 728**Returns** 729 730| Type | Description | 731| --------------------- | ---------------------------------- | 732| Promise\<[ResultCode](#resultcode18)\> | Promise used to return the operation result.| 733 734**Error codes** 735 736For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 737 738| ID | Error Message | 739| --------------------- | ---------------------------------- | 740| 201 | Permission denied. | 741| 202 | Non-system applications use system APIs. | 742| 401 | Invalid parameter value.| 743| 801 | Capability not supported. | 744|3120001| Service connection failed. | 745|3120002| System internal error. | 746 747**Example** 748 749```ts 750import { BusinessError } from '@kit.BasicServicesKit'; 751import { eSIM } from '@kit.TelephonyKit'; 752 753eSIM.setDefaultSmdpAddress(0, testAddress).then(() => { 754 console.log(`setDefaultSmdpAddress invoking succeeded.`); 755}).catch((err: BusinessError) => { 756 console.error(`setDefaultSmdpAddress, ErrorState: err->${JSON.stringify(err)}`); 757}); 758``` 759 760## eSIM.getDefaultSmdpAddress<sup>18+</sup> 761 762getDefaultSmdpAddress\(slotId: number\): Promise\<string\> 763 764Obtains the default SM-DP+ address stored in the eUICC. This API uses a promise to return the result. 765 766**System API**: This is a system API. 767 768**Required permission**: ohos.permission.GET_TELEPHONY_ESIM_STATE 769 770**System capability**: SystemCapability.Telephony.CoreService.Esim 771 772**Parameters** 773 774| Name| Type| Mandatory| Description| 775| ------ | ------ | ----- | ----- | 776| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 777 778**Returns** 779 780| Type | Description | 781| --------------------- | ---------------------------------- | 782| Promise\<string\> | Promise used to return the SM-DP+ address.| 783 784**Error codes** 785 786For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 787 788| ID | Error Message | 789| --------------------- | ---------------------------------- | 790| 201 | Permission denied. | 791| 202 | Non-system applications use system APIs. | 792| 401 | Invalid parameter value.| 793| 801 | Capability not supported. | 794|3120001| Service connection failed. | 795|3120002| System internal error. | 796 797**Example** 798 799```ts 800import { BusinessError } from '@kit.BasicServicesKit'; 801import { eSIM } from '@kit.TelephonyKit'; 802 803eSIM.getDefaultSmdpAddress(0).then((data: string) => { 804 console.log(`getDefaultSmdpAddress, result: data->${JSON.stringify(data)}`); 805}).catch((err: BusinessError) => { 806 console.error(`getDefaultSmdpAddress, ErrorState: err->${JSON.stringify(err)}`); 807}); 808``` 809 810## eSIM.cancelSession<sup>18+</sup> 811 812cancelSession\(slotId: number, transactionId: string, cancelReason: CancelReason\): Promise\<ResultCode\> 813 814Cancels a session. This API uses a promise to return the result. 815 816**System API**: This is a system API. 817 818**Required permission**: ohos.permission.SET_TELEPHONY_ESIM_STATE 819 820**System capability**: SystemCapability.Telephony.CoreService.Esim 821 822**Parameters** 823 824| Name| Type| Mandatory| Description| 825| ------ | ------ | ----- | ----- | 826| slotId | number | Yes| Card slot ID.<br>- **0**: card slot 1.<br>- **1**: card slot 2| 827| transactionId | string | Yes| Service ID.| 828| cancelReason | [CancelReason](#cancelreason18) | Yes| Reason for canceling the session.| 829 830**Returns** 831 832| Type | Description | 833| --------------------- | ---------------------------------- | 834| Promise\<[ResultCode](#resultcode18)\> | Promise used to return the operation result.| 835 836**Error codes** 837 838For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 839 840| ID | Error Message | 841| --------------------- | ---------------------------------- | 842| 201 | Permission denied. | 843| 202 | Non-system applications use system APIs. | 844| 401 | Invalid parameter value.| 845| 801 | Capability not supported. | 846|3120001| Service connection failed. | 847|3120002| System internal error. | 848 849**Example** 850 851```ts 852import { BusinessError } from '@kit.BasicServicesKit'; 853import { eSIM } from '@kit.TelephonyKit'; 854 855eSIM.cancelSession(0, testId, CancelReason::CANCEL_REASON_END_USER_REJECTION).then((data: string) => { 856 console.log(`cancelSession, result: data->${JSON.stringify(data)}`); 857}).catch((err: BusinessError) => { 858 console.error(`cancelSession execution failed: err->${JSON.stringify(err)}`); 859}); 860``` 861 862## AccessRule<sup>18+</sup> 863 864Defines access rules. 865 866**System API**: This is a system API. 867 868**System capability**: SystemCapability.Telephony.CoreService.Esim 869 870| Name| Type| Mandatory| Description| 871| ----- | ----- | ----- | -----| 872| certificateHashHexStr | string | Yes | Hex string of the certificate hash.| 873| packageName | string | Yes | Package name.| 874| accessType | number | Yes | Rule type.| 875 876## DownloadableProfile<sup>18+</sup> 877 878Defines a downloadable profile. 879 880**System API**: This is a system API. 881 882**System capability**: SystemCapability.Telephony.CoreService.Esim 883 884| Name| Type| Mandatory| Description| 885| ----- | ----- | ----- | -----| 886| activationCode | string | Yes | Activation code. For a profile that does not require an activation code, the value may be left empty.| 887| confirmationCode | string | No | Confirmation code. | 888| carrierName | string | No | Carrier name. | 889| accessRules | Array\<AccessRule> | No | Access rule array.| 890 891## GetDownloadableProfileMetadataResult<sup>18+</sup> 892 893Obtains the metadata of the downloadable profile. 894 895**System API**: This is a system API. 896 897**System capability**: SystemCapability.Telephony.CoreService.Esim 898 899| Name| Type| Mandatory| Description| 900| ----- | ----- | ----- | -----| 901| downloadableProfile | DownloadableProfile | Yes | Downloadable profile. | 902| pprType | number | Yes | Profile policy rule type.| 903| pprFlag | boolean | Yes | Profile policy rule flag.| 904| iccid | string | Yes | Profile ICCID. | 905| serviceProviderName | string | Yes | Service provider name.| 906| profileName | string | Yes | Profile name.| 907| profileClass | ProfileClass | Yes | Profile class. | 908| solvableErrors | SolvableErrors | Yes | Solvable errors.| 909| responseResult | ResultCode | Yes | Operation result code. | 910 911## GetDownloadableProfilesResult<sup>18+</sup> 912 913Obtains the list of default downloadable profiles. 914 915**System API**: This is a system API. 916 917**System capability**: SystemCapability.Telephony.CoreService.Esim 918 919| Name| Type| Mandatory| Description| 920| ----- | ----- | ----- | -----| 921| responseResult | ResultCode | Yes | Promise used to return the operation result. | 922| downloadableProfiles | Array\<DownloadableProfile> | Yes | Downloadable file array.| 923 924## DownloadProfileResult<sup>18+</sup> 925 926Defines the profile download result. 927 928**System API**: This is a system API. 929 930**System capability**: SystemCapability.Telephony.CoreService.Esim 931 932| Name| Type| Mandatory| Description| 933| ----- | ----- | ----- | -----| 934| responseResult | ResultCode | Yes | Operation result code.| 935| solvableErrors | SolvableErrors | Yes | Solvable errors.| 936| cardId | number | Yes | Card ID. | 937 938## GetEuiccProfileInfoListResult<sup>18+</sup> 939 940Obtains the profile information list. 941 942**System API**: This is a system API. 943 944**System capability**: SystemCapability.Telephony.CoreService.Esim 945 946| Name| Type| Mandatory| Description| 947| ----- | ----- | ----- | -----| 948| responseResult |ResultCode | Yes | Promise used to return the operation result. | 949| profiles | Array\<EuiccProfile> | Yes | Profile array. | 950| isRemovable | boolean | Yes | Checks whether the eUICC is removable.| 951 952## OperatorId<sup>18+</sup> 953 954Obtains information about the eUICC chip or device. 955 956**System API**: This is a system API. 957 958**System capability**: SystemCapability.Telephony.CoreService.Esim 959 960| Name| Type| Mandatory| Description| 961| ----- | ----- | ----- | -----| 962| mcc | string | Yes | Mobile country code (MCC).| 963| mnc | string | Yes | Network code. | 964| gid1 | string | Yes | Group ID level 1. | 965| gid2 | string | Yes | Group ID level 2. | 966 967## EuiccProfile<sup>18+</sup> 968 969Profile information. 970 971**System API**: This is a system API. 972 973**System capability**: SystemCapability.Telephony.CoreService.Esim 974 975| Name| Type| Mandatory| Description| 976| ----- | ----- | ----- | -----| 977| iccid | string | Yes | Profile ICCID.| 978| nickName | string | Yes | Profile nickname.| 979| serviceProviderName | string | Yes | Service provider name.| 980| profileName | string | Yes | Profile name. | 981| state | ProfileState | Yes | Profile status.| 982| profileClass | ProfileClass | Yes | Profile class. | 983| operatorId | OperatorId | Yes | Operation ID of the profile.| 984| policyRules | PolicyRules | Yes | Profile policy rules. | 985| accessRules | Array\<AccessRule> | Yes | Profile access rules. | 986 987## EuiccInfo<sup>18+</sup> 988 989Defines the eUICC information. 990 991**System API**: This is a system API. 992 993**System capability**: SystemCapability.Telephony.CoreService.Esim 994 995| Name| Type| Mandatory| Description| 996| ----- | ----- | ----- | -----| 997| osVersion | string | Yes | OS version.| 998 999## ResetOption<sup>18+</sup> 1000 1001Defines the reset options. 1002 1003**System API**: This is a system API. 1004 1005**System capability**: SystemCapability.Telephony.CoreService.Esim 1006 1007| Name| Value| Description| 1008| ----- | ----- | ----- | 1009|DELETE_OPERATIONAL_PROFILES | 1 | Deletion of all operational profiles.| 1010|DELETE_FIELD_LOADED_TEST_PROFILES | 1 << 1 | Deletion of the downloaded test profiles.| 1011|RESET_DEFAULT_SMDP_ADDRESS | 1 << 2 | Resetting of the default SM-DP+ address.| 1012 1013## OsuStatus<sup>18+</sup> 1014 1015Defines the OS upgrade status. 1016 1017**System API**: This is a system API. 1018 1019**System capability**: SystemCapability.Telephony.CoreService.Esim 1020 1021| Name| Value| Description| 1022| ----- | ----- | ----- | 1023|EUICC_UPGRADE_IN_PROGRESS | 1 | Upgrading.| 1024|EUICC_UPGRADE_FAILED | 2 | Upgrade failed.| 1025|EUICC_UPGRADE_SUCCESSFUL | 3 | Update succeeded.| 1026|EUICC_UPGRADE_ALREADY_LATEST | 4 | Already the latest version.| 1027|EUICC_UPGRADE_SERVICE_UNAVAILABLE | 5 | Update service unavailable.| 1028 1029## ResultCode<sup>18+</sup> 1030 1031Enumerates the result codes. 1032 1033**System API**: This is a system API. 1034 1035**System capability**: SystemCapability.Telephony.CoreService.Esim 1036 1037| Name| Value| Description| 1038| ----- | ----- | ----- | 1039| RESULT_SOLVABLE_ERRORS | -2 | Solving of the solvable errors required. | 1040| RESULT_MUST_DISABLE_PROFILE | -1 | Disabling of the active profile required.| 1041| RESULT_OK | 0 | Operation success.| 1042| RESULT_GET_EID_FAILED | 201 | Failed to obtain the EID.| 1043| RESULT_ACTIVATION_CODE_CHANGED | 203 | Activation code changed upon user confirmation. | 1044| RESULT_ACTIVATION_CODE_INVALID | 204 | Invalid activation code. | 1045| RESULT_SMDP_ADDRESS_INVALID | 205 | Invalid SM-DP+ server address.| 1046| RESULT_EUICC_INFO_INVALID | 206 | Invalid eUICC information. | 1047| RESULT_TLS_HANDSHAKE_FAILED | 207 | TLS handshake failed. | 1048| RESULT_CERTIFICATE_IO_ERROR | 208 | Certificate network connection error. | 1049| RESULT_CERTIFICATE_RESPONSE_TIMEOUT | 209 | Invalid certificate address or response timeout.| 1050| RESULT_AUTHENTICATION_FAILED | 210 | Authentication failed. | 1051| RESULT_RESPONSE_HTTP_FAILED | 211 | HTTP response failed.| 1052| RESULT_CONFIRMATION_CODE_INCORRECT | 212 | Incorrect confirmation code.| 1053| RESULT_EXCEEDED_CONFIRMATION_CODE_TRY_LIMIT | 213 | Maximum confirmation code retries reached. | 1054| RESULT_NO_PROFILE_ON_SERVER | 214 | No downloadable profile available on the server.| 1055| RESULT_TRANSACTION_ID_INVALID | 215 | Invalid transaction ID. | 1056| RESULT_SERVER_ADDRESS_INVALID | 216 | Invalid server address.| 1057| RESULT_GET_BOUND_PROFILE_PACKAGE_FAILED | 217 | Failed to obtain the BPP. | 1058| RESULT_USER_CANCEL_DOWNLOAD | 218 | Download cancelled by the user. | 1059| RESULT_SERVER_UNAVAILABLE | 220 | Carrier server unavailable.| 1060| RESULT_PROFILE_NON_DELETE | 223 | File deletion not allowed by the PPR rule. | 1061| RESULT_SMDP_ADDRESS_INCORRECT | 226 | Incorrect SMDP server address. | 1062| RESULT_ANALYZE_AUTHENTICATION_SERVER_RESPONSE_FAILED | 228 | Failed to parse the server authentication response.| 1063| RESULT_ANALYZE_AUTHENTICATION_CLIENT_RESPONSE_FAILED | 229 | Failed to parse the client authentication response.| 1064| RESULT_ANALYZE_AUTHENTICATION_CLIENT_MATCHING_ID_REFUSED | 231 | Failed to parse the client authentication response because the matching ID was rejected.| 1065| RESULT_PROFILE_TYPE_ERROR_AUTHENTICATION_STOPPED | 233 | Authentication stopped due to incorrect profile type. | 1066| RESULT_CARRIER_SERVER_REFUSED_ERRORS | 249 | Rejection cause code of the carrier server, which is 3.8.| 1067| RESULT_CERTIFICATE_INVALID | 251 | Invalid certificate.| 1068| RESULT_OUT_OF_MEMORY | 263 | Failed to install the profile due to insufficient memory.| 1069| RESULT_PPR_FORBIDDEN | 268 | Operation not allowed by the PPR rule.| 1070| RESULT_NOTHING_TO_DELETE | 270 | No configuration file for deletion.| 1071| RESULT_PPR_NOT_MATCH | 276 | PPR rule mismatch. | 1072| RESULT_CAT_BUSY | 283 | Session in progress. | 1073| RESULT_PROFILE_EID_INVALID | 284 | eSIM profile in use or invalid.| 1074| RESULT_DOWNLOAD_TIMEOUT | 287 | Download timeout. | 1075| RESULT_SGP_22_OTHER | 400 | Other errors defined in SGP.22. | 1076 1077## CancelReason<sup>18+</sup> 1078 1079Reason for canceling the session. 1080 1081**System API**: This is a system API. 1082 1083**System capability**: SystemCapability.Telephony.CoreService.Esim 1084 1085| Name| Value| Description| 1086| ----- | ----- | ----- | 1087|CANCEL_REASON_END_USER_REJECTION | 0 | The user has rejected the download. | 1088|CANCEL_REASON_POSTPONED | 1 | The download has been delayed. You can restart it later.| 1089|CANCEL_REASON_TIMEOUT | 2 | The download has timed out. You can restart it later.| 1090|CANCEL_REASON_PPR_NOT_ALLOWED | 3 | The installation cannot be performed because the authorization table or other installed profile on the eUICC does not allow its policy rules.| 1091 1092## ProfileState<sup>18+</sup> 1093 1094Enumerates the profile states. 1095 1096**System API**: This is a system API. 1097 1098**System capability**: SystemCapability.Telephony.CoreService.Esim 1099 1100| Name| Value| Description| 1101| ----- | ----- | ----- | 1102|PROFILE_STATE_UNSPECIFIED | -1 | Profile status unspecified.| 1103|PROFILE_STATE_DISABLED | 0 | Profile disabled. | 1104|PROFILE_STATE_ENABLED | 1 | Profile enabled.| 1105 1106## ProfileClass<sup>18+</sup> 1107 1108Enumerates the profile classes. 1109 1110**System API**: This is a system API. 1111 1112**System capability**: SystemCapability.Telephony.CoreService.Esim 1113 1114| Name| Value| Description| 1115| ----- | ----- | ----- | 1116|PROFILE_CLASS_UNSPECIFIED | -1 | Profile class unspecified. | 1117|PROFILE_CLASS_TEST | 0 | Test profile. | 1118|PROFILE_CLASS_PROVISIONING | 1 | Profile preloaded to the eUICC. | 1119|PROFILE_CLASS_OPERATIONAL | 2 | Profile that can be preloaded or downloaded.| 1120 1121## PolicyRules<sup>18+</sup> 1122 1123Enumerates the profile policy rules. 1124 1125**System API**: This is a system API. 1126 1127**System capability**: SystemCapability.Telephony.CoreService.Esim 1128 1129| Name| Value| Description| 1130| ----- | ----- | ----- | 1131|POLICY_RULE_DISABLE_NOT_ALLOWED | 1 | A profile cannot be disabled after being enabled.| 1132|POLICY_RULE_DELETE_NOT_ALLOWED | 1 << 1 | The profile cannot be deleted. | 1133|POLICY_RULE_DISABLE_AND_DELETE | 1 << 2 | A profile must be deleted immediately after being enabled. | 1134 1135## SolvableErrors<sup>18+</sup> 1136 1137Enumerates the solvable errors. 1138 1139**System API**: This is a system API. 1140 1141**System capability**: SystemCapability.Telephony.CoreService.Esim 1142 1143| Name| Value| Description| 1144| ----- | ----- | ----- | 1145|SOLVABLE_ERROR_NEED_CONFIRMATION_CODE | 1 << 0 | The user needs to enter the confirmation code during the download. | 1146|SOLVABLE_ERROR_NEED_POLICY_RULE | 1 << 1 | The download process requires user consent to allow the profile policy rules.| 1147 1148## DownloadConfiguration<sup>18+</sup> 1149 1150Defines the download configuration. 1151 1152**System API**: This is a system API. 1153 1154**System capability**: SystemCapability.Telephony.CoreService.Esim 1155 1156| Name| Type| Mandatory| Description| 1157| ----- | ----- | ----- | -----| 1158|switchAfterDownload | boolean | Yes| Whether to enable the profile after being downloaded.| 1159|forceDisableProfile | boolean | Yes| Whether to forcibly disable a profile. | 1160|isPprAllowed | boolean | Yes| Whether to allow the service provider to enforce the profile policy rule after the user is informed of its restrictions.| 1161