1# @ohos.multimedia.drm (Digital Rights Management) 2 3The Digital Rights Management (DRM) framework provides APIs for you to develop digital rights management for your audio and video applications. You can call the DRM solutions (which exist as DRM plugins) provided by the system to implement the following features: 4 5* DRM certificate management: generates provision requests and processes responses to these requests. Such a request/response exchange occurs between an application and a provisioning server to retrieve a DRM certificate. 6* DRM media key management: generates media key requests, processes responses to these requests, and manages offline media keys. Such a request/response exchange occurs between an application and a license server to obtain or release a media key, which is used to decrypt DRM-protected content. 7* DRM authorization: authorizes access to DRM-protected content based on media keys. 8* DRM decryption: decrypts DRM-protected content. 9 10> **NOTE** 11> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 12 13## Modules to Import 14 15```ts 16import { drm } from '@kit.DrmKit'; 17``` 18 19## DrmErrorCode 20 21Enumerates the DRM error codes. 22 23**Atomic service API**: This API can be used in atomic services since API version 14. 24 25**System capability**: SystemCapability.Multimedia.Drm.Core 26 27| Name | Value | Description | 28| ------------------------- | ---- | ------------ | 29| ERROR_UNKNOWN | 24700101 | Unknown error. | 30| MAX_SYSTEM_NUM_REACHED | 24700103 | The number of **MediaKeySystem** instances reaches the upper limit (64). | 31| MAX_SESSION_NUM_REACHED | 24700104 | The number of **MediaKeySession** instances reaches the upper limit (64). | 32| SERVICE_FATAL_ERROR | 24700201 | DRM service error. | 33 34## PreDefinedConfigName 35 36Enumerates the names of predefined configuration items. 37 38**Atomic service API**: This API can be used in atomic services since API version 14. 39 40**System capability**: SystemCapability.Multimedia.Drm.Core 41 42| Name | Value | Description | 43| ------------------------- | ---- | ------------ | 44| CONFIG_DEVICE_VENDOR | 'vendor' | Plugin vendor name, which corresponds to the value of **vendor** in the return value of [getConfigurationString](#getconfigurationstring). | 45| CONFIG_DEVICE_VERSION | 'version' | Plugin version number, which corresponds to the value of **version** in the return value of [getConfigurationString](#getconfigurationstring). | 46| CONFIG_DEVICE_DESCRIPTION | 'description' | Device descriptor, which corresponds to the value of **description** in the return value of [getConfigurationString](#getconfigurationstring). | 47| CONFIG_DEVICE_ALGORITHMS | 'algorithms' | Supported algorithm names, which correspond to the value of **algorithms** in the return value of [getConfigurationString](#getconfigurationstring). | 48| CONFIG_DEVICE_UNIQUE_ID | 'deviceUniqueId' | Unique device ID, which corresponds to the value of **deviceUniqueId** in the return value of [getConfigurationByteArray](#getconfigurationbytearray). | 49| CONFIG_SESSION_MAX | 'maxSessionNum' | Maximum number of sessions supported by the device, which corresponds to the value of **maxSessionNum** in the return value of [getConfigurationString](#getconfigurationstring). | 50| CONFIG_SESSION_CURRENT | 'currentSessionNum' | Number of existing sessions, which corresponds to the value of **currentSessionNum** in the return value of [getConfigurationString](#getconfigurationstring). | 51 52## MediaKeyType 53 54Enumerates the types of media keys. 55 56**Atomic service API**: This API can be used in atomic services since API version 14. 57 58**System capability**: SystemCapability.Multimedia.Drm.Core 59 60| Name | Value | Description | 61| ------------------------- | ---- | ------------ | 62| MEDIA_KEY_TYPE_OFFLINE | 0 | Offline. | 63| MEDIA_KEY_TYPE_ONLINE | 1 | Online. | 64 65## OfflineMediaKeyStatus 66 67Enumerates the statuses of offline media keys. 68 69**Atomic service API**: This API can be used in atomic services since API version 14. 70 71**System capability**: SystemCapability.Multimedia.Drm.Core 72 73| Name | Value | Description | 74| ------------------------- | ---- | ------------ | 75| OFFLINE_MEDIA_KEY_STATUS_UNKNOWN | 0 | Unknown status. | 76| OFFLINE_MEDIA_KEY_STATUS_USABLE | 1 | The media key is available. | 77| OFFLINE_MEDIA_KEY_STATUS_INACTIVE | 2 | The media key is inactive. | 78 79## CertificateStatus 80 81Enumerates the statuses of DRM certificates. 82 83**Atomic service API**: This API can be used in atomic services since API version 14. 84 85**System capability**: SystemCapability.Multimedia.Drm.Core 86 87| Name | Value | Description | 88| ------------------------- | ---- | ------------ | 89| CERT_STATUS_PROVISIONED | 0 | A DRM certificate has been installed on the device. | 90| CERT_STATUS_NOT_PROVISIONED | 1 | No DRM certificate is installed on the device. | 91| CERT_STATUS_EXPIRED | 2 | The DRM certificate has expired. | 92| CERT_STATUS_INVALID | 3 | The DRM certificate is invalid. | 93| CERT_STATUS_UNAVAILABLE | 4 | The DRM certificate is unavailable. | 94 95## MediaKeyRequestType 96 97Enumerates the types of media key requests. 98 99**Atomic service API**: This API can be used in atomic services since API version 12. 100 101**System capability**: SystemCapability.Multimedia.Drm.Core 102 103| Name | Value | Description | 104| ------------------------- | ---- | ------------ | 105| MEDIA_KEY_REQUEST_TYPE_UNKNOWN | 0 | Unknown type. | 106| MEDIA_KEY_REQUEST_TYPE_INITIAL | 1 | Initial request. | 107| MEDIA_KEY_REQUEST_TYPE_RENEWAL | 2 | Renewal request. | 108| MEDIA_KEY_REQUEST_TYPE_RELEASE | 3 | Release request. | 109| MEDIA_KEY_REQUEST_TYPE_NONE | 4 | None. | 110| MEDIA_KEY_REQUEST_TYPE_UPDATE | 5 | Update request. | 111 112## ContentProtectionLevel 113 114Enumerates the content protection levels. 115 116**Atomic service API**: This API can be used in atomic services since API version 12. 117 118**System capability**: SystemCapability.Multimedia.Drm.Core 119 120| Name | Value | Description | 121| ------------------------- | ---- | ------------ | 122| CONTENT_PROTECTION_LEVEL_UNKNOWN | 0 | Unknown content protection level. | 123| CONTENT_PROTECTION_LEVEL_SW_CRYPTO | 1 | Software content protection level. | 124| CONTENT_PROTECTION_LEVEL_HW_CRYPTO | 2 | Hardware content protection level. | 125| CONTENT_PROTECTION_LEVEL_ENHANCED_HW | 3 | Enhanced hardware content protection level. | 126| CONTENT_PROTECTION_LEVEL_MAX | 4 | Highest content protection level. | 127 128## ProvisionRequest 129 130Describes a provision request, which is used to request a DRM certificate from a provisioning server. 131 132**Atomic service API**: This API can be used in atomic services since API version 14. 133 134**System capability**: SystemCapability.Multimedia.Drm.Core 135 136| Name | Type | Mandatory| Description | 137| -------- | ----------------------------- |---- | ------------- | 138| data | Uint8Array | Yes | Data carried in the provision request. | 139| defaultURL | string | Yes | URL of the provisioning server (which provisions DRM certificates). | 140 141## OptionsData 142 143Describes the optional data carried in a media key request. 144 145**Atomic service API**: This API can be used in atomic services since API version 12. 146 147**System capability**: SystemCapability.Multimedia.Drm.Core 148 149| Name | Type | Mandatory| Description | 150| -------- | ----------------------------- |---- | ------------- | 151| name | string | Yes | Name of the optional data. | 152| value | string | Yes | Value of the optional data. | 153 154## MediaKeyRequest 155 156Describes a media key request. 157 158**Atomic service API**: This API can be used in atomic services since API version 12. 159 160**System capability**: SystemCapability.Multimedia.Drm.Core 161 162| Name | Type | Mandatory| Description | 163| -------- | ----------------------------- |---- | ------------- | 164| mediaKeyRequestType | [MediaKeyRequestType](#mediakeyrequesttype) | Yes | Type of the media key request. | 165| data | Uint8Array | Yes | Data carried in the media key request. | 166| defaultURL | string | Yes | URL of the license server (which provisions media keys). | 167 168## EventInfo 169 170Describes the event information. 171 172**Atomic service API**: This API can be used in atomic services since API version 12. 173 174**System capability**: SystemCapability.Multimedia.Drm.Core 175 176| Name | Type | Mandatory| Description | 177| -------- | ----------------------------- |---- | ------------- | 178| info | Uint8Array | Yes | Event information. | 179| extraInfo | string | Yes | Extended event information. | 180 181## StatisticKeyValue 182 183Describes the statistical information. 184 185**Atomic service API**: This API can be used in atomic services since API version 14. 186 187**System capability**: SystemCapability.Multimedia.Drm.Core 188 189| Name | Type | Mandatory| Description | 190| -------- | ----------------------------- |---- | ------------- | 191| name | string | Yes | Name of the statistical item. | 192| value | string | Yes | Value of the statistical item. | 193 194## MediaKeyStatus 195 196Describes the media key status. 197 198**Atomic service API**: This API can be used in atomic services since API version 12. 199 200**System capability**: SystemCapability.Multimedia.Drm.Core 201 202| Name | Type | Mandatory| Description | 203| -------- | ----------------------------- |---- | ------------- | 204| name | string | Yes | Name of the media key status (such as the media key expiration time and content protection level). | 205| value | string | Yes | Value of the media key status. | 206 207## KeysInfo 208 209Describes the information about media keys. 210 211**Atomic service API**: This API can be used in atomic services since API version 12. 212 213**System capability**: SystemCapability.Multimedia.Drm.Core 214 215| Name | Type | Mandatory| Description | 216| -------- | ----------------------------- |---- | ------------- | 217| keyId | Uint8Array | Yes | Media key ID. | 218| value | string | Yes | Media key status. | 219 220## MediaKeySystemInfo 221 222Describes the DRM information, which is used to encrypt content. 223 224**Atomic service API**: This API can be used in atomic services since API version 12. 225 226**System capability**: SystemCapability.Multimedia.Drm.Core 227 228| Name | Type | Mandatory| Description | 229| -------- | ----------------------------- |---- | ------------- | 230| uuid | string | Yes | UUID of the DRM content protection system. | 231| pssh | Uint8Array | Yes | Protection System Specific Header (PSSH) in the DRM information. | 232 233## MediaKeySystemDescription<sup>12+</sup> 234 235Describes the plugin information. 236 237**Atomic service API**: This API can be used in atomic services since API version 14. 238 239**System capability**: SystemCapability.Multimedia.Drm.Core 240 241| Name | Type | Mandatory| Description | 242| -------- | ----------------------------- |---- | ------------- | 243| name | string | Yes | Name of the plugin. | 244| uuid | string | Yes | UUID of the plugin. | 245 246## drm.createMediaKeySystem 247 248createMediaKeySystem(name: string): MediaKeySystem 249 250Creates a **MediaKeySystem** instance. 251 252**Atomic service API**: This API can be used in atomic services since API version 14. 253 254**System capability**: SystemCapability.Multimedia.Drm.Core 255 256**Parameters** 257 258| Name | Type | Mandatory| Description | 259| -------- | ----------------------------------------------- | ---- | ---------------------------- | 260| name | string | Yes | DRM solution name. | 261 262**Return value** 263 264| Type | Description | 265| ----------------------------------------------- | ---------------------------- | 266| [MediaKeySystem](#mediakeysystem) | **MediaKeySystem** instance. | 267 268**Error codes** 269 270For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 271 272| ID | Error Message | 273| --------------- | --------------- | 274| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 275| 24700101 | All unknown errors | 276| 24700103 | Meet max MediaKeySystem num limit | 277| 24700201 | Fatal service error, for example, service died | 278 279**Example** 280 281```ts 282import { drm } from '@kit.DrmKit'; 283import { BusinessError } from '@kit.BasicServicesKit'; 284try { 285 let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 286} catch (err) { 287 let error = err as BusinessError; 288 console.error(`createMediaKeySystem ERROR: ${error}`); 289} 290``` 291 292## drm.isMediaKeySystemSupported 293 294isMediaKeySystemSupported(name: string): boolean 295 296Checks whether the device supports the specified DRM solution. 297 298**Atomic service API**: This API can be used in atomic services since API version 14. 299 300**System capability**: SystemCapability.Multimedia.Drm.Core 301 302**Parameters** 303 304| Name | Type | Mandatory| Description | 305| -------- | ----------------------------------------------- | ---- | ---------------------------- | 306| name | string | Yes | DRM solution name. | 307 308**Return value** 309 310| Type | Description | 311| ----------------------------------------------- | ---------------------------- | 312| boolean | Returns **true** if the device supports the DRM solution; returns **false** otherwise. | 313 314**Error codes** 315 316For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 317 318| ID | Error Message | 319| --------------- | --------------- | 320| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Parameter verification failed, the param name's length is zero or too big(exceeds 4096 Bytes). | 321| 24700101 | All unknown errors | 322| 24700201 | Fatal service error, for example, service died | 323 324**Example** 325 326```ts 327import { drm } from '@kit.DrmKit'; 328import { BusinessError } from '@kit.BasicServicesKit'; 329 330try { 331 let supported: boolean = drm.isMediaKeySystemSupported("com.clearplay.drm"); 332 console.log("isMediaKeySystemSupported: ", supported); 333} catch (err) { 334 let error = err as BusinessError; 335 console.error(`isMediaKeySystemSupported ERROR: ${error}`); 336} 337``` 338 339## drm.isMediaKeySystemSupported 340 341isMediaKeySystemSupported(name: string, mimeType: string): boolean 342 343Checks whether the device supports the combination of the DRM solution and MIME type. 344 345**Atomic service API**: This API can be used in atomic services since API version 14. 346 347**System capability**: SystemCapability.Multimedia.Drm.Core 348 349**Parameters** 350 351| Name | Type | Mandatory| Description | 352| -------- | ----------------------------------------------- | ---- | ---------------------------- | 353| name | string | Yes | DRM solution name. | 354| mimeType | string | Yes | MIME type, which is determined by the DRM solution. | 355 356**Return value** 357 358| Type | Description | 359| ----------------------------------------------- | ---------------------------- | 360| boolean | Returns **true** if the device supports the combination; returns **false** otherwise. | 361 362**Error codes** 363 364For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 365 366| ID | Error Message | 367| --------------- | --------------- | 368| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 369| 24700101 | All unknown errors | 370| 24700201 | Fatal service error, for example, service died | 371 372**Example** 373 374```ts 375import { drm } from '@kit.DrmKit'; 376import { BusinessError } from '@kit.BasicServicesKit'; 377 378try { 379 let supported: boolean = drm.isMediaKeySystemSupported("com.clearplay.drm", "video/avc"); 380 console.log("isMediaKeySystemSupported: ", supported); 381} catch (err) { 382 let error = err as BusinessError; 383 console.error(`isMediaKeySystemSupported ERROR: ${error}`); 384} 385``` 386 387## drm.isMediaKeySystemSupported 388 389isMediaKeySystemSupported(name: string, mimeType: string, level: ContentProtectionLevel): boolean 390 391Checks whether the device supports the combination of the DRM solution, MIME type, and content protection level. 392 393**Atomic service API**: This API can be used in atomic services since API version 14. 394 395**System capability**: SystemCapability.Multimedia.Drm.Core 396 397**Parameters** 398 399| Name | Type | Mandatory| Description | 400| -------- | ----------------------------------------------- | ---- | ---------------------------- | 401| name | string | Yes | DRM solution name. | 402| mimeType | string | Yes | MIME type, which is determined by the DRM solution. | 403| level | [ContentProtectionLevel](#contentprotectionlevel) | Yes | Content protection level. | 404 405**Return value** 406 407| Type | Description | 408| ----------------------------------------------- | ---------------------------- | 409| boolean | Returns **true** if the device supports the combination; returns **false** otherwise. | 410 411**Error codes** 412 413For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 414 415| ID | Error Message | 416| --------------- | --------------- | 417| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 418| 24700101 | All unknown errors | 419| 24700201 | Fatal service error, for example, service died | 420 421**Example** 422 423```ts 424import { drm } from '@kit.DrmKit'; 425import { BusinessError } from '@kit.BasicServicesKit'; 426 427try { 428 let supported: boolean = drm.isMediaKeySystemSupported("com.clearplay.drm", "video/avc", drm.ContentProtectionLevel.CONTENT_PROTECTION_LEVEL_SW_CRYPTO); 429 console.log("isMediaKeySystemSupported: ", supported); 430} catch (err) { 431 let error = err as BusinessError; 432 console.error(`isMediaKeySystemSupported ERROR: ${error}`); 433} 434``` 435 436## drm.getMediaKeySystemUuid<sup>12+</sup> 437 438getMediaKeySystemUuid(name: string): string; 439 440Obtains the UUID of the DRM content protection system supported by the specified DRM solution. 441 442**Atomic service API**: This API can be used in atomic services since API version 14. 443 444**System capability**: SystemCapability.Multimedia.Drm.Core 445 446**Parameters** 447 448| Name | Type | Mandatory| Description | 449| -------- | ----------------------------------------------- | ---- | ---------------------------- | 450| name | string | Yes | DRM solution name. | 451 452**Return value** 453 454| Type | Description | 455| ----------------------------------------------- | ---------------------------- | 456| string | UUID of the DRM content protection system. | 457 458**Error codes** 459 460For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 461 462| ID | Error Message | 463| --------------- | --------------- | 464| 401 | The parameter check failed.Possibly because: 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 465| 24700101 | All unknown errors | 466| 24700201 | Fatal service error, for example, service died | 467 468**Example** 469 470```ts 471import { drm } from '@kit.DrmKit'; 472import { BusinessError } from '@kit.BasicServicesKit'; 473try { 474 let uuid: String = drm.getMediaKeySystemUuid("com.clearplay.drm"); 475 console.log("getMediaKeySystemUuid: ", uuid); 476} catch (err) { 477 let error = err as BusinessError; 478 console.error(`getMediaKeySystemUuid ERROR: ${error}`); 479} 480``` 481 482## drm.getMediaKeySystems<sup>12+</sup> 483 484getMediaKeySystems(): MediaKeySystemDescription[] 485 486Obtains the list of plugins supported by the device. 487 488**Atomic service API**: This API can be used in atomic services since API version 14. 489 490**System capability**: SystemCapability.Multimedia.Drm.Core 491 492**Return value** 493 494| Type | Description | 495| ----------------------------------------------- | ---------------------------- | 496| [MediaKeySystemDescription[]](#mediakeysystemdescription12) | Array of the supported plugins. | 497 498**Error codes** 499 500For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 501 502| ID | Error Message | 503| --------------- | --------------- | 504| 24700101 | All unknown errors | 505| 24700201 | Fatal service error, for example, service died | 506 507**Example** 508 509```ts 510import { drm } from '@kit.DrmKit'; 511import { BusinessError } from '@kit.BasicServicesKit'; 512try { 513 let description: drm.MediaKeySystemDescription[] = drm.getMediaKeySystems(); 514} catch (err) { 515 let error = err as BusinessError; 516 console.error(`getMediaKeySystems ERROR: ${error}`); 517} 518``` 519 520## MediaKeySystem 521Implements **MediaKeySystem** instance management. Specifically, it provides APIs to request and process DRM certificates, creates session, manages offline media key, obtain DRM statistical information, and obtain device configuration information. Before calling any API in **MediaKeySystem**, you must use [createMediaKeySystem](#drmcreatemediakeysystem) to create a **MediaKeySystem** instance. 522 523### setConfigurationString 524 525setConfigurationString(configName: string, value: string): void 526 527Sets a configuration item in the form of a string. 528 529**Atomic service API**: This API can be used in atomic services since API version 14. 530 531**System capability**: SystemCapability.Multimedia.Drm.Core 532 533**Parameters** 534 535| Name | Type | Mandatory| Description | 536| -------- | ----------------------------------------------- | ---- | ---------------------------- | 537| configName | string | Yes | Name of the configuration item, which is determined by the DRM solution on the device and cannot be empty. For details about available options, see [PreDefinedConfigName](#predefinedconfigname). | 538| value | string | Yes | Value of the configuration item. | 539 540**Error codes** 541 542For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 543 544| ID | Error Message | 545| --------------- | --------------- | 546| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 547| 24700101 | All unknown errors | 548| 24700201 | Fatal service error, for example, service died | 549 550**Example** 551 552```ts 553import { drm } from '@kit.DrmKit'; 554import { BusinessError } from '@kit.BasicServicesKit'; 555 556let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 557try { 558 mediaKeySystem.setConfigurationString("stringConfigName", "stringConfigValue"); // Ensure that stringConfigName is configurable. 559} catch (err) { 560 let error = err as BusinessError; 561 console.error(`setConfigurationString ERROR: ${error}`); 562} 563``` 564 565### getConfigurationString 566 567getConfigurationString(configName: string): string 568 569Obtains the value of a configuration item in the form of a string. 570 571**Atomic service API**: This API can be used in atomic services since API version 14. 572 573**System capability**: SystemCapability.Multimedia.Drm.Core 574 575**Parameters** 576 577| Name | Type | Mandatory| Description | 578| -------- | ----------------------------------------------- | ---- | ---------------------------- | 579| configName | string | Yes | Name of the configuration item, which is determined by the DRM solution on the device and cannot be empty. For details about available options, see [PreDefinedConfigName](#predefinedconfigname). | 580 581**Return value** 582 583| Type | Description | 584| ----------------------------------------------- | ---------------------------- | 585| string | Value of the configuration item in the form of a string. | 586 587**Error codes** 588 589For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 590 591| ID | Error Message | 592| --------------- | --------------- | 593| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Parameter verification failed, the param's length is zero or too big(exceeds 4096 Bytes). | 594| 24700101 | All unknown errors | 595| 24700201 | Fatal service error, for example, service died | 596 597**Example** 598 599```ts 600import { drm } from '@kit.DrmKit'; 601import { BusinessError } from '@kit.BasicServicesKit'; 602 603let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 604try { 605 let configValue: string = mediaKeySystem.getConfigurationString("vendor"); 606} catch (err) { 607 let error = err as BusinessError; 608 console.error(`getConfigurationString ERROR: ${error}`); 609} 610``` 611 612### setConfigurationByteArray 613 614setConfigurationByteArray(configName: string, value: Uint8Array): void 615 616Sets a configuration item in the form of a byte array. 617 618**Atomic service API**: This API can be used in atomic services since API version 14. 619 620**System capability**: SystemCapability.Multimedia.Drm.Core 621 622**Parameters** 623 624| Name | Type | Mandatory| Description | 625| -------- | ----------------------------------------------- | ---- | ---------------------------- | 626| configName | string | Yes | Name of the configuration item, which is determined by the DRM solution on the device and cannot be empty. For details about available options, see [PreDefinedConfigName](#predefinedconfigname). | 627| value | Uint8Array | Yes | Value of the configuration item in the form of an array. The specific value is determined by the DRM solution on the device. | 628 629**Error codes** 630 631For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 632 633| ID | Error Message | 634| --------------- | --------------- | 635| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 636| 24700101 | All unknown errors. | 637| 24700201 | Fatal service error, for example, service died. | 638 639**Example** 640 641```ts 642import { drm } from '@kit.DrmKit'; 643import { BusinessError } from '@kit.BasicServicesKit'; 644 645let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 646// Set configValue based on project requirements. 647let configValue: Uint8Array = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 648try { 649 // Ensure that byteArrayConfigName of the current DRM solution is configurable. 650 mediaKeySystem.setConfigurationByteArray("byteArrayConfigName", configValue); 651} catch (err) { 652 let error = err as BusinessError; 653 console.error(`setConfigurationByteArray ERROR: ${error}`); 654} 655``` 656 657### getConfigurationByteArray 658 659getConfigurationByteArray(configName: string): Uint8Array 660 661Obtains the value of a configuration item in the form of a byte array. 662 663**Atomic service API**: This API can be used in atomic services since API version 14. 664 665**System capability**: SystemCapability.Multimedia.Drm.Core 666 667**Parameters** 668 669| Name | Type | Mandatory| Description | 670| -------- | ----------------------------------------------- | ---- | ---------------------------- | 671| configName | string | Yes | Name of the configuration item, which is determined by the DRM solution on the device and cannot be empty. For details about available options, see [PreDefinedConfigName](#predefinedconfigname). | 672 673**Return value** 674 675| Type | Description | 676| ----------------------------------------------- | ---------------------------- | 677| Uint8Array | Value of the configuration item in the form of an array. | 678 679**Error codes** 680 681For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 682 683| ID | Error Message | 684| --------------- | --------------- | 685| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 686| 24700101 | All unknown errors | 687| 24700201 | Fatal service error, for example, service died | 688 689**Example** 690 691```ts 692import { drm } from '@kit.DrmKit'; 693import { BusinessError } from '@kit.BasicServicesKit'; 694 695let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 696try { 697 let configValue: Uint8Array = mediaKeySystem.getConfigurationByteArray("deviceUniqueId"); // Ensure that deviceUniqueId exists. 698} catch (err) { 699 let error = err as BusinessError; 700 console.error(`getConfigurationByteArray ERROR: ${error}`); 701} 702``` 703 704### getStatistics 705 706getStatistics(): StatisticKeyValue[] 707 708Obtains the statistical information, including the number of current sessions, plugin version, maximum decryption duration for each session, number of decryption times, and number of decryption failures. 709 710**Atomic service API**: This API can be used in atomic services since API version 14. 711 712**System capability**: SystemCapability.Multimedia.Drm.Core 713 714**Return value** 715 716| Type | Description | 717| ----------------------------------------------- | ---------------------------- | 718| [StatisticKeyValue[]](#statistickeyvalue) | Statistical information. | 719 720**Error codes** 721 722For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 723 724| ID | Error Message | 725| --------------- | --------------- | 726| 24700101 | All unknown errors | 727| 24700201 | Fatal service error, for example, service died | 728 729**Example** 730 731```ts 732import { drm } from '@kit.DrmKit'; 733import { BusinessError } from '@kit.BasicServicesKit'; 734 735let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 736try { 737 let statisticKeyValue: drm.StatisticKeyValue[] = mediaKeySystem.getStatistics(); 738} catch (err) { 739 let error = err as BusinessError; 740 console.error(`getConfigurationByteArray ERROR: ${error}`); 741} 742``` 743 744### getMaxContentProtectionLevel 745 746getMaxContentProtectionLevel(): ContentProtectionLevel 747 748Obtains the maximum content protection level supported by the current DRM solution. 749 750**Atomic service API**: This API can be used in atomic services since API version 14. 751 752**System capability**: SystemCapability.Multimedia.Drm.Core 753 754**Return value** 755 756| Type | Description | 757| ----------------------------------------------- | ---------------------------- | 758| [ContentProtectionLevel](#contentprotectionlevel) | Maximum content protection level. | 759 760**Error codes** 761 762For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 763 764| ID | Error Message | 765| --------------- | --------------- | 766| 24700101 | All unknown errors | 767| 24700201 | Fatal service error, for example, service died | 768 769**Example** 770 771```ts 772import { drm } from '@kit.DrmKit'; 773import { BusinessError } from '@kit.BasicServicesKit'; 774 775let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 776try { 777 let maxLevel: drm.ContentProtectionLevel = mediaKeySystem.getMaxContentProtectionLevel(); 778} catch (err) { 779 let error = err as BusinessError; 780 console.error(`getConfigurationByteArray ERROR: ${error}`); 781} 782``` 783 784### generateKeySystemRequest 785 786generateKeySystemRequest(): Promise<ProvisionRequest\> 787 788Generates a provision request. 789 790**Atomic service API**: This API can be used in atomic services since API version 14. 791 792**System capability**: SystemCapability.Multimedia.Drm.Core 793 794**Return value** 795 796| Type | Description | 797| ----------------------------------------------- | ---------------------------- | 798| Promise<[ProvisionRequest](#provisionrequest)\> | Promise used to return the provision request obtained. If a DRM certificate already exists on the device, a failure message is returned. | 799 800**Error codes** 801 802For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 803 804| ID | Error Message | 805| --------------- | --------------- | 806| 24700101 | All unknown errors | 807| 24700201 | Fatal service error, for example, service died | 808 809**Example** 810 811```ts 812import { drm } from '@kit.DrmKit'; 813import { BusinessError } from '@kit.BasicServicesKit'; 814 815let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 816// Do not call this API if a DRM certificate already exists on the device. 817mediaKeySystem.generateKeySystemRequest().then((ProvisionRequest: drm.ProvisionRequest) => { 818 console.log("generateKeySystemRequest"); 819}).catch((err: BusinessError) => { 820 console.error(`generateKeySystemRequest: ERROR: ${err}`); 821}); 822``` 823 824### processKeySystemResponse 825 826processKeySystemResponse(response: Uint8Array): Promise<void\> 827 828Processes a provision response. 829 830**Atomic service API**: This API can be used in atomic services since API version 14. 831 832**System capability**: SystemCapability.Multimedia.Drm.Core 833 834**Parameters** 835 836| Name | Type | Mandatory| Description | 837| -------- | ----------------------------------------------- | ---- | ---------------------------- | 838| response | Uint8Array | Yes | Provision response. | 839 840**Return value** 841 842| Type | Description | 843| ----------------------------------------------- | ---------------------------- | 844| Promise<void\> | Promise | 845 846**Error codes** 847 848For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 849 850| ID | Error Message | 851| --------------- | --------------- | 852| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 853| 24700101 | All unknown errors | 854| 24700201 | Fatal service error, for example, service died | 855 856**Example** 857 858```ts 859import { drm } from '@kit.DrmKit'; 860import { BusinessError } from '@kit.BasicServicesKit'; 861 862let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 863// keySystemResponse is the response obtained from the DRM service. Pass in the actual data obtained. 864let keySystemResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 865mediaKeySystem.processKeySystemResponse(keySystemResponse).then(() => { 866 console.log("processKeySystemResponse"); 867}).catch((err: BusinessError) => { 868 console.error(`processKeySystemResponse: ERROR: ${err}`); 869}); 870``` 871 872### getCertificateStatus 873 874getCertificateStatus():CertificateStatus 875 876Obtains the status of the DRM certificate. 877 878**Atomic service API**: This API can be used in atomic services since API version 14. 879 880**System capability**: SystemCapability.Multimedia.Drm.Core 881 882**Return value** 883 884| Type | Description | 885| ----------------------------------------------- | ---------------------------- | 886| [CertificateStatus](#certificatestatus) | Certificate status. | 887 888**Error codes** 889 890For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 891 892| ID | Error Message | 893| --------------- | --------------- | 894| 24700101 | All unknown errors | 895| 24700201 | Fatal service error, for example, service died | 896 897**Example** 898 899```ts 900import { drm } from '@kit.DrmKit'; 901import { BusinessError } from '@kit.BasicServicesKit'; 902 903let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 904try { 905 let certificateStatus: drm.CertificateStatus = mediaKeySystem.getCertificateStatus(); 906} catch (err) { 907 let error = err as BusinessError; 908 console.error(`getCertificateStatus ERROR: ${error}`); 909} 910``` 911 912### on('keySystemRequired') 913 914on(type: 'keySystemRequired', callback: (eventInfo: EventInfo) => void): void 915 916Subscribes to events indicating that the application requires a DRM certificate. 917 918**Atomic service API**: This API can be used in atomic services since API version 14. 919 920**System capability**: SystemCapability.Multimedia.Drm.Core 921 922**Parameters** 923 924| Name | Type | Mandatory| Description | 925| -------- | -------------------- | ---- | ------------------------------------- | 926| type | string | Yes | Event type. The event can be listened for when a **MediaKeySystem** instance is created. This event is triggered when the application requests a DRM certificate.| 927| callback | Callback\<[EventInfo](#eventinfo)\> | Yes | Callback used to return the event information. If this event callback is returned, a DRM certificate must be requested. | 928 929**Error codes** 930 931For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 932 933| ID | Error Message | 934| --------------- | --------------- | 935| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 936| 24700101 | All unknown errors | 937 938**Example** 939 940```ts 941import { drm } from '@kit.DrmKit'; 942 943let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 944mediaKeySystem.on('keySystemRequired', (eventInfo: drm.EventInfo) => { 945 console.log('keySystemRequired ' + 'extra: ' + eventInfo.extraInfo + 'data: ' + eventInfo.info); 946}); 947``` 948 949### off('keySystemRequired') 950 951off(type: 'keySystemRequired', callback?: (eventInfo: EventInfo) => void): void 952 953Unsubscribes from events indicating that the application requests a DRM certificate. 954 955**Atomic service API**: This API can be used in atomic services since API version 14. 956 957**System capability**: SystemCapability.Multimedia.Drm.Core 958 959**Parameters** 960 961| Name | Type | Mandatory| Description | 962| -------- | -------------------- | ---- | ------------------------------------- | 963| type | string | Yes | Event type. The event can be listened for when a **MediaKeySystem** instance is created.| 964| callback | Callback\<[EventInfo](#eventinfo)\> | No | Callback used to return the event information. | 965 966**Error codes** 967 968For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 969 970| ID | Error Message | 971| --------------- | --------------- | 972| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 973| 24700101 | All unknown errors | 974 975**Example** 976 977```ts 978let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 979mediaKeySystem.off('keySystemRequired'); 980``` 981 982### createMediaKeySession 983 984createMediaKeySession(level: ContentProtectionLevel): MediaKeySession 985 986Creates a **MediaKeySession** instance with the specified content protection level. 987 988**Atomic service API**: This API can be used in atomic services since API version 14. 989 990**System capability**: SystemCapability.Multimedia.Drm.Core 991 992**Parameters** 993 994| Name | Type | Mandatory| Description | 995| -------- | ----------------------------------------------- | ---- | ---------------------------- | 996| level | [ContentProtectionLevel](#contentprotectionlevel) | Yes | Content protection level. | 997 998**Return value** 999 1000| Type | Description | 1001| ----------------------------------------------- | ---------------------------- | 1002| [MediaKeySession](#mediakeysession) | **MediaKeySession** instance. | 1003 1004**Error codes** 1005 1006For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1007 1008| ID | Error Message | 1009| --------------- | --------------- | 1010| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.The param level exceeds reasonable range, please use value in ContentProtectionLevel. | 1011| 24700101 | All unknown errors | 1012| 24700104 | Meet max MediaKeySession num limit | 1013| 24700201 | Fatal service error, for example, service died | 1014 1015**Example** 1016 1017```ts 1018import { drm } from '@kit.DrmKit'; 1019import { BusinessError } from '@kit.BasicServicesKit'; 1020 1021let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1022try { 1023 let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(drm.ContentProtectionLevel.CONTENT_PROTECTION_LEVEL_SW_CRYPTO); 1024} catch (err) { 1025 let error = err as BusinessError; 1026 console.error(`createMediaKeySession ERROR: ${error}`); 1027} 1028``` 1029 1030### createMediaKeySession 1031 1032createMediaKeySession(): MediaKeySession 1033 1034Creates a **MediaKeySession** instance with the default content protection level of the DRM solution. 1035 1036**Atomic service API**: This API can be used in atomic services since API version 14. 1037 1038**System capability**: SystemCapability.Multimedia.Drm.Core 1039 1040**Return value** 1041 1042| Type | Description | 1043| ----------------------------------------------- | ---------------------------- | 1044| [MediaKeySession](#mediakeysession) | **MediaKeySession** instance. | 1045 1046**Error codes** 1047 1048For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1049 1050| ID | Error Message | 1051| --------------- | --------------- | 1052| 24700101 | All unknown errors | 1053| 24700104 | Meet max MediaKeySession num limit | 1054| 24700201 | Fatal service error, for example, service died | 1055 1056**Example** 1057 1058```ts 1059import { drm } from '@kit.DrmKit'; 1060import { BusinessError } from '@kit.BasicServicesKit'; 1061 1062let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1063try { 1064 let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1065} catch (err) { 1066 let error = err as BusinessError; 1067 console.error(`createMediaKeySession ERROR: ${error}`); 1068} 1069``` 1070 1071### getOfflineMediaKeyIds 1072 1073getOfflineMediaKeyIds(): Uint8Array[] 1074 1075Obtains the IDs of offline media keys. 1076 1077**Atomic service API**: This API can be used in atomic services since API version 14. 1078 1079**System capability**: SystemCapability.Multimedia.Drm.Core 1080 1081 1082**Return value** 1083 1084| Type | Description | 1085| ----------------------------------------------- | ---------------------------- | 1086| Uint8Array[] | Array holding the IDs of offline media keys. | 1087 1088**Error codes** 1089 1090For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1091 1092| ID | Error Message | 1093| --------------- | --------------- | 1094| 24700101 | All unknown errors | 1095| 24700201 | Fatal service error, for example, service died | 1096 1097**Example** 1098 1099```ts 1100import { drm } from '@kit.DrmKit'; 1101import { BusinessError } from '@kit.BasicServicesKit'; 1102 1103let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1104try { 1105 let offlineMediaKeyIds: Uint8Array[] = mediaKeySystem.getOfflineMediaKeyIds(); 1106} catch (err) { 1107 let error = err as BusinessError; 1108 console.error(`getOfflineMediaKeyIds ERROR: ${error}`); 1109} 1110``` 1111 1112### getOfflineMediaKeyStatus 1113 1114getOfflineMediaKeyStatus(mediaKeyId: Uint8Array): OfflineMediaKeyStatus 1115 1116Obtains the status of offline media keys with the specified IDs. 1117 1118**Atomic service API**: This API can be used in atomic services since API version 14. 1119 1120**System capability**: SystemCapability.Multimedia.Drm.Core 1121 1122**Parameters** 1123 1124| Name | Type | Mandatory| Description | 1125| -------- | ----------------------------------------------- | ---- | ---------------------------- | 1126| mediaKeyId | Uint8Array | Yes | Array holding the IDs of offline media keys. | 1127 1128**Return value** 1129 1130| Type | Description | 1131| ----------------------------------------------- | ---------------------------- | 1132| [OfflineMediaKeyStatus](#offlinemediakeystatus) | Status of the offline media keys. | 1133 1134**Error codes** 1135 1136For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1137 1138| ID | Error Message | 1139| --------------- | --------------- | 1140| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1141| 24700101 | All unknown errors | 1142| 24700201 | Fatal service error, for example, service died | 1143 1144**Example** 1145 1146```ts 1147import { drm } from '@kit.DrmKit'; 1148import { BusinessError } from '@kit.BasicServicesKit'; 1149 1150let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1151// mediaKeyId is the return value of processMediaKeyResponse or getOfflineMediaKeyIds. Pass in the actual data returned. 1152let mediaKeyId = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 1153try { 1154 let configValue: drm.OfflineMediaKeyStatus = mediaKeySystem.getOfflineMediaKeyStatus(mediaKeyId); 1155} catch (err) { 1156 let error = err as BusinessError; 1157 console.error(`getOfflineMediaKeyStatus ERROR: ${error}`); 1158} 1159``` 1160 1161### clearOfflineMediaKeys 1162 1163clearOfflineMediaKeys(mediaKeyId: Uint8Array): void 1164 1165Clears offline media keys by ID. 1166 1167**Atomic service API**: This API can be used in atomic services since API version 14. 1168 1169**System capability**: SystemCapability.Multimedia.Drm.Core 1170 1171**Parameters** 1172 1173| Name | Type | Mandatory| Description | 1174| -------- | ----------------------------------------------- | ---- | ---------------------------- | 1175| mediaKeyId | Uint8Array | Yes | Array holding the IDs of offline media keys. | 1176 1177**Error codes** 1178 1179For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1180 1181| ID | Error Message | 1182| --------------- | --------------- | 1183| 401 | The parameter check failed.Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1184| 24700101 | All unknown errors | 1185| 24700201 | Fatal service error, for example, service died | 1186 1187**Example** 1188 1189```ts 1190import { drm } from '@kit.DrmKit'; 1191import { BusinessError } from '@kit.BasicServicesKit'; 1192 1193let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1194// mediaKeyId is the return value of processMediaKeyResponse or getOfflineMediaKeyIds. Pass in the actual data returned. 1195let mediaKeyId = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 1196try { 1197 mediaKeySystem.clearOfflineMediaKeys(mediaKeyId); 1198} catch (err) { 1199 let error = err as BusinessError; 1200 console.error(`clearOfflineMediaKeys ERROR: ${error}`); 1201} 1202``` 1203 1204### destroy 1205 1206destroy(): void 1207 1208Destroys this **MediaKeySystem** instance. 1209 1210**Atomic service API**: This API can be used in atomic services since API version 14. 1211 1212**System capability**: SystemCapability.Multimedia.Drm.Core 1213 1214**Error codes** 1215 1216For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1217 1218| ID | Error Message | 1219| --------------- | --------------- | 1220| 24700101 | All unknown errors | 1221| 24700201 | Fatal service error, for example, service died | 1222 1223**Example** 1224 1225```ts 1226import { drm } from '@kit.DrmKit'; 1227import { BusinessError } from '@kit.BasicServicesKit'; 1228 1229let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1230try { 1231 mediaKeySystem.destroy(); 1232} catch (err) { 1233 let error = err as BusinessError; 1234 console.error(`mediaKeySystem destroy ERROR: ${error}`); 1235} 1236``` 1237 1238## MediaKeySession 1239Implements media key management. Before calling any API in **MediaKeySession**, you must use [createMediaKeySession](#createmediakeysession) to create a **MediaKeySession** instance. 1240 1241### generateMediaKeyRequest 1242 1243generateMediaKeyRequest(mimeType: string, initData: Uint8Array, mediaKeyType: number, options?: OptionsData[]): Promise<MediaKeyRequest\> 1244 1245Generates a media key request. 1246 1247**Atomic service API**: This API can be used in atomic services since API version 12. 1248 1249**System capability**: SystemCapability.Multimedia.Drm.Core 1250 1251**Parameters** 1252 1253| Name | Type | Mandatory| Description | 1254| -------- | ----------------------------------------------- | ---- | ---------------------------- | 1255| mimeType | string | Yes | MIME type, which is determined by the DRM solution. | 1256| initData | Uint8Array | Yes | Initial data. | 1257| mediaKeyType| number | Yes | Type of the media key. The value **0** means an online media key, and **1** means an offline media key.| 1258| options | [OptionsData[]](#optionsdata) | No | Optional data. | 1259 1260**Return value** 1261 1262| Type | Description | 1263| ----------------------------------------------- | ---------------------------- | 1264| Promise<[MediaKeyRequest](#mediakeyrequest)\> | Promise used to return the media key request generated. | 1265 1266**Error codes** 1267 1268For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1269 1270| ID | Error Message | 1271| --------------- | --------------- | 1272| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1273| 24700101 | All unknown errors | 1274| 24700201 | Fatal service error, for example, service died | 1275 1276**Example** 1277 1278```ts 1279import { drm } from '@kit.DrmKit'; 1280import { BusinessError } from '@kit.BasicServicesKit'; 1281 1282let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1283let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1284// PSSH data is the descriptive header of the copyright protection system and is encapsulated in encrypted streams. Specifically, in MP4 file, the PSSH data is found within the PSSH box; for DASH streams, the PSSH data is located in the MPD and MP4 PSSH box; for HLS+TS streams, the PSSH data is located in the M3U8 file and each TS segment. Pass in the actual value. 1285let uint8pssh = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 1286mediaKeySession.generateMediaKeyRequest("video/avc", uint8pssh, drm.MediaKeyType.MEDIA_KEY_TYPE_ONLINE).then((mediaKeyRequest: drm.MediaKeyRequest) =>{ 1287 console.log('generateMediaKeyRequest' + mediaKeyRequest); 1288}).catch((err: BusinessError) => { 1289 console.error(`generateMediaKeyRequest: ERROR: ${err}`); 1290}); 1291``` 1292 1293### processMediaKeyResponse 1294 1295processMediaKeyResponse(response: Uint8Array): Promise<Uint8Array\> 1296 1297Processes a media key response. 1298 1299**Atomic service API**: This API can be used in atomic services since API version 12. 1300 1301**System capability**: SystemCapability.Multimedia.Drm.Core 1302 1303**Parameters** 1304 1305| Name | Type | Mandatory| Description | 1306| -------- | ----------------------------------------------- | ---- | ---------------------------- | 1307| response | Uint8Array | Yes | Media key response. | 1308 1309**Return value** 1310 1311| Type | Description | 1312| ----------------------------------------------- | ---------------------------- | 1313| Promise<Uint8Array\> | Promise used to return the media key IDs. | 1314 1315**Error codes** 1316 1317For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1318 1319| ID | Error Message | 1320| --------------- | --------------- | 1321| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1322| 24700101 | All unknown errors | 1323| 24700201 | Fatal service error, for example, service died | 1324 1325**Example** 1326 1327```ts 1328import { drm } from '@kit.DrmKit'; 1329import { BusinessError } from '@kit.BasicServicesKit'; 1330 1331let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1332let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1333// mediaKeyResponse is obtained from the DRM service. Pass in the actual value obtained. 1334let mediaKeyResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 1335mediaKeySession.processMediaKeyResponse(mediaKeyResponse).then((mediaKeyId: Uint8Array) => { 1336 console.log('processMediaKeyResponse:' + mediaKeyId); 1337}).catch((err: BusinessError) => { 1338 console.error(`processMediaKeyResponse: ERROR: ${err}`); 1339}); 1340``` 1341 1342### checkMediaKeyStatus 1343 1344 checkMediaKeyStatus(): MediaKeyStatus[] 1345 1346Checks the status of the media keys in use. 1347 1348**Atomic service API**: This API can be used in atomic services since API version 12. 1349 1350**System capability**: SystemCapability.Multimedia.Drm.Core 1351 1352**Return value** 1353 1354| Type | Description | 1355| ----------------------------------------------- | ---------------------------- | 1356| [MediaKeyStatus[]](#mediakeystatus) | Media key status. | 1357 1358**Error codes** 1359 1360For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1361 1362| ID | Error Message | 1363| --------------- | --------------- | 1364| 24700101 | All unknown errors | 1365| 24700201 | Fatal service error, for example, service died | 1366 1367**Example** 1368 1369```ts 1370import { drm } from '@kit.DrmKit'; 1371import { BusinessError } from '@kit.BasicServicesKit'; 1372 1373let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1374let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1375try { 1376 let keyStatus: drm.MediaKeyStatus[] = mediaKeySession.checkMediaKeyStatus(); 1377} catch (err) { 1378 let error = err as BusinessError; 1379 console.error(`checkMediaKeyStatus ERROR: ${error}`); 1380} 1381``` 1382 1383### clearMediaKeys 1384 1385clearMediaKeys(): void 1386 1387Clears the media keys in use. 1388 1389**Atomic service API**: This API can be used in atomic services since API version 12. 1390 1391**System capability**: SystemCapability.Multimedia.Drm.Core 1392 1393**Error codes** 1394 1395For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1396 1397| ID | Error Message | 1398| --------------- | --------------- | 1399| 24700101 | All unknown errors | 1400| 24700201 | Fatal service error, for example, service died | 1401 1402**Example** 1403 1404```ts 1405import { drm } from '@kit.DrmKit'; 1406import { BusinessError } from '@kit.BasicServicesKit'; 1407 1408let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1409let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1410// mediaKeyResponse is obtained from the DRM service. Pass in the actual value obtained. 1411let mediaKeyResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 1412mediaKeySession.processMediaKeyResponse(mediaKeyResponse).then((mediaKeyId: Uint8Array) => { 1413 console.log('processMediaKeyResponse:' + mediaKeyId); 1414}).catch((err: BusinessError) => { 1415 console.error(`processMediaKeyResponse: ERROR: ${err}`); 1416}); 1417try { 1418 mediaKeySession.clearMediaKeys(); 1419} catch (err) { 1420 let error = err as BusinessError; 1421 console.error(`clearMediaKeys ERROR: ${error}`); 1422} 1423``` 1424 1425### generateOfflineReleaseRequest 1426 1427generateOfflineReleaseRequest(mediaKeyId: Uint8Array): Promise<Uint8Array\> 1428 1429Generates a request to release offline media keys. 1430 1431**Atomic service API**: This API can be used in atomic services since API version 12. 1432 1433**System capability**: SystemCapability.Multimedia.Drm.Core 1434 1435**Parameters** 1436 1437| Name | Type | Mandatory| Description | 1438| -------- | ----------------------------------------------- | ---- | ---------------------------- | 1439| mediaKeyId | Uint8Array | Yes | Array holding the IDs of offline media keys. | 1440 1441**Return value** 1442 1443| Type | Description | 1444| ----------------------------------------------- | ---------------------------- | 1445| Promise<Uint8Array\> | Promise used to return the request generated if the DRM solution on the device supports offline media key release. | 1446 1447**Error codes** 1448 1449For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1450 1451| ID | Error Message | 1452| --------------- | --------------- | 1453| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1454| 24700101 | All unknown errors | 1455| 24700201 | Fatal service error, for example, service died | 1456 1457**Example** 1458 1459```ts 1460import { drm } from '@kit.DrmKit'; 1461import { BusinessError } from '@kit.BasicServicesKit'; 1462 1463let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1464let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1465// mediaKeyId is the return value of processMediaKeyResponse or getOfflineMediaKeyIds. Pass in the actual data returned. 1466let mediaKeyId = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 1467mediaKeySession.generateOfflineReleaseRequest(mediaKeyId).then((offlineReleaseRequest: Uint8Array) => { 1468 console.log('generateOfflineReleaseRequest:' + offlineReleaseRequest); 1469}).catch((err: BusinessError) => { 1470 console.error(`generateOfflineReleaseRequest: ERROR: ${err}`); 1471}); 1472``` 1473 1474### processOfflineReleaseResponse 1475 1476processOfflineReleaseResponse(mediaKeyId: Uint8Array, response: Uint8Array): Promise<void\> 1477 1478Processes a response to a request for releasing offline media keys. 1479 1480**Atomic service API**: This API can be used in atomic services since API version 12. 1481 1482**System capability**: SystemCapability.Multimedia.Drm.Core 1483 1484**Parameters** 1485 1486| Name | Type | Mandatory| Description | 1487| -------- | ----------------------------------------------- | ---- | ---------------------------- | 1488| mediaKeyId | Uint8Array | Yes | Array holding the IDs of offline media keys. | 1489| response | Uint8Array | Yes | Response to the request for releasing offline media keys. | 1490 1491**Return value** 1492 1493| Type | Description | 1494| ----------------------------------------------- | ---------------------------- | 1495| Promise<void\> | Promise used to return the result if the DRM solution on the device supports offline media key release. | 1496 1497**Error codes** 1498 1499For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1500 1501| ID | Error Message | 1502| --------------- | --------------- | 1503| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1504| 24700101 | All unknown errors | 1505| 24700201 | Fatal service error, for example, service died | 1506 1507**Example** 1508 1509```ts 1510import { drm } from '@kit.DrmKit'; 1511import { BusinessError } from '@kit.BasicServicesKit'; 1512 1513let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1514let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1515// mediaKeyId is the return value of processMediaKeyResponse or getOfflineMediaKeyIds. Apply for memory based on the actual length. 1516let mediaKeyId = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 1517mediaKeySession.generateOfflineReleaseRequest(mediaKeyId).then((offlineReleaseRequest: Uint8Array) => { 1518 console.log('generateOfflineReleaseRequest:' + offlineReleaseRequest); 1519}).catch((err: BusinessError) => { 1520 console.error(`generateOfflineReleaseRequest: ERROR: ${err}`); 1521}); 1522// offlineReleaseResponse is obtained from the DRM service. Apply for memory based on the actual length. 1523let offlineReleaseResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 1524mediaKeySession.processOfflineReleaseResponse(mediaKeyId, offlineReleaseResponse).then(() => { 1525 console.log('processOfflineReleaseResponse'); 1526}).catch((err: BusinessError) => { 1527 console.error(`processOfflineReleaseResponse: ERROR: ${err}`); 1528}); 1529``` 1530 1531### restoreOfflineMediaKeys 1532 1533restoreOfflineMediaKeys(mediaKeyId: Uint8Array): Promise<void\> 1534 1535Restores offline media keys. 1536 1537**Atomic service API**: This API can be used in atomic services since API version 12. 1538 1539**System capability**: SystemCapability.Multimedia.Drm.Core 1540 1541**Parameters** 1542 1543| Name | Type | Mandatory| Description | 1544| -------- | ----------------------------------------------- | ---- | ---------------------------- | 1545| mediaKeyId | Uint8Array | Yes | Array holding the IDs of offline media keys. | 1546 1547**Return value** 1548 1549| Type | Description | 1550| ----------------------------------------------- | ---------------------------- | 1551| Promise<void\> | Promise | 1552 1553**Error codes** 1554 1555For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1556 1557| ID | Error Message | 1558| --------------- | --------------- | 1559| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1560| 24700101 | All unknown errors | 1561| 24700201 | Fatal service error, for example, service died | 1562 1563**Example** 1564 1565```ts 1566import { drm } from '@kit.DrmKit'; 1567import { BusinessError } from '@kit.BasicServicesKit'; 1568 1569let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1570let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1571// mediaKeyId is the return value of processMediaKeyResponse or getOfflineMediaKeyIds. Pass in the actual data returned. 1572let mediaKeyId = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 1573mediaKeySession.restoreOfflineMediaKeys(mediaKeyId).then(() => { 1574 console.log("restoreOfflineMediaKeys"); 1575}).catch((err: BusinessError) => { 1576 console.error(`restoreOfflineMediaKeys: ERROR: ${err}`); 1577}); 1578``` 1579 1580### getContentProtectionLevel 1581 1582getContentProtectionLevel(): ContentProtectionLevel 1583 1584Obtains the content protection level of this media key session. 1585 1586**Atomic service API**: This API can be used in atomic services since API version 12. 1587 1588**System capability**: SystemCapability.Multimedia.Drm.Core 1589 1590**Return value** 1591 1592| Type | Description | 1593| ----------------------------------------------- | ---------------------------- | 1594| [ContentProtectionLevel](#contentprotectionlevel) | Content protection level. | 1595 1596**Error codes** 1597 1598For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1599 1600| ID | Error Message | 1601| --------------- | --------------- | 1602| 24700101 | All unknown errors | 1603| 24700201 | Fatal service error, for example, service died | 1604 1605**Example** 1606 1607```ts 1608import { drm } from '@kit.DrmKit'; 1609import { BusinessError } from '@kit.BasicServicesKit'; 1610 1611let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1612let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1613try { 1614 let contentProtectionLevel: drm.ContentProtectionLevel = mediaKeySession.getContentProtectionLevel(); 1615} catch (err) { 1616 let error = err as BusinessError; 1617 console.error(`getContentProtectionLevel ERROR: ${error}`); 1618} 1619``` 1620 1621### requireSecureDecoderModule 1622 1623requireSecureDecoderModule(mimeType: string): boolean 1624 1625Checks whether secure decoding is required. 1626 1627**Atomic service API**: This API can be used in atomic services since API version 12. 1628 1629**System capability**: SystemCapability.Multimedia.Drm.Core 1630 1631**Parameters** 1632 1633| Name | Type | Mandatory| Description | 1634| -------- | ----------------------------------------------- | ---- | ---------------------------- | 1635| mimeType | string | Yes | MIME type, which is determined by the DRM solution. | 1636 1637**Return value** 1638 1639| Type | Description | 1640| ----------------------------------------------- | ---------------------------- | 1641| boolean | Whether secure decoding is required. The value **true** means that secure decoding is required, and **false** means the opposite. | 1642 1643**Error codes** 1644 1645For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1646 1647| ID | Error Message | 1648| --------------- | --------------- | 1649| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1650| 24700101 | All unknown errors | 1651| 24700201 | Fatal service error, for example, service died | 1652 1653**Example** 1654 1655```ts 1656import { drm } from '@kit.DrmKit'; 1657import { BusinessError } from '@kit.BasicServicesKit'; 1658 1659let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1660let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1661try { 1662 let status: boolean = mediaKeySession.requireSecureDecoderModule("video/avc"); 1663} catch (err) { 1664 let error = err as BusinessError; 1665 console.error(`requireSecureDecoderModule ERROR: ${error}`); 1666} 1667``` 1668 1669### on('keyRequired') 1670 1671on(type: 'keyRequired', callback: (eventInfo: EventInfo) => void): void 1672 1673Subscribes to events indicating that the application requests a media key. 1674 1675**Atomic service API**: This API can be used in atomic services since API version 12. 1676 1677**System capability**: SystemCapability.Multimedia.Drm.Core 1678 1679**Parameters** 1680 1681| Name | Type | Mandatory| Description | 1682| -------- | -------------------- | ---- | ------------------------------------- | 1683| type | string | Yes | Event type. The value is fixed at **'keyRequired'**. This event is triggered when the application requires a media key.| 1684| callback | Callback\<[EventInfo](#eventinfo)\> | Yes | Callback used to return the event information. | 1685 1686**Error codes** 1687 1688For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1689 1690| ID | Error Message | 1691| --------------- | --------------- | 1692| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1693| 24700101 | All unknown errors | 1694 1695**Example** 1696 1697```ts 1698import { drm } from '@kit.DrmKit'; 1699 1700let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1701let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1702mediaKeySession.on('keyRequired', (eventInfo: drm.EventInfo) => { 1703 console.log('keyRequired ' + 'extra: ' + eventInfo.extraInfo + 'data: ' + eventInfo.info); 1704}); 1705``` 1706 1707### off('keyRequired') 1708 1709off(type: 'keyRequired', callback?: (eventInfo: EventInfo) => void): void 1710 1711Unsubscribes from events indicating that the application requests a media key. 1712 1713**Atomic service API**: This API can be used in atomic services since API version 12. 1714 1715**System capability**: SystemCapability.Multimedia.Drm.Core 1716 1717**Parameters** 1718 1719| Name | Type | Mandatory| Description | 1720| -------- | -------------------- | ---- | ------------------------------------- | 1721| type | string | Yes | Event type. The value is fixed at **'keyRequired'**.| 1722| callback | Callback\<[EventInfo](#eventinfo)\> | No | Callback used to return the event information. | 1723 1724**Error codes** 1725 1726For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1727 1728| ID | Error Message | 1729| --------------- | --------------- | 1730| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1731| 24700101 | All unknown errors | 1732 1733**Example** 1734 1735```ts 1736import { drm } from '@kit.DrmKit'; 1737 1738let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1739let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1740mediaKeySession.off('keyRequired'); 1741``` 1742 1743### on('keyExpired') 1744 1745on(type: 'keyExpired', callback: (eventInfo: EventInfo) => void): void 1746 1747Subscribes to events indicating that a media key expires. 1748 1749**Atomic service API**: This API can be used in atomic services since API version 12. 1750 1751**System capability**: SystemCapability.Multimedia.Drm.Core 1752 1753**Parameters** 1754 1755| Name | Type | Mandatory| Description | 1756| -------- | -------------------- | ---- | ------------------------------------- | 1757| type | string | Yes | Event type. The value is fixed at **'keyExpired'**. This event is triggered when a media key expires.| 1758| callback | Callback\<[EventInfo](#eventinfo)\> | Yes | Callback used to return the event information. | 1759 1760**Error codes** 1761 1762For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1763 1764| ID | Error Message | 1765| --------------- | --------------- | 1766| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1767| 24700101 | All unknown errors | 1768 1769**Example** 1770 1771```ts 1772import { drm } from '@kit.DrmKit'; 1773 1774let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1775let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1776mediaKeySession.on('keyExpired', (eventInfo: drm.EventInfo) => { 1777 console.log('keyExpired ' + 'extra: ' + eventInfo.extraInfo + 'data: ' + eventInfo.info); 1778}); 1779``` 1780 1781### off('keyExpired') 1782 1783off(type: 'keyExpired', callback?: (eventInfo: EventInfo) => void): void 1784 1785Unsubscribes from events indicating that a media key expires. 1786 1787**Atomic service API**: This API can be used in atomic services since API version 12. 1788 1789**System capability**: SystemCapability.Multimedia.Drm.Core 1790 1791**Parameters** 1792 1793| Name | Type | Mandatory| Description | 1794| -------- | -------------------- | ---- | ------------------------------------- | 1795| type | string | Yes | Event type. The value is fixed at **'keyExpired'**.| 1796| callback | Callback\<[EventInfo](#eventinfo)\> | No | Callback used to return the event information. | 1797 1798**Error codes** 1799 1800For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1801 1802| ID | Error Message | 1803| --------------- | --------------- | 1804| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1805| 24700101 | All unknown errors | 1806 1807**Example** 1808 1809```ts 1810import { drm } from '@kit.DrmKit'; 1811 1812let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1813let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1814mediaKeySession.off('keyExpired'); 1815``` 1816 1817### on('vendorDefined') 1818 1819on(type: 'vendorDefined', callback: (eventInfo: EventInfo) => void): void 1820 1821Subscribes to vendor-defined events. 1822 1823**Atomic service API**: This API can be used in atomic services since API version 12. 1824 1825**System capability**: SystemCapability.Multimedia.Drm.Core 1826 1827**Parameters** 1828 1829| Name | Type | Mandatory| Description | 1830| -------- | -------------------- | ---- | ------------------------------------- | 1831| type | string | Yes | Event type. The value is fixed at **'vendorDefined'**. This event is triggered when a vendor-defined event occurs.| 1832| callback | Callback\<[EventInfo](#eventinfo)\> | Yes | Callback used to return the event information. | 1833 1834**Error codes** 1835 1836For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1837 1838| ID | Error Message | 1839| --------------- | --------------- | 1840| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1841| 24700101 | All unknown errors | 1842 1843**Example** 1844 1845```ts 1846import { drm } from '@kit.DrmKit'; 1847 1848let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1849let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1850mediaKeySession.on('vendorDefined', (eventInfo: drm.EventInfo) => { 1851 console.log('vendorDefined ' + 'extra: ' + eventInfo.extraInfo + 'data: ' + eventInfo.info); 1852}); 1853``` 1854 1855### off('vendorDefined') 1856 1857off(type: 'vendorDefined', callback?: (eventInfo: EventInfo) => void): void 1858 1859Unsubscribes from vendor-defined events. 1860 1861**Atomic service API**: This API can be used in atomic services since API version 12. 1862 1863**System capability**: SystemCapability.Multimedia.Drm.Core 1864 1865**Parameters** 1866 1867| Name | Type | Mandatory| Description | 1868| -------- | -------------------- | ---- | ------------------------------------- | 1869| type | string | Yes | Event type. The value is fixed at **'vendorDefined'**.| 1870| callback | Callback\<[EventInfo](#eventinfo)\> | No | Callback used to return the event information. | 1871 1872**Error codes** 1873 1874For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1875 1876| ID | Error Message | 1877| --------------- | --------------- | 1878| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1879| 24700101 | All unknown errors | 1880 1881**Example** 1882 1883```ts 1884import { drm } from '@kit.DrmKit'; 1885 1886let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1887let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1888mediaKeySession.off('vendorDefined'); 1889``` 1890 1891### on('expirationUpdate') 1892 1893on(type: 'expirationUpdate', callback: (eventInfo: EventInfo) => void): void 1894 1895Subscribes to events indicating that a media key updates on expiry. 1896 1897**Atomic service API**: This API can be used in atomic services since API version 12. 1898 1899**System capability**: SystemCapability.Multimedia.Drm.Core 1900 1901**Parameters** 1902 1903| Name | Type | Mandatory| Description | 1904| -------- | -------------------- | ---- | ------------------------------------- | 1905| type | string | Yes | Event type. The value is fixed at **'expirationUpdate'**. This event is triggered when a media key updates on expiry.| 1906| callback | Callback\<[EventInfo](#eventinfo)\> | Yes | Callback used to return the event information. | 1907 1908**Error codes** 1909 1910For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1911 1912| ID | Error Message | 1913| --------------- | --------------- | 1914| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1915| 24700101 | All unknown errors | 1916 1917**Example** 1918 1919```ts 1920import { drm } from '@kit.DrmKit'; 1921 1922let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1923let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1924mediaKeySession.on('expirationUpdate', (eventInfo: drm.EventInfo) => { 1925 console.log('expirationUpdate ' + 'extra: ' + eventInfo.extraInfo + 'data: ' + eventInfo.info); 1926}); 1927``` 1928 1929### off('expirationUpdate') 1930 1931off(type: 'expirationUpdate', callback?: (eventInfo: EventInfo) => void): void 1932 1933Unsubscribes from events indicating that a media key updates on expiry. 1934 1935**Atomic service API**: This API can be used in atomic services since API version 12. 1936 1937**System capability**: SystemCapability.Multimedia.Drm.Core 1938 1939**Parameters** 1940 1941| Name | Type | Mandatory| Description | 1942| -------- | -------------------- | ---- | ------------------------------------- | 1943| type | string | Yes | Event type. The value is fixed at **'expirationUpdate'**.| 1944| callback | Callback\<[EventInfo](#eventinfo)\> | No | Callback used to return the event information. | 1945 1946**Error codes** 1947 1948For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1949 1950| ID | Error Message | 1951| --------------- | --------------- | 1952| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1953| 24700101 | All unknown errors | 1954 1955**Example** 1956 1957```ts 1958import { drm } from '@kit.DrmKit'; 1959 1960let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1961let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1962mediaKeySession.off('expirationUpdate'); 1963``` 1964 1965### on('keysChange') 1966 1967on(type: 'keysChange', callback: (keyInfo: KeysInfo[], newKeyAvailable: boolean) => void): void 1968 1969Subscribes to events indicating that a media key changes. 1970 1971**Atomic service API**: This API can be used in atomic services since API version 12. 1972 1973**System capability**: SystemCapability.Multimedia.Drm.Core 1974 1975**Parameters** 1976 1977| Name | Type | Mandatory| Description | 1978| -------- | -------------------- | ---- | ------------------------------------- | 1979| type | string | Yes | Event type. The value is fixed at **'keysChange'**. This event is triggered when a media key changes.| 1980| callback | Callback\<[KeysInfo[]](#keysinfo), boolean\> | Yes | Callback used to return the event information, including the lists of key IDs, statuses, and availability. | 1981 1982**Error codes** 1983 1984For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 1985 1986| ID | Error Message | 1987| --------------- | --------------- | 1988| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 1989| 24700101 | All unknown errors | 1990 1991**Example** 1992 1993```ts 1994import { drm } from '@kit.DrmKit'; 1995 1996let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 1997let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 1998mediaKeySession.on('keysChange', (keyInfo: drm.KeysInfo[], newKeyAvailable: boolean) => { 1999 for (let i = 0; i < keyInfo.length; i++) { 2000 console.log('keysChange' + 'keyId:' + keyInfo[i].keyId + ' data:' + keyInfo[i].value); 2001 } 2002}); 2003``` 2004 2005### off('keysChange') 2006 2007off(type: 'keysChange', callback?: (keyInfo: KeysInfo[], newKeyAvailable: boolean) => void): void 2008 2009Unsubscribes from events indicating that a media key changes. 2010 2011**Atomic service API**: This API can be used in atomic services since API version 12. 2012 2013**System capability**: SystemCapability.Multimedia.Drm.Core 2014 2015**Parameters** 2016 2017| Name | Type | Mandatory| Description | 2018| -------- | -------------------- | ---- | ------------------------------------- | 2019| type | string | Yes | Event type. The value is fixed at **'keysChange'**.| 2020| callback | Callback\<[KeysInfo[]](#keysinfo), boolean\> | No | Callback used to return the event information, including the lists of key IDs, statuses, and availability. | 2021 2022**Error codes** 2023 2024For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 2025 2026| ID | Error Message | 2027| --------------- | --------------- | 2028| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified or too many parameters. 2.Incorrect parameter types. 3.Parameter verification failed. | 2029| 24700101 | All unknown errors | 2030 2031**Example** 2032 2033```ts 2034import { drm } from '@kit.DrmKit'; 2035 2036let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 2037let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 2038mediaKeySession.off('keysChange'); 2039``` 2040 2041### destroy 2042 2043destroy(): void 2044 2045Destroys this **MediaKeySession** instance. 2046 2047**Atomic service API**: This API can be used in atomic services since API version 12. 2048 2049**System capability**: SystemCapability.Multimedia.Drm.Core 2050 2051**Error codes** 2052 2053For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 2054 2055| ID | Error Message | 2056| --------------- | --------------- | 2057| 24700101 | All unknown errors | 2058| 24700201 | Fatal service error, for example, service died | 2059 2060**Example** 2061 2062```ts 2063import { drm } from '@kit.DrmKit'; 2064import { BusinessError } from '@kit.BasicServicesKit'; 2065 2066let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 2067let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 2068try { 2069 mediaKeySession.destroy(); 2070} catch (err) { 2071 let error = err as BusinessError; 2072 console.error(`mediaKeySession destroy ERROR: ${error}`); 2073} 2074 2075``` 2076