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