FwdLockEngine.h revision bd2f13ddbe7a9e7550205f6b53880329e09b9457 
1/*
2 * Copyright (C) 2010 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef __FWDLOCKENGINE_H__
18#define __FWDLOCKENGINE_H__
19
20#include <DrmEngineBase.h>
21#include <DrmConstraints.h>
22#include <DrmRights.h>
23#include <DrmInfo.h>
24#include <DrmInfoStatus.h>
25#include <DrmConvertedStatus.h>
26#include <DrmInfoRequest.h>
27#include <DrmSupportInfo.h>
28#include <DrmInfoEvent.h>
29
30#include "SessionMap.h"
31#include "FwdLockConv.h"
32
33namespace android {
34
35/**
36 * Forward Lock Engine class.
37 */
38class FwdLockEngine : public android::DrmEngineBase {
39
40public:
41    FwdLockEngine();
42    virtual ~FwdLockEngine();
43
44protected:
45/**
46 * Get constraint information associated with input content.
47 *
48 * @param uniqueId Unique identifier for a session
49 * @param path Path of the protected content
50 * @param action Actions defined such as,
51 *     Action::DEFAULT, Action::PLAY, etc
52 * @return DrmConstraints
53 *     key-value pairs of constraint are embedded in it
54 * @note
55 *     In case of error, return NULL
56 */
57DrmConstraints* onGetConstraints(int uniqueId, const String8* path, int action);
58
59/**
60 * Get metadata information associated with input content.
61 *
62 * @param uniqueId Unique identifier for a session
63 * @param path Path of the protected content
64 * @return DrmMetadata
65 *      For Forward Lock engine, it returns an empty object
66 * @note
67 *     In case of error, returns NULL
68 */
69DrmMetadata* onGetMetadata(int uniqueId, const String8* path);
70
71/**
72 * Initialize plug-in.
73 *
74 * @param uniqueId Unique identifier for a session
75 * @return status_t
76 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
77 */
78status_t onInitialize(int uniqueId);
79
80/**
81 * Register a callback to be invoked when the caller required to
82 * receive necessary information.
83 *
84 * @param uniqueId Unique identifier for a session
85 * @param infoListener Listener
86 * @return status_t
87 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
88 */
89status_t onSetOnInfoListener(int uniqueId, const IDrmEngine::OnInfoListener* infoListener);
90
91/**
92 * Terminate the plug-in and release resources bound to it.
93 *
94 * @param uniqueId Unique identifier for a session
95 * @return status_t
96 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
97 */
98status_t onTerminate(int uniqueId);
99
100/**
101 * Get whether the given content can be handled by this plugin or not.
102 *
103 * @param uniqueId Unique identifier for a session
104 * @param path Path to the protected object
105 * @return bool
106 *      Returns true if this plugin can handle , false in case of not able to handle
107 */
108bool onCanHandle(int uniqueId, const String8& path);
109
110/**
111 * Processes the given DRM information as appropriate for its type.
112 * Not used for Forward Lock Engine.
113 *
114 * @param uniqueId Unique identifier for a session
115 * @param drmInfo Information that needs to be processed
116 * @return DrmInfoStatus
117 *      instance as a result of processing given input
118 */
119DrmInfoStatus* onProcessDrmInfo(int uniqueId, const DrmInfo* drmInfo);
120
121/**
122 * Save DRM rights to specified rights path
123 * and make association with content path.
124 *
125 * @param uniqueId Unique identifier for a session
126 * @param drmRights DrmRights to be saved
127 * @param rightsPath File path where rights to be saved
128 * @param contentPath File path where content was saved
129 * @return status_t
130 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
131 */
132status_t onSaveRights(int uniqueId,
133                      const DrmRights& drmRights,
134                      const String8& rightsPath,
135                      const String8& contentPath);
136
137/**
138 * Retrieves necessary information for registration, unregistration or rights
139 * acquisition information.
140 *
141 * @param uniqueId Unique identifier for a session
142 * @param drmInfoRequest Request information to retrieve drmInfo
143 * @return DrmInfo
144 *      instance as a result of processing given input
145 */
146DrmInfo* onAcquireDrmInfo(int uniqueId,
147                          const DrmInfoRequest* drmInfoRequest);
148
149/**
150 * Retrieves the mime type embedded inside the original content.
151 *
152 * @param uniqueId Unique identifier for a session
153 * @param path Path of the protected content
154 * @return String8
155 *       Returns mime-type of the original content, such as "video/mpeg"
156 */
157String8 onGetOriginalMimeType(int uniqueId, const String8& path);
158
159/**
160 * Retrieves the type of the protected object (content, rights, etc..)
161 * using specified path or mimetype. At least one parameter should be non null
162 * to retrieve DRM object type.
163 *
164 * @param uniqueId Unique identifier for a session
165 * @param path Path of the content or null.
166 * @param mimeType Mime type of the content or null.
167 * @return type of the DRM content,
168 *     such as DrmObjectType::CONTENT, DrmObjectType::RIGHTS_OBJECT
169 */
170int onGetDrmObjectType(int uniqueId,
171                       const String8& path,
172                       const String8& mimeType);
173
174/**
175 * Check whether the given content has valid rights or not.
176 *
177 * @param uniqueId Unique identifier for a session
178 * @param path Path of the protected content
179 * @param action Action to perform (Action::DEFAULT, Action::PLAY, etc)
180 * @return the status of the rights for the protected content,
181 *     such as RightsStatus::RIGHTS_VALID, RightsStatus::RIGHTS_EXPIRED, etc.
182 */
183int onCheckRightsStatus(int uniqueId,
184                        const String8& path,
185                        int action);
186
187/**
188 * Consumes the rights for a content.
189 * If the reserve parameter is true the rights are reserved until the same
190 * application calls this api again with the reserve parameter set to false.
191 *
192 * @param uniqueId Unique identifier for a session
193 * @param decryptHandle Handle for the decryption session
194 * @param action Action to perform. (Action::DEFAULT, Action::PLAY, etc)
195 * @param reserve True if the rights should be reserved.
196 * @return status_t
197 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
198 */
199status_t onConsumeRights(int uniqueId,
200                         DecryptHandle* decryptHandle,
201                         int action,
202                         bool reserve);
203
204/**
205 * Informs the DRM Engine about the playback actions performed on the DRM files.
206 *
207 * @param uniqueId Unique identifier for a session
208 * @param decryptHandle Handle for the decryption session
209 * @param playbackStatus Playback action (Playback::START, Playback::STOP, Playback::PAUSE)
210 * @param position Position in the file (in milliseconds) where the start occurs.
211 *     Only valid together with Playback::START.
212 * @return status_t
213 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
214 */
215#ifdef USE_64BIT_DRM_API
216status_t onSetPlaybackStatus(int uniqueId,
217                             DecryptHandle* decryptHandle,
218                             int playbackStatus,
219                             int64_t position);
220#else
221status_t onSetPlaybackStatus(int uniqueId,
222                             DecryptHandle* decryptHandle,
223                             int playbackStatus,
224                             int position);
225#endif
226
227/**
228 *  Validates whether an action on the DRM content is allowed or not.
229 *
230 * @param uniqueId Unique identifier for a session
231 * @param path Path of the protected content
232 * @param action Action to validate (Action::PLAY, Action::TRANSFER, etc)
233 * @param description Detailed description of the action
234 * @return true if the action is allowed.
235 */
236bool onValidateAction(int uniqueId,
237                      const String8& path,
238                      int action,
239                      const ActionDescription& description);
240
241/**
242 * Removes the rights associated with the given protected content.
243 * Not used for Forward Lock Engine.
244 *
245 * @param uniqueId Unique identifier for a session
246 * @param path Path of the protected content
247 * @return status_t
248 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
249 */
250status_t onRemoveRights(int uniqueId, const String8& path);
251
252/**
253 * Removes all the rights information of each plug-in associated with
254 * DRM framework. Will be used in master reset but does nothing for
255 * Forward Lock Engine.
256 *
257 * @param uniqueId Unique identifier for a session
258 * @return status_t
259 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
260 */
261status_t onRemoveAllRights(int uniqueId);
262
263/**
264 * Starts the Forward Lock file conversion session.
265 * Each time the application tries to download a new DRM file
266 * which needs to be converted, then the application has to
267 * begin with calling this API. The convertId is used as the conversion session key
268 * and must not be the same for different convert sessions.
269 *
270 * @param uniqueId Unique identifier for a session
271 * @param convertId Handle for the convert session
272 * @return status_t
273 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
274 */
275status_t onOpenConvertSession(int uniqueId, int convertId);
276
277/**
278 * Accepts and converts the input data which is part of DRM file.
279 * The resultant converted data and the status is returned in the DrmConvertedInfo
280 * object. This method will be called each time there is a new block
281 * of data received by the application.
282 *
283 * @param uniqueId Unique identifier for a session
284 * @param convertId Handle for the convert session
285 * @param inputData Input Data which need to be converted
286 * @return Return object contains the status of the data conversion,
287 *       the output converted data and offset. In this case the
288 *      application will ignore the offset information.
289 */
290DrmConvertedStatus* onConvertData(int uniqueId,
291                                  int convertId,
292                                  const DrmBuffer* inputData);
293
294/**
295 * Closes the convert session in case of data supply completed or error occurred.
296 * Upon successful conversion of the complete data, it returns signature calculated over
297 * the entire data used over a conversion session. This signature must be copied to the offset
298 * mentioned in the DrmConvertedStatus. Signature is used for data integrity protection.
299 *
300 * @param uniqueId Unique identifier for a session
301 * @param convertId Handle for the convert session
302 * @return Return object contains the status of the data conversion,
303 *      the header and body signature data. It also informs
304 *      the application about the file offset at which this
305 *      signature data should be written.
306 */
307DrmConvertedStatus* onCloseConvertSession(int uniqueId, int convertId);
308
309/**
310 * Returns the information about the Drm Engine capabilities which includes
311 * supported MimeTypes and file suffixes.
312 *
313 * @param uniqueId Unique identifier for a session
314 * @return DrmSupportInfo
315 *      instance which holds the capabilities of a plug-in
316 */
317DrmSupportInfo* onGetSupportInfo(int uniqueId);
318
319/**
320 * Open the decrypt session to decrypt the given protected content.
321 *
322 * @param uniqueId Unique identifier for a session
323 * @param decryptHandle Handle for the current decryption session
324 * @param fd File descriptor of the protected content to be decrypted
325 * @param offset Start position of the content
326 * @param length The length of the protected content
327 * @return
328 *     DRM_ERROR_CANNOT_HANDLE for failure and DRM_NO_ERROR for success
329 */
330#ifdef USE_64BIT_DRM_API
331status_t onOpenDecryptSession(int uniqueId,
332                              DecryptHandle* decryptHandle,
333                              int fd, off64_t offset, off64_t length);
334#else
335status_t onOpenDecryptSession(int uniqueId,
336                              DecryptHandle* decryptHandle,
337                              int fd, int offset, int length);
338#endif
339
340/**
341 * Open the decrypt session to decrypt the given protected content.
342 *
343 * @param uniqueId Unique identifier for a session
344 * @param decryptHandle Handle for the current decryption session
345 * @param uri Path of the protected content to be decrypted
346 * @return
347 *     DRM_ERROR_CANNOT_HANDLE for failure and DRM_NO_ERROR for success
348 */
349status_t onOpenDecryptSession(int uniqueId,
350                              DecryptHandle* decryptHandle,
351                              const char* uri);
352
353/**
354 * Close the decrypt session for the given handle.
355 *
356 * @param uniqueId Unique identifier for a session
357 * @param decryptHandle Handle for the decryption session
358 * @return status_t
359 *     Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure
360 */
361status_t onCloseDecryptSession(int uniqueId,
362                               DecryptHandle* decryptHandle);
363
364/**
365 * Initialize decryption for the given unit of the protected content.
366 *
367 * @param uniqueId Unique identifier for a session
368 * @param decryptHandle Handle for the decryption session
369 * @param decryptUnitId ID which specifies decryption unit, such as track ID
370 * @param headerInfo Information for initializing decryption of this decrypUnit
371 * @return
372 *     DRM_ERROR_CANNOT_HANDLE for failure and DRM_NO_ERROR for success
373 */
374status_t onInitializeDecryptUnit(int uniqueId,
375                                 DecryptHandle* decryptHandle,
376                                 int decryptUnitId,
377                                 const DrmBuffer* headerInfo);
378
379/**
380 * Decrypt the protected content buffers for the given unit.
381 * This method will be called any number of times, based on number of
382 * encrypted streams received from application.
383 *
384 * @param uniqueId Unique identifier for a session
385 * @param decryptHandle Handle for the decryption session
386 * @param decryptUnitId ID which specifies decryption unit, such as track ID
387 * @param encBuffer Encrypted data block
388 * @param decBuffer Decrypted data block
389 * @return status_t
390 *     Returns the error code for this API
391 *     DRM_NO_ERROR for success, and one of DRM_ERROR_UNKNOWN, DRM_ERROR_LICENSE_EXPIRED
392 *     DRM_ERROR_SESSION_NOT_OPENED, DRM_ERROR_DECRYPT_UNIT_NOT_INITIALIZED,
393 *     DRM_ERROR_DECRYPT for failure.
394 */
395status_t onDecrypt(int uniqueId,
396                   DecryptHandle* decryptHandle,
397                   int decryptUnitId,
398                   const DrmBuffer* encBuffer,
399                   DrmBuffer** decBuffer);
400
401/**
402 * Decrypt the protected content buffers for the given unit.
403 * This method will be called any number of times, based on number of
404 * encrypted streams received from application.
405 *
406 * @param uniqueId Unique identifier for a session
407 * @param decryptId Handle for the decryption session
408 * @param decryptUnitId ID Specifies decryption unit, such as track ID
409 * @param encBuffer Encrypted data block
410 * @param decBuffer Decrypted data block
411 * @param IV Optional buffer
412 * @return status_t
413 *     Returns the error code for this API
414 *     DRM_NO_ERROR for success, and one of DRM_ERROR_UNKNOWN, DRM_ERROR_LICENSE_EXPIRED
415 *     DRM_ERROR_SESSION_NOT_OPENED, DRM_ERROR_DECRYPT_UNIT_NOT_INITIALIZED,
416 *     DRM_ERROR_DECRYPT for failure.
417 */
418status_t onDecrypt(int uniqueId, DecryptHandle* decryptHandle,
419                   int decryptUnitId, const DrmBuffer* encBuffer,
420                   DrmBuffer** decBuffer, DrmBuffer* IV);
421
422/**
423 * Finalize decryption for the given unit of the protected content.
424 *
425 * @param uniqueId Unique identifier for a session
426 * @param decryptHandle Handle for the decryption session
427 * @param decryptUnitId ID Specifies decryption unit, such as track ID
428 * @return
429 *     DRM_ERROR_CANNOT_HANDLE for failure and DRM_NO_ERROR for success
430 */
431status_t onFinalizeDecryptUnit(int uniqueId,
432                               DecryptHandle* decryptHandle,
433                               int decryptUnitId);
434
435/**
436 * Reads the specified number of bytes from an open DRM file.
437 *
438 * @param uniqueId Unique identifier for a session
439 * @param decryptHandle Handle for the decryption session
440 * @param buffer Reference to the buffer that should receive the read data.
441 * @param numBytes Number of bytes to read.
442 *
443 * @return Number of bytes read.
444 * @retval -1 Failure.
445 */
446ssize_t onRead(int uniqueId,
447               DecryptHandle* decryptHandle,
448               void* pBuffer,
449               int numBytes);
450
451/**
452 * Updates the file position within an open DRM file.
453 *
454 * @param uniqueId Unique identifier for a session
455 * @param decryptHandle Handle for the decryption session
456 * @param offset Offset with which to update the file position.
457 * @param whence One of SEEK_SET, SEEK_CUR, and SEEK_END.
458 *           These constants are defined in unistd.h.
459 *
460 * @return New file position.
461 * @retval ((off_t)-1) Failure.
462 */
463#ifdef USE_64BIT_DRM_API
464off64_t onLseek(int uniqueId,
465                DecryptHandle* decryptHandle,
466                off64_t offset,
467                int whence);
468#else
469off_t onLseek(int uniqueId,
470              DecryptHandle* decryptHandle,
471              off_t offset,
472              int whence);
473#endif
474
475/**
476 * Reads the specified number of bytes from an open DRM file.
477 *
478 * @param uniqueId Unique identifier for a session
479 * @param decryptHandle Handle for the decryption session
480 * @param buffer Reference to the buffer that should receive the read data.
481 * @param numBytes Number of bytes to read.
482 * @param offset Offset with which to update the file position.
483 *
484 * @return Number of bytes read. Returns -1 for Failure.
485 */
486#ifdef USE_64BIT_DRM_API
487ssize_t onPread(int uniqueId,
488                DecryptHandle* decryptHandle,
489                void* buffer,
490                ssize_t numBytes,
491                off64_t offset);
492#else
493ssize_t onPread(int uniqueId,
494                DecryptHandle* decryptHandle,
495                void* buffer,
496                ssize_t numBytes,
497                off_t offset);
498#endif
499
500private:
501
502    static const String8 Description;
503    static const String8 FileSuffixes[];
504    static const String8 MimeTypes[];
505    static bool IsFileSuffixSupported(const String8& suffix);
506    static bool IsMimeTypeSupported(const String8& mime);
507    static void AddSupportedMimeTypes(DrmSupportInfo *info);
508    static void AddSupportedFileSuffixes(DrmSupportInfo *info);
509
510/**
511 * Session Class for Forward Lock Conversion. An object of this class is created
512 * for every conversion.
513 */
514class ConvertSession {
515    public :
516        int uniqueId;
517        FwdLockConv_Output_t output;
518
519        ConvertSession() {
520            uniqueId = 0;
521            memset(&output, 0, sizeof(FwdLockConv_Output_t));
522        }
523
524        virtual ~ConvertSession() {}
525};
526
527/**
528 * Session Class for Forward Lock decoder. An object of this class is created
529 * for every decoding session.
530 */
531class DecodeSession {
532    public :
533        int fileDesc;
534        off_t offset;
535
536        DecodeSession() {
537            fileDesc = -1;
538            offset = 0;
539        }
540
541        DecodeSession(int fd) {
542            fileDesc = fd;
543            offset = 0;
544        }
545
546        virtual ~DecodeSession() {}
547};
548
549/**
550 * Session Map Tables for Conversion and Decoding of forward lock files.
551 */
552SessionMap<ConvertSession*> convertSessionMap;
553SessionMap<DecodeSession*> decodeSessionMap;
554
555/**
556 * Converts the error code from Forward Lock Converter to DrmConvertStatus error code.
557 *
558 * @param Forward Lock Converter error code
559 *
560 * @return Status code from DrmConvertStatus.
561 */
562static int getConvertedStatus(FwdLockConv_Status_t status);
563};
564
565};
566
567#endif /* __FWDLOCKENGINE_H__ */
568