1# Interface (MediaKeySession) 2 3> **NOTE** 4> 5> 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. 6 7MediaKeySession implements media key management. Before calling any API in MediaKeySession, you must use [createMediaKeySession](arkts-apis-drm-MediaKeySystem.md#createmediakeysession) to create a MediaKeySession instance. 8 9## Modules to Import 10 11```ts 12import { drm } from '@kit.DrmKit'; 13``` 14 15## generateMediaKeyRequest 16 17generateMediaKeyRequest(mimeType: string, initData: Uint8Array, mediaKeyType: number, options?: OptionsData[]): Promise<MediaKeyRequest\> 18 19Generates a media key request. 20 21**Atomic service API**: This API can be used in atomic services since API version 12. 22 23**System capability**: SystemCapability.Multimedia.Drm.Core 24 25**Parameters** 26 27| Name | Type | Mandatory| Description | 28| -------- | ----------------------------------------------- | ---- | ---------------------------- | 29| mimeType | string | Yes | MIME type, which is determined by the DRM solution. | 30| initData | Uint8Array | Yes | Initial data. | 31| mediaKeyType| number | Yes | Type of the media key. The value **0** means an online media key, and **1** means an offline media key.| 32| options | [OptionsData[]](arkts-apis-drm-i.md#optionsdata) | No | Optional data. | 33 34**Return value** 35 36| Type | Description | 37| ----------------------------------------------- | ---------------------------- | 38| Promise<[MediaKeyRequest](arkts-apis-drm-i.md#mediakeyrequest)\> | Promise used to return the media key request generated. | 39 40**Error codes** 41 42For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 43 44| ID | Error Message | 45| --------------- | --------------- | 46| 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. | 47| 24700101 | All unknown errors | 48| 24700201 | Fatal service error, for example, service died | 49 50**Example** 51 52```ts 53import { drm } from '@kit.DrmKit'; 54import { BusinessError } from '@kit.BasicServicesKit'; 55 56let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 57let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 58// 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. 59let uint8pssh = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 60mediaKeySession.generateMediaKeyRequest("video/avc", uint8pssh, drm.MediaKeyType.MEDIA_KEY_TYPE_ONLINE).then((mediaKeyRequest: drm.MediaKeyRequest) =>{ 61 console.log('generateMediaKeyRequest' + mediaKeyRequest); 62}).catch((err: BusinessError) => { 63 console.error(`generateMediaKeyRequest: ERROR: ${err}`); 64}); 65``` 66 67## processMediaKeyResponse 68 69processMediaKeyResponse(response: Uint8Array): Promise<Uint8Array\> 70 71Processes a media key response. 72 73**Atomic service API**: This API can be used in atomic services since API version 12. 74 75**System capability**: SystemCapability.Multimedia.Drm.Core 76 77**Parameters** 78 79| Name | Type | Mandatory| Description | 80| -------- | ----------------------------------------------- | ---- | ---------------------------- | 81| response | Uint8Array | Yes | Media key response. | 82 83**Return value** 84 85| Type | Description | 86| ----------------------------------------------- | ---------------------------- | 87| Promise<Uint8Array\> | Promise used to return the media key IDs. | 88 89**Error codes** 90 91For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 92 93| ID | Error Message | 94| --------------- | --------------- | 95| 401 | The parameter check failed. Possibly because: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 96| 24700101 | All unknown errors | 97| 24700201 | Fatal service error, for example, service died | 98 99**Example** 100 101```ts 102import { drm } from '@kit.DrmKit'; 103import { BusinessError } from '@kit.BasicServicesKit'; 104 105let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 106let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 107// mediaKeyResponse is obtained from the DRM service. Pass in the actual value obtained. 108let mediaKeyResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 109mediaKeySession.processMediaKeyResponse(mediaKeyResponse).then((mediaKeyId: Uint8Array) => { 110 console.log('processMediaKeyResponse:' + mediaKeyId); 111}).catch((err: BusinessError) => { 112 console.error(`processMediaKeyResponse: ERROR: ${err}`); 113}); 114``` 115 116## checkMediaKeyStatus 117 118 checkMediaKeyStatus(): MediaKeyStatus[] 119 120Checks the status of the media keys in use. 121 122**Atomic service API**: This API can be used in atomic services since API version 12. 123 124**System capability**: SystemCapability.Multimedia.Drm.Core 125 126**Return value** 127 128| Type | Description | 129| ----------------------------------------------- | ---------------------------- | 130| [MediaKeyStatus[]](arkts-apis-drm-i.md#mediakeystatus) | Media key status. | 131 132**Error codes** 133 134For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 135 136| ID | Error Message | 137| --------------- | --------------- | 138| 24700101 | All unknown errors | 139| 24700201 | Fatal service error, for example, service died | 140 141**Example** 142 143```ts 144import { drm } from '@kit.DrmKit'; 145import { BusinessError } from '@kit.BasicServicesKit'; 146 147let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 148let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 149try { 150 let keyStatus: drm.MediaKeyStatus[] = mediaKeySession.checkMediaKeyStatus(); 151} catch (err) { 152 let error = err as BusinessError; 153 console.error(`checkMediaKeyStatus ERROR: ${error}`); 154} 155``` 156 157## clearMediaKeys 158 159clearMediaKeys(): void 160 161Clears the media keys in use. 162 163**Atomic service API**: This API can be used in atomic services since API version 12. 164 165**System capability**: SystemCapability.Multimedia.Drm.Core 166 167**Error codes** 168 169For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 170 171| ID | Error Message | 172| --------------- | --------------- | 173| 24700101 | All unknown errors | 174| 24700201 | Fatal service error, for example, service died | 175 176**Example** 177 178```ts 179import { drm } from '@kit.DrmKit'; 180import { BusinessError } from '@kit.BasicServicesKit'; 181 182let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 183let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 184// mediaKeyResponse is obtained from the DRM service. Pass in the actual value obtained. 185let mediaKeyResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 186mediaKeySession.processMediaKeyResponse(mediaKeyResponse).then((mediaKeyId: Uint8Array) => { 187 console.log('processMediaKeyResponse:' + mediaKeyId); 188}).catch((err: BusinessError) => { 189 console.error(`processMediaKeyResponse: ERROR: ${err}`); 190}); 191try { 192 mediaKeySession.clearMediaKeys(); 193} catch (err) { 194 let error = err as BusinessError; 195 console.error(`clearMediaKeys ERROR: ${error}`); 196} 197``` 198 199## generateOfflineReleaseRequest 200 201generateOfflineReleaseRequest(mediaKeyId: Uint8Array): Promise<Uint8Array\> 202 203Generates a request to release offline media keys. 204 205**Atomic service API**: This API can be used in atomic services since API version 12. 206 207**System capability**: SystemCapability.Multimedia.Drm.Core 208 209**Parameters** 210 211| Name | Type | Mandatory| Description | 212| -------- | ----------------------------------------------- | ---- | ---------------------------- | 213| mediaKeyId | Uint8Array | Yes | Array holding the IDs of offline media keys. | 214 215**Return value** 216 217| Type | Description | 218| ----------------------------------------------- | ---------------------------- | 219| Promise<Uint8Array\> | Promise used to return the request generated if the DRM solution on the device supports offline media key release. | 220 221**Error codes** 222 223For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 224 225| ID | Error Message | 226| --------------- | --------------- | 227| 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. | 228| 24700101 | All unknown errors | 229| 24700201 | Fatal service error, for example, service died | 230 231**Example** 232 233```ts 234import { drm } from '@kit.DrmKit'; 235import { BusinessError } from '@kit.BasicServicesKit'; 236 237let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 238let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 239// mediaKeyId is the return value of processMediaKeyResponse or getOfflineMediaKeyIds. Pass in the actual data returned. 240let mediaKeyId = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 241mediaKeySession.generateOfflineReleaseRequest(mediaKeyId).then((offlineReleaseRequest: Uint8Array) => { 242 console.log('generateOfflineReleaseRequest:' + offlineReleaseRequest); 243}).catch((err: BusinessError) => { 244 console.error(`generateOfflineReleaseRequest: ERROR: ${err}`); 245}); 246``` 247 248## processOfflineReleaseResponse 249 250processOfflineReleaseResponse(mediaKeyId: Uint8Array, response: Uint8Array): Promise<void\> 251 252Processes a response to a request for releasing offline media keys. 253 254**Atomic service API**: This API can be used in atomic services since API version 12. 255 256**System capability**: SystemCapability.Multimedia.Drm.Core 257 258**Parameters** 259 260| Name | Type | Mandatory| Description | 261| -------- | ----------------------------------------------- | ---- | ---------------------------- | 262| mediaKeyId | Uint8Array | Yes | Array holding the IDs of offline media keys. | 263| response | Uint8Array | Yes | Response to the request for releasing offline media keys. | 264 265**Return value** 266 267| Type | Description | 268| ----------------------------------------------- | ---------------------------- | 269| Promise<void\> | Promise used to return the result if the DRM solution on the device supports offline media key release. | 270 271**Error codes** 272 273For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 274 275| ID | Error Message | 276| --------------- | --------------- | 277| 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. | 278| 24700101 | All unknown errors | 279| 24700201 | Fatal service error, for example, service died | 280 281**Example** 282 283```ts 284import { drm } from '@kit.DrmKit'; 285import { BusinessError } from '@kit.BasicServicesKit'; 286 287let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 288let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 289// mediaKeyId is the return value of processMediaKeyResponse or getOfflineMediaKeyIds. Apply for memory based on the actual length. 290let mediaKeyId = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 291mediaKeySession.generateOfflineReleaseRequest(mediaKeyId).then((offlineReleaseRequest: Uint8Array) => { 292 console.log('generateOfflineReleaseRequest:' + offlineReleaseRequest); 293}).catch((err: BusinessError) => { 294 console.error(`generateOfflineReleaseRequest: ERROR: ${err}`); 295}); 296// offlineReleaseResponse is obtained from the DRM service. Apply for memory based on the actual length. 297let offlineReleaseResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 298mediaKeySession.processOfflineReleaseResponse(mediaKeyId, offlineReleaseResponse).then(() => { 299 console.log('processOfflineReleaseResponse'); 300}).catch((err: BusinessError) => { 301 console.error(`processOfflineReleaseResponse: ERROR: ${err}`); 302}); 303``` 304 305## restoreOfflineMediaKeys 306 307restoreOfflineMediaKeys(mediaKeyId: Uint8Array): Promise<void\> 308 309Restores offline media keys. 310 311**Atomic service API**: This API can be used in atomic services since API version 12. 312 313**System capability**: SystemCapability.Multimedia.Drm.Core 314 315**Parameters** 316 317| Name | Type | Mandatory| Description | 318| -------- | ----------------------------------------------- | ---- | ---------------------------- | 319| mediaKeyId | Uint8Array | Yes | Array holding the IDs of offline media keys. | 320 321**Return value** 322 323| Type | Description | 324| ----------------------------------------------- | ---------------------------- | 325| Promise<void\> | Promise | 326 327**Error codes** 328 329For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 330 331| ID | Error Message | 332| --------------- | --------------- | 333| 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. | 334| 24700101 | All unknown errors | 335| 24700201 | Fatal service error, for example, service died | 336 337**Example** 338 339```ts 340import { drm } from '@kit.DrmKit'; 341import { BusinessError } from '@kit.BasicServicesKit'; 342 343let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 344let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 345// mediaKeyId is the return value of processMediaKeyResponse or getOfflineMediaKeyIds. Pass in the actual data returned. 346let mediaKeyId = new Uint8Array([0x00, 0x00, 0x00, 0x00]); 347mediaKeySession.restoreOfflineMediaKeys(mediaKeyId).then(() => { 348 console.log("restoreOfflineMediaKeys"); 349}).catch((err: BusinessError) => { 350 console.error(`restoreOfflineMediaKeys: ERROR: ${err}`); 351}); 352``` 353 354## getContentProtectionLevel 355 356getContentProtectionLevel(): ContentProtectionLevel 357 358Obtains the content protection level of this media key session. 359 360**Atomic service API**: This API can be used in atomic services since API version 12. 361 362**System capability**: SystemCapability.Multimedia.Drm.Core 363 364**Return value** 365 366| Type | Description | 367| ----------------------------------------------- | ---------------------------- | 368| [ContentProtectionLevel](arkts-apis-drm-e.md#contentprotectionlevel) | Content protection level. | 369 370**Error codes** 371 372For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 373 374| ID | Error Message | 375| --------------- | --------------- | 376| 24700101 | All unknown errors | 377| 24700201 | Fatal service error, for example, service died | 378 379**Example** 380 381```ts 382import { drm } from '@kit.DrmKit'; 383import { BusinessError } from '@kit.BasicServicesKit'; 384 385let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 386let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 387try { 388 let contentProtectionLevel: drm.ContentProtectionLevel = mediaKeySession.getContentProtectionLevel(); 389} catch (err) { 390 let error = err as BusinessError; 391 console.error(`getContentProtectionLevel ERROR: ${error}`); 392} 393``` 394 395## requireSecureDecoderModule 396 397requireSecureDecoderModule(mimeType: string): boolean 398 399Checks whether secure decoding is required. 400 401**Atomic service API**: This API can be used in atomic services since API version 12. 402 403**System capability**: SystemCapability.Multimedia.Drm.Core 404 405**Parameters** 406 407| Name | Type | Mandatory| Description | 408| -------- | ----------------------------------------------- | ---- | ---------------------------- | 409| mimeType | string | Yes | MIME type, which is determined by the DRM solution. | 410 411**Return value** 412 413| Type | Description | 414| ----------------------------------------------- | ---------------------------- | 415| boolean | Whether secure decoding is required. **true** if required, **false** otherwise. | 416 417**Error codes** 418 419For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 420 421| ID | Error Message | 422| --------------- | --------------- | 423| 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. | 424| 24700101 | All unknown errors | 425| 24700201 | Fatal service error, for example, service died | 426 427**Example** 428 429```ts 430import { drm } from '@kit.DrmKit'; 431import { BusinessError } from '@kit.BasicServicesKit'; 432 433let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 434let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 435try { 436 let status: boolean = mediaKeySession.requireSecureDecoderModule("video/avc"); 437} catch (err) { 438 let error = err as BusinessError; 439 console.error(`requireSecureDecoderModule ERROR: ${error}`); 440} 441``` 442 443## on('keyRequired') 444 445on(type: 'keyRequired', callback: (eventInfo: EventInfo) => void): void 446 447Subscribes to events indicating that the application requests a media key. 448 449**Atomic service API**: This API can be used in atomic services since API version 12. 450 451**System capability**: SystemCapability.Multimedia.Drm.Core 452 453**Parameters** 454 455| Name | Type | Mandatory| Description | 456| -------- | -------------------- | ---- | ------------------------------------- | 457| type | string | Yes | Event type. The value is fixed at **'keyRequired'**. This event is triggered when the application requires a media key.| 458| callback | (eventInfo: \<[EventInfo](arkts-apis-drm-i.md#eventinfo)\>) => void | Yes | Callback used to return the event information. | 459 460**Error codes** 461 462For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 463 464| ID | Error Message | 465| --------------- | --------------- | 466| 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. | 467| 24700101 | All unknown errors | 468 469**Example** 470 471```ts 472import { drm } from '@kit.DrmKit'; 473 474let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 475let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 476mediaKeySession.on('keyRequired', (eventInfo: drm.EventInfo) => { 477 console.log('keyRequired ' + 'extra: ' + eventInfo.extraInfo + 'data: ' + eventInfo.info); 478}); 479``` 480 481## off('keyRequired') 482 483off(type: 'keyRequired', callback?: (eventInfo: EventInfo) => void): void 484 485Unsubscribes from events indicating that the application requests a media key. 486 487**Atomic service API**: This API can be used in atomic services since API version 12. 488 489**System capability**: SystemCapability.Multimedia.Drm.Core 490 491**Parameters** 492 493| Name | Type | Mandatory| Description | 494| -------- | -------------------- | ---- | ------------------------------------- | 495| type | string | Yes | Event type. The value is fixed at **'keyRequired'**.| 496| callback | (eventInfo: \<[EventInfo](arkts-apis-drm-i.md#eventinfo)\>) => void | No | Callback used to return the event information. | 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| 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. | 505| 24700101 | All unknown errors | 506 507**Example** 508 509```ts 510import { drm } from '@kit.DrmKit'; 511 512let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 513let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 514mediaKeySession.off('keyRequired'); 515``` 516 517## on('keyExpired') 518 519on(type: 'keyExpired', callback: (eventInfo: EventInfo) => void): void 520 521Subscribes to events indicating that a media key expires. 522 523**Atomic service API**: This API can be used in atomic services since API version 12. 524 525**System capability**: SystemCapability.Multimedia.Drm.Core 526 527**Parameters** 528 529| Name | Type | Mandatory| Description | 530| -------- | -------------------- | ---- | ------------------------------------- | 531| type | string | Yes | Event type. The value is fixed at **'keyExpired'**. This event is triggered when a media key expires.| 532| callback | (eventInfo: \<[EventInfo](arkts-apis-drm-i.md#eventinfo)\>) => void | Yes | Callback used to return the event information. | 533 534**Error codes** 535 536For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 537 538| ID | Error Message | 539| --------------- | --------------- | 540| 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. | 541| 24700101 | All unknown errors | 542 543**Example** 544 545```ts 546import { drm } from '@kit.DrmKit'; 547 548let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 549let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 550mediaKeySession.on('keyExpired', (eventInfo: drm.EventInfo) => { 551 console.log('keyExpired ' + 'extra: ' + eventInfo.extraInfo + 'data: ' + eventInfo.info); 552}); 553``` 554 555## off('keyExpired') 556 557off(type: 'keyExpired', callback?: (eventInfo: EventInfo) => void): void 558 559Unsubscribes from events indicating that a media key expires. 560 561**Atomic service API**: This API can be used in atomic services since API version 12. 562 563**System capability**: SystemCapability.Multimedia.Drm.Core 564 565**Parameters** 566 567| Name | Type | Mandatory| Description | 568| -------- | -------------------- | ---- | ------------------------------------- | 569| type | string | Yes | Event type. The value is fixed at **'keyExpired'**.| 570| callback | (eventInfo: \<[EventInfo](arkts-apis-drm-i.md#eventinfo)\>) => void | No | Callback used to return the event information. | 571 572**Error codes** 573 574For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 575 576| ID | Error Message | 577| --------------- | --------------- | 578| 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. | 579| 24700101 | All unknown errors | 580 581**Example** 582 583```ts 584import { drm } from '@kit.DrmKit'; 585 586let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 587let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 588mediaKeySession.off('keyExpired'); 589``` 590 591## on('vendorDefined') 592 593on(type: 'vendorDefined', callback: (eventInfo: EventInfo) => void): void 594 595Subscribes to vendor-defined events. 596 597**Atomic service API**: This API can be used in atomic services since API version 12. 598 599**System capability**: SystemCapability.Multimedia.Drm.Core 600 601**Parameters** 602 603| Name | Type | Mandatory| Description | 604| -------- | -------------------- | ---- | ------------------------------------- | 605| type | string | Yes | Event type. The value is fixed at **'vendorDefined'**. This event is triggered when a vendor-defined event occurs.| 606| callback | (eventInfo: \<[EventInfo](arkts-apis-drm-i.md#eventinfo)\>) => void | Yes | Callback used to return the event information. | 607 608**Error codes** 609 610For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 611 612| ID | Error Message | 613| --------------- | --------------- | 614| 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. | 615| 24700101 | All unknown errors | 616 617**Example** 618 619```ts 620import { drm } from '@kit.DrmKit'; 621 622let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 623let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 624mediaKeySession.on('vendorDefined', (eventInfo: drm.EventInfo) => { 625 console.log('vendorDefined ' + 'extra: ' + eventInfo.extraInfo + 'data: ' + eventInfo.info); 626}); 627``` 628 629## off('vendorDefined') 630 631off(type: 'vendorDefined', callback?: (eventInfo: EventInfo) => void): void 632 633Unsubscribes from vendor-defined events. 634 635**Atomic service API**: This API can be used in atomic services since API version 12. 636 637**System capability**: SystemCapability.Multimedia.Drm.Core 638 639**Parameters** 640 641| Name | Type | Mandatory| Description | 642| -------- | -------------------- | ---- | ------------------------------------- | 643| type | string | Yes | Event type. The value is fixed at **'vendorDefined'**.| 644| callback | (eventInfo: \<[EventInfo](arkts-apis-drm-i.md#eventinfo)\>) => void | No | Callback used to return the event information. | 645 646**Error codes** 647 648For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 649 650| ID | Error Message | 651| --------------- | --------------- | 652| 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. | 653| 24700101 | All unknown errors | 654 655**Example** 656 657```ts 658import { drm } from '@kit.DrmKit'; 659 660let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 661let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 662mediaKeySession.off('vendorDefined'); 663``` 664 665## on('expirationUpdate') 666 667on(type: 'expirationUpdate', callback: (eventInfo: EventInfo) => void): void 668 669Subscribes to events indicating that a media key updates on expiry. 670 671**Atomic service API**: This API can be used in atomic services since API version 12. 672 673**System capability**: SystemCapability.Multimedia.Drm.Core 674 675**Parameters** 676 677| Name | Type | Mandatory| Description | 678| -------- | -------------------- | ---- | ------------------------------------- | 679| type | string | Yes | Event type. The value is fixed at **'expirationUpdate'**. This event is triggered when a media key updates on expiry.| 680| callback | (eventInfo: \<[EventInfo](arkts-apis-drm-i.md#eventinfo)\>) => void | Yes | Callback used to return the event information. | 681 682**Error codes** 683 684For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 685 686| ID | Error Message | 687| --------------- | --------------- | 688| 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. | 689| 24700101 | All unknown errors | 690 691**Example** 692 693```ts 694import { drm } from '@kit.DrmKit'; 695 696let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 697let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 698mediaKeySession.on('expirationUpdate', (eventInfo: drm.EventInfo) => { 699 console.log('expirationUpdate ' + 'extra: ' + eventInfo.extraInfo + 'data: ' + eventInfo.info); 700}); 701``` 702 703## off('expirationUpdate') 704 705off(type: 'expirationUpdate', callback?: (eventInfo: EventInfo) => void): void 706 707Unsubscribes from events indicating that a media key updates on expiry. 708 709**Atomic service API**: This API can be used in atomic services since API version 12. 710 711**System capability**: SystemCapability.Multimedia.Drm.Core 712 713**Parameters** 714 715| Name | Type | Mandatory| Description | 716| -------- | -------------------- | ---- | ------------------------------------- | 717| type | string | Yes | Event type. The value is fixed at **'expirationUpdate'**.| 718| callback | (eventInfo: \<[EventInfo](arkts-apis-drm-i.md#eventinfo)\>) => void | No | Callback used to return the event 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| 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. | 727| 24700101 | All unknown errors | 728 729**Example** 730 731```ts 732import { drm } from '@kit.DrmKit'; 733 734let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 735let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 736mediaKeySession.off('expirationUpdate'); 737``` 738 739## on('keysChange') 740 741on(type: 'keysChange', callback: (keyInfo: KeysInfo[], newKeyAvailable: boolean) => void): void 742 743Subscribes to events indicating that a media key changes. 744 745**Atomic service API**: This API can be used in atomic services since API version 12. 746 747**System capability**: SystemCapability.Multimedia.Drm.Core 748 749**Parameters** 750 751| Name | Type | Mandatory| Description | 752| -------- | -------------------- | ---- | ------------------------------------- | 753| type | string | Yes | Event type. The value is fixed at **'keysChange'**. This event is triggered when a media key changes.| 754| callback | (keyInfo: [KeysInfo[]](arkts-apis-drm-i.md#keysinfo), newKeyAvailable: boolean) | Yes | Callback used to return the event information, including the lists of key IDs, statuses, and availability. | 755 756**Error codes** 757 758For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 759 760| ID | Error Message | 761| --------------- | --------------- | 762| 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. | 763| 24700101 | All unknown errors | 764 765**Example** 766 767```ts 768import { drm } from '@kit.DrmKit'; 769 770let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 771let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 772mediaKeySession.on('keysChange', (keyInfo: drm.KeysInfo[], newKeyAvailable: boolean) => { 773 for (let i = 0; i < keyInfo.length; i++) { 774 console.log('keysChange' + 'keyId:' + keyInfo[i].keyId + ' data:' + keyInfo[i].value); 775 } 776}); 777``` 778 779## off('keysChange') 780 781off(type: 'keysChange', callback?: (keyInfo: KeysInfo[], newKeyAvailable: boolean) => void): void 782 783Unsubscribes from events indicating that a media key changes. 784 785**Atomic service API**: This API can be used in atomic services since API version 12. 786 787**System capability**: SystemCapability.Multimedia.Drm.Core 788 789**Parameters** 790 791| Name | Type | Mandatory| Description | 792| -------- | -------------------- | ---- | ------------------------------------- | 793| type | string | Yes | Event type. The value is fixed at **'keysChange'**.| 794| callback | (keyInfo: [KeysInfo[]](arkts-apis-drm-i.md#keysinfo), newKeyAvailable: boolean) | No | Callback used to return the event information, including the lists of key IDs, statuses, and availability. | 795 796**Error codes** 797 798For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 799 800| ID | Error Message | 801| --------------- | --------------- | 802| 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. | 803| 24700101 | All unknown errors | 804 805**Example** 806 807```ts 808import { drm } from '@kit.DrmKit'; 809 810let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 811let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 812mediaKeySession.off('keysChange'); 813``` 814 815## destroy 816 817destroy(): void 818 819Destroys this MediaKeySession instance. 820 821**Atomic service API**: This API can be used in atomic services since API version 12. 822 823**System capability**: SystemCapability.Multimedia.Drm.Core 824 825**Error codes** 826 827For details about the error codes, see [DRM Error Codes](errorcode-drm.md). 828 829| ID | Error Message | 830| --------------- | --------------- | 831| 24700101 | All unknown errors | 832| 24700201 | Fatal service error, for example, service died | 833 834**Example** 835 836```ts 837import { drm } from '@kit.DrmKit'; 838import { BusinessError } from '@kit.BasicServicesKit'; 839 840let mediaKeySystem: drm.MediaKeySystem = drm.createMediaKeySystem("com.clearplay.drm"); 841let mediaKeySession: drm.MediaKeySession = mediaKeySystem.createMediaKeySession(); 842try { 843 mediaKeySession.destroy(); 844} catch (err) { 845 let error = err as BusinessError; 846 console.error(`mediaKeySession destroy ERROR: ${error}`); 847} 848 849``` 850