1# DRM Media Key Session Management (ArkTS)
2
3The **MediaKeySystem** class of the DRM module supports media key management and media decryption. **MediaKeySession** instances are created and destroyed by **MediaKeySystem** instances.
4
5## How to Develop
6
7Read [DRM](../../reference/apis-drm-kit/js-apis-drm.md) for the API reference.
8
91. Import the module.
10
11   ```ts
12   import { drm } from '@kit.DrmKit';
13   ```
14
152. Import the **BusinessError** module, which provides the error codes thrown by the APIs of the DRM module.
16
17   ```ts
18   import { BusinessError } from '@kit.BasicServicesKit';
19   ```
20
213. Listen for the session status.
22
23    You can listen for the following events of a **MediaKeySession** instance: key request events, key expiry events, vendor-defined events, key update on expiry events, and key change events.
24
25    - Listen for key request events, which are triggered when a media key is requested.
26
27       ```ts
28       mediaKeySession.on('keyRequired', (eventInfo: drm.EventInfo) => {
29         console.log('keyRequired' + 'info:' + eventInfo.info + ' extraInfo:' + eventInfo.extraInfo);
30       });
31       ```
32
33    - Listen for key expiry events, which are triggered when a media key expires.
34
35       ```ts
36       mediaKeySession.on('keyExpired', (eventInfo: drm.EventInfo) => {
37          console.log('keyExpired' + 'info:' + eventInfo.info + ' extraInfo:' + eventInfo.extraInfo);
38       });
39       ```
40
41    - Listen for vendor-defined events, which are triggered when a custom event of the DRM scheme occurs.
42
43       ```ts
44       mediaKeySession.on('vendorDefined', (eventInfo: drm.EventInfo) => {
45         console.log('vendorDefined' + 'info:' + eventInfo.info + ' extraInfo:' + eventInfo.extraInfo);
46       });
47       ```
48
49    - Listen for key update on expiry events, which are triggered when a media key updates upon expiry.
50
51       ```ts
52       mediaKeySession.on('expirationUpdate', (eventInfo: drm.EventInfo) => {
53         console.log('expirationUpdate' + 'info:' + eventInfo.info + ' extraInfo:' + eventInfo.extraInfo);
54       });
55       ```
56
57    - Listen for key change events, which are triggered when a media key is changed.
58
59       ```ts
60       mediaKeySession.on('keysChange', (keyInfo : drm.KeysInfo[], newKeyAvailable:boolean) => {
61         for(let i = 0; i < keyInfo.length; i++){
62           console.log('keysChange' + 'info:' + keyInfo[i].keyId + ' extraInfo:' + keyInfo[i].value);
63         }
64       });
65       ```
66
674. Generate a media key request and process its response.
68
69   ```ts
70   let initData = new Uint8Array([0x00, 0x00, 0x00, 0x00]);
71   // Set optional data based on the DRM scheme.
72   let optionalData:drm.OptionsData[] = [{
73     name: "...",
74     value: "..."
75   }];
76   // The following example shows how to set an online media key request and response.
77   mediaKeySession.generateMediaKeyRequest("video/avc", initData, drm.MediaKeyType.MEDIA_KEY_TYPE_ONLINE, optionalData).then(async (licenseRequest) => {
78      console.info("generateMediaKeyRequest success", licenseRequest.mediaKeyRequestType, licenseRequest.data, licenseRequest.defaultURL);
79      // Send licenseRequest.data returned by the media key request to the DRM service through a network request to obtain a response and process the response.
80      let licenseResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]);
81      mediaKeySession.processMediaKeyResponse(licenseResponse).then((mediaKeyId: Uint8Array) => {
82        console.info("processMediaKeyResponse success");
83      }).catch((err:BusinessError) =>{
84        console.info("processMediaKeyResponse err end", err.code);
85     });
86   }).catch((err:BusinessError) =>{
87     console.info("generateMediaKeyRequest err end", err.code);
88   });
89   // The following example shows how to set an offline media key request and response.
90   let offlineMediaKeyId = new Uint8Array([0x00, 0x00, 0x00, 0x00]);
91   mediaKeySession.generateMediaKeyRequest("video/avc", initData, drm.MediaKeyType.MEDIA_KEY_TYPE_OFFLINE, optionalData).then((licenseRequest: drm.MediaKeyRequest) => {
92      console.info("generateMediaKeyRequest success", licenseRequest.mediaKeyRequestType, licenseRequest.data, licenseRequest.defaultURL);
93      // Send licenseRequest.data returned by the media key request to the DRM service through a network request to obtain a response and process the response.
94      let licenseResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]);
95      mediaKeySession.processMediaKeyResponse(licenseResponse).then((mediaKeyId: Uint8Array) => {
96	offlineMediaKeyId = mediaKeyId;
97        console.info("processMediaKeyResponse success");
98      }).catch((err:BusinessError) =>{
99        console.info("processMediaKeyResponse err end", err.code);
100     });
101   }).catch((err:BusinessError) =>{
102     console.info("generateMediaKeyRequest err end", err.code);
103   });
104   ```
105
1065. (Optional) Check the media key status of the media key session.
107
108    ```ts
109    try {
110      let keyvalue: drm.MediaKeyStatus[] = mediaKeySession.checkMediaKeyStatus();
111      console.info("checkMediaKeyStatus success", keyvalue[0].value);
112    } catch (err) {
113      let error = err as BusinessError;
114      console.error(`checkMediaKeyStatus ERROR: ${error}`);
115    }
116    ```
117
1186. (Optional) Generate an offline media key release request and process its response.
119
120   ```ts
121   mediaKeySession.generateOfflineReleaseRequest(offlineMediaKeyId).then((OfflineReleaseRequest: Uint8Array) => {
122     console.info("generateOfflineReleaseRequest success", OfflineReleaseRequest);
123     // Send OfflineReleaseRequest returned by the offline media key release request to the DRM service through a network request to obtain a response and process the response.
124     let OfflineReleaseResponse = new Uint8Array([0x00, 0x00, 0x00, 0x00]);
125     mediaKeySession.processOfflineReleaseResponse(offlineMediaKeyId, OfflineReleaseResponse).then(() => {
126       console.info("processOfflineReleaseResponse success");
127     }).catch((err:BusinessError) =>{
128       console.info("processOfflineReleaseResponse err end", err.code);
129     });
130   }).catch((err:BusinessError) =>{
131     console.info("generateOfflineReleaseRequest err end", err.code);
132   });
133   ```
134
1357. (Optional) Restore offline media keys.
136
137   ```ts
138   // Restore the specified media key information to the media key session.
139   mediaKeySession.restoreOfflineMediaKeys(offlineMediaKeyId).then(() => {
140     console.log("restoreOfflineMediaKeys success.");
141   }).catch((err: BusinessError) => {
142     console.error(`restoreOfflineMediaKeys: ERROR: ${err}`);
143   });
144   ```
145
1468. (Optional) Obtain the content protection level of the media key session.
147
148    ```ts
149    try {
150      let contentProtectionLevel: drm.ContentProtectionLevel = mediaKeySession.getContentProtectionLevel();
151    } catch (err) {
152      let error = err as BusinessError;
153      console.error(`getContentProtectionLevel ERROR: ${error}`);
154    }
155   ```
156
1579. (Optional) Check whether secure decoding is required.
158
159    ```ts
160    try {
161      let status: boolean = mediaKeySession.requireSecureDecoderModule("video/avc");
162    } catch (err) {
163      let error = err as BusinessError;
164      console.error(`requireSecureDecoderModule ERROR: ${error}`);
165    }
166    ```
167
16810. (Optional) Clear the media keys of the media key session.
169
170    ```ts
171    try {
172       mediaKeySession.clearMediaKeys();
173    } catch (err) {
174      let error = err as BusinessError;
175      console.error(`clearMediaKeys ERROR: ${error}`);
176    }
177    ```
178