1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
|
/*
* Copyright (C) 2010 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __IDRM_ENGINE_H__
#define __IDRM_ENGINE_H__
#include <drm/drm_framework_common.h>
namespace android {
class DrmContentIds;
class DrmConstraints;
class DrmRights;
class DrmInfo;
class DrmInfoStatus;
class DrmConvertedStatus;
class DrmInfoRequest;
class DrmSupportInfo;
class DrmInfoEvent;
/**
* This class is an interface for plug-in user
*
* Responsibility of this class is provide generic interface to DRM Engine Manager.
* Each interface need to be as abstract as possible.
*/
class IDrmEngine {
public:
virtual ~IDrmEngine() {
}
public:
class OnInfoListener {
public:
virtual void onInfo(const DrmInfoEvent& event) = 0;
virtual ~OnInfoListener() { }
};
public:
//////////////////////////////////
// Implementation of IDrmEngine //
//////////////////////////////////
/**
* Initialize plug-in
*
* @param[in] uniqueId Unique identifier for a session
* @return status_t
* Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
*/
virtual status_t initialize(int uniqueId) = 0;
/**
* Register a callback to be invoked when the caller required to
* receive necessary information
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] infoListener Listener
* @return status_t
* Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
*/
virtual status_t setOnInfoListener(
int uniqueId, const IDrmEngine::OnInfoListener* infoListener) = 0;
/**
* Terminate the plug-in
* and release resource bound to plug-in
* e.g.) release native resource
*
* @param[in] uniqueId Unique identifier for a session
* @return status_t
* Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
*/
virtual status_t terminate(int uniqueId) = 0;
/**
* Get constraint information associated with input content
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] path Path of the protected content
* @param[in] action Actions defined such as,
* Action::DEFAULT, Action::PLAY, etc
* @return DrmConstraints
* key-value pairs of constraint are embedded in it
* @note
* In case of error, return NULL
*/
virtual DrmConstraints* getConstraints(
int uniqueId, const String8* path, int action) = 0;
/**
* Get whether the given content can be handled by this plugin or not
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] path Path the protected object
* @return bool
* true if this plugin can handle , false in case of not able to handle
*/
virtual bool canHandle(int uniqueId, const String8& path) = 0;
/**
* Executes given drm information based on its type
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] drmInfo Information needs to be processed
* @return DrmInfoStatus
* instance as a result of processing given input
*/
virtual DrmInfoStatus* processDrmInfo(int uniqueId, const DrmInfo* drmInfo) = 0;
/**
* Retrieves necessary information for registration, unregistration or rights
* acquisition information.
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] drmInfoRequest Request information to retrieve drmInfo
* @return DrmInfo
* instance as a result of processing given input
*/
virtual DrmInfo* acquireDrmInfo(int uniqueId, const DrmInfoRequest* drmInfoRequest) = 0;
/**
* Save DRM rights to specified rights path
* and make association with content path
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] drmRights DrmRights to be saved
* @param[in] rightsPath File path where rights to be saved
* @param[in] contentPath File path where content was saved
*/
virtual void saveRights(int uniqueId, const DrmRights& drmRights,
const String8& rightsPath, const String8& contentPath) = 0;
/**
* Retrieves the mime type embedded inside the original content
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] path Path of the protected content
* @return String8
* Returns mime-type of the original content, such as "video/mpeg"
*/
virtual String8 getOriginalMimeType(int uniqueId, const String8& path) = 0;
/**
* Retrieves the type of the protected object (content, rights, etc..)
* using specified path or mimetype. At least one parameter should be non null
* to retrieve DRM object type
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] path Path of the content or null.
* @param[in] mimeType Mime type of the content or null.
* @return type of the DRM content,
* such as DrmObjectType::CONTENT, DrmObjectType::RIGHTS_OBJECT
*/
virtual int getDrmObjectType(
int uniqueId, const String8& path, const String8& mimeType) = 0;
/**
* Check whether the given content has valid rights or not
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] path Path of the protected content
* @param[in] action Action to perform (Action::DEFAULT, Action::PLAY, etc)
* @return the status of the rights for the protected content,
* such as RightsStatus::RIGHTS_VALID, RightsStatus::RIGHTS_EXPIRED, etc.
*/
virtual int checkRightsStatus(int uniqueId, const String8& path, int action) = 0;
/**
* Consumes the rights for a content.
* If the reserve parameter is true the rights is reserved until the same
* application calls this api again with the reserve parameter set to false.
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] decryptHandle Handle for the decryption session
* @param[in] action Action to perform. (Action::DEFAULT, Action::PLAY, etc)
* @param[in] reserve True if the rights should be reserved.
*/
virtual void consumeRights(
int uniqueId, DecryptHandle* decryptHandle, int action, bool reserve) = 0;
/**
* Informs the DRM Engine about the playback actions performed on the DRM files.
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] decryptHandle Handle for the decryption session
* @param[in] playbackStatus Playback action (Playback::START, Playback::STOP, Playback::PAUSE)
* @param[in] position Position in the file (in milliseconds) where the start occurs.
* Only valid together with Playback::START.
*/
virtual void setPlaybackStatus(int uniqueId, DecryptHandle* decryptHandle,
int playbackStatus, int position) = 0;
/**
* Validates whether an action on the DRM content is allowed or not.
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] path Path of the protected content
* @param[in] action Action to validate (Action::PLAY, Action::TRANSFER, etc)
* @param[in] description Detailed description of the action
* @return true if the action is allowed.
*/
virtual bool validateAction(int uniqueId, const String8& path,
int action, const ActionDescription& description) = 0;
/**
* Removes the rights associated with the given protected content
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] path Path of the protected content
*/
virtual void removeRights(int uniqueId, const String8& path) = 0;
/**
* Removes all the rights information of each plug-in associated with
* DRM framework. Will be used in master reset
*
* @param[in] uniqueId Unique identifier for a session
*/
virtual void removeAllRights(int uniqueId) = 0;
/**
* This API is for Forward Lock based DRM scheme.
* Each time the application tries to download a new DRM file
* which needs to be converted, then the application has to
* begin with calling this API.
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] convertId Handle for the convert session
*/
virtual void openConvertSession(int uniqueId, int convertId) = 0;
/**
* Accepts and converts the input data which is part of DRM file.
* The resultant converted data and the status is returned in the DrmConvertedInfo
* object. This method will be called each time there are new block
* of data received by the application.
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] convertId Handle for the convert session
* @param[in] inputData Input Data which need to be converted
* @return Return object contains the status of the data conversion,
* the output converted data and offset. In this case the
* application will ignore the offset information.
*/
virtual DrmConvertedStatus* convertData(
int uniqueId, int convertId, const DrmBuffer* inputData) = 0;
/**
* Informs the Drm Agent when there is no more data which need to be converted
* or when an error occurs. Upon successful conversion of the complete data,
* the agent will inform that where the header and body signature
* should be added. This signature appending is needed to integrity
* protect the converted file.
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] convertId Handle for the convert session
* @return Return object contains the status of the data conversion,
* the header and body signature data. It also informs
* the application on which offset these signature data
* should be appended.
*/
virtual DrmConvertedStatus* closeConvertSession( int uniqueId, int convertId) = 0;
/**
* Returns the information about the Drm Engine capabilities which includes
* supported MimeTypes and file suffixes.
*
* @param[in] uniqueId Unique identifier for a session
* @return DrmSupportInfo
* instance which holds the capabilities of a plug-in
*/
virtual DrmSupportInfo* getSupportInfo(int uniqueId) = 0;
/**
* Open the decrypt session to decrypt the given protected content
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] decryptHandle Handle for the current decryption session
* @param[in] fd File descriptor of the protected content to be decrypted
* @param[in] offset Start position of the content
* @param[in] length The length of the protected content
* @return
* DRM_ERROR_CANNOT_HANDLE for failure and DRM_NO_ERROR for success
*/
virtual status_t openDecryptSession(
int uniqueId, DecryptHandle* decryptHandle, int fd, int offset, int length) = 0;
/**
* Close the decrypt session for the given handle
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] decryptHandle Handle for the decryption session
*/
virtual void closeDecryptSession(int uniqueId, DecryptHandle* decryptHandle) = 0;
/**
* Initialize decryption for the given unit of the protected content
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] decryptHandle Handle for the decryption session
* @param[in] decryptUnitId ID which specifies decryption unit, such as track ID
* @param[in] headerInfo Information for initializing decryption of this decrypUnit
*/
virtual void initializeDecryptUnit(int uniqueId, DecryptHandle* decryptHandle,
int decryptUnitId, const DrmBuffer* headerInfo) = 0;
/**
* Decrypt the protected content buffers for the given unit
* This method will be called any number of times, based on number of
* encrypted streams received from application.
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] decryptHandle Handle for the decryption session
* @param[in] decryptUnitId ID which specifies decryption unit, such as track ID
* @param[in] encBuffer Encrypted data block
* @param[out] decBuffer Decrypted data block
* @return status_t
* Returns the error code for this API
* DRM_NO_ERROR for success, and one of DRM_ERROR_UNKNOWN, DRM_ERROR_LICENSE_EXPIRED
* DRM_ERROR_SESSION_NOT_OPENED, DRM_ERROR_DECRYPT_UNIT_NOT_INITIALIZED,
* DRM_ERROR_DECRYPT for failure.
*/
virtual status_t decrypt(int uniqueId, DecryptHandle* decryptHandle,
int decryptUnitId, const DrmBuffer* encBuffer, DrmBuffer** decBuffer) = 0;
/**
* Finalize decryption for the given unit of the protected content
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] decryptHandle Handle for the decryption session
* @param[in] decryptUnitId ID which specifies decryption unit, such as track ID
*/
virtual void finalizeDecryptUnit(
int uniqueId, DecryptHandle* decryptHandle, int decryptUnitId) = 0;
/**
* Reads the specified number of bytes from an open DRM file.
*
* @param[in] uniqueId Unique identifier for a session
* @param[in] decryptHandle Handle for the decryption session
* @param[out] buffer Reference to the buffer that should receive the read data.
* @param[in] numBytes Number of bytes to read.
* @param[in] offset Offset with which to update the file position.
*
* @return Number of bytes read. Returns -1 for Failure.
*/
virtual ssize_t pread(int uniqueId, DecryptHandle* decryptHandle,
void* buffer, ssize_t numBytes, off_t offset) = 0;
};
};
#endif /* __IDRM_ENGINE_H__ */
|