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