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 __DRM_ENGINE_BASE_H__ 18 #define __DRM_ENGINE_BASE_H__ 19 20 #include <drm/drm_framework_common.h> 21 #include "IDrmEngine.h" 22 23 namespace android { 24 25 /** 26 * This class is an interface for plug-in developers 27 * 28 * Responsibility of this class is control the sequence of actual plug-in. 29 * All each plug-in developer has to do is implement onXXX() type virtual interfaces. 30 */ 31 class DrmEngineBase : public IDrmEngine { 32 public: 33 DrmEngineBase(); 34 virtual ~DrmEngineBase(); 35 36 public: 37 DrmConstraints* getConstraints(int uniqueId, const String8* path, int action); 38 39 DrmMetadata* getMetadata(int uniqueId, const String8* path); 40 41 status_t initialize(int uniqueId); 42 43 status_t setOnInfoListener(int uniqueId, const IDrmEngine::OnInfoListener* infoListener); 44 45 status_t terminate(int uniqueId); 46 47 bool canHandle(int uniqueId, const String8& path); 48 49 DrmInfoStatus* processDrmInfo(int uniqueId, const DrmInfo* drmInfo); 50 51 status_t saveRights(int uniqueId, const DrmRights& drmRights, 52 const String8& rightsPath, const String8& contentPath); 53 54 DrmInfo* acquireDrmInfo(int uniqueId, const DrmInfoRequest* drmInfoRequest); 55 56 String8 getOriginalMimeType(int uniqueId, const String8& path); 57 58 int getDrmObjectType(int uniqueId, const String8& path, const String8& mimeType); 59 60 int checkRightsStatus(int uniqueId, const String8& path, int action); 61 62 status_t consumeRights(int uniqueId, DecryptHandle* decryptHandle, int action, bool reserve); 63 64 status_t setPlaybackStatus( 65 int uniqueId, DecryptHandle* decryptHandle, int playbackStatus, int64_t position); 66 67 bool validateAction( 68 int uniqueId, const String8& path, int action, const ActionDescription& description); 69 70 status_t removeRights(int uniqueId, const String8& path); 71 72 status_t removeAllRights(int uniqueId); 73 74 status_t openConvertSession(int uniqueId, int convertId); 75 76 DrmConvertedStatus* convertData(int uniqueId, int convertId, const DrmBuffer* inputData); 77 78 DrmConvertedStatus* closeConvertSession(int uniqueId, int convertId); 79 80 DrmSupportInfo* getSupportInfo(int uniqueId); 81 82 status_t openDecryptSession( 83 int uniqueId, DecryptHandle* decryptHandle, int fd, off64_t offset, off64_t length); 84 85 status_t openDecryptSession( 86 int uniqueId, DecryptHandle* decryptHandle, const char* uri); 87 88 status_t closeDecryptSession(int uniqueId, DecryptHandle* decryptHandle); 89 90 status_t initializeDecryptUnit(int uniqueId, DecryptHandle* decryptHandle, 91 int decryptUnitId, const DrmBuffer* headerInfo); 92 93 status_t decrypt(int uniqueId, DecryptHandle* decryptHandle, int decryptUnitId, 94 const DrmBuffer* encBuffer, DrmBuffer** decBuffer, DrmBuffer* IV); 95 96 status_t finalizeDecryptUnit(int uniqueId, DecryptHandle* decryptHandle, int decryptUnitId); 97 98 ssize_t pread(int uniqueId, DecryptHandle* decryptHandle, 99 void* buffer, ssize_t numBytes, off64_t offset); 100 101 protected: 102 ///////////////////////////////////////////////////// 103 // Interface for plug-in developers // 104 // each plug-in has to implement following method // 105 ///////////////////////////////////////////////////// 106 /** 107 * Get constraint information associated with input content 108 * 109 * @param[in] uniqueId Unique identifier for a session 110 * @param[in] path Path of the protected content 111 * @param[in] action Actions defined such as, 112 * Action::DEFAULT, Action::PLAY, etc 113 * @return DrmConstraints 114 * key-value pairs of constraint are embedded in it 115 * @note 116 * In case of error, return NULL 117 */ 118 virtual DrmConstraints* onGetConstraints( 119 int uniqueId, const String8* path, int action) = 0; 120 121 /** 122 * Get metadata information associated with input content 123 * 124 * @param[in] uniqueId Unique identifier for a session 125 * @param[in] path Path of the protected content 126 * @return DrmMetadata 127 * key-value pairs of metadata 128 * @note 129 * In case of error, return NULL 130 */ 131 virtual DrmMetadata* onGetMetadata(int uniqueId, const String8* path) = 0; 132 133 /** 134 * Initialize plug-in 135 * 136 * @param[in] uniqueId Unique identifier for a session 137 * @return status_t 138 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 139 */ 140 virtual status_t onInitialize(int uniqueId) = 0; 141 142 /** 143 * Register a callback to be invoked when the caller required to 144 * receive necessary information 145 * 146 * @param[in] uniqueId Unique identifier for a session. uniqueId is a random 147 * number generated in the DRM service. If the DrmManagerClient 148 * is created in native code, uniqueId will be a number ranged 149 * from 0x1000 to 0x1fff. If it comes from Java code, the uniqueId 150 * will be a number ranged from 0x00 to 0xfff. So bit 0x1000 in 151 * uniqueId could be used in DRM plugins to differentiate native 152 * OnInfoListener and Java OnInfoListener. 153 * @param[in] infoListener Listener 154 * @return status_t 155 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 156 */ 157 virtual status_t onSetOnInfoListener( 158 int uniqueId, const IDrmEngine::OnInfoListener* infoListener) = 0; 159 160 /** 161 * Terminate the plug-in 162 * and release resource bound to plug-in 163 * 164 * @param[in] uniqueId Unique identifier for a session 165 * @return status_t 166 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 167 */ 168 virtual status_t onTerminate(int uniqueId) = 0; 169 170 /** 171 * Get whether the given content can be handled by this plugin or not 172 * 173 * @param[in] uniqueId Unique identifier for a session 174 * @param[in] path Path the protected object 175 * @return bool 176 * Returns true if this plugin can handle , false in case of not able to handle 177 */ 178 virtual bool onCanHandle(int uniqueId, const String8& path) = 0; 179 180 /** 181 * Executes given drm information based on its type 182 * 183 * @param[in] uniqueId Unique identifier for a session 184 * @param[in] drmInfo Information needs to be processed 185 * @return DrmInfoStatus 186 * instance as a result of processing given input 187 */ 188 virtual DrmInfoStatus* onProcessDrmInfo(int uniqueId, const DrmInfo* drmInfo) = 0; 189 190 /** 191 * Save DRM rights to specified rights path 192 * and make association with content path 193 * 194 * @param[in] uniqueId Unique identifier for a session 195 * @param[in] drmRights DrmRights to be saved 196 * @param[in] rightsPath File path where rights to be saved 197 * @param[in] contentPath File path where content was saved 198 * @return status_t 199 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 200 */ 201 virtual status_t onSaveRights(int uniqueId, const DrmRights& drmRights, 202 const String8& rightspath, const String8& contentPath) = 0; 203 204 /** 205 * Retrieves necessary information for registration, unregistration or rights 206 * acquisition information. 207 * 208 * @param[in] uniqueId Unique identifier for a session 209 * @param[in] drmInfoRequest Request information to retrieve drmInfo 210 * @return DrmInfo 211 * instance as a result of processing given input 212 */ 213 virtual DrmInfo* onAcquireDrmInfo(int uniqueId, const DrmInfoRequest* drmInforequest) = 0; 214 215 /** 216 * Retrieves the mime type embedded inside the original content 217 * 218 * @param[in] uniqueId Unique identifier for a session 219 * @param[in] path Path of the protected content 220 * @return String8 221 * Returns mime-type of the original content, such as "video/mpeg" 222 */ 223 virtual String8 onGetOriginalMimeType(int uniqueId, const String8& path) = 0; 224 225 /** 226 * Retrieves the type of the protected object (content, rights, etc..) 227 * using specified path or mimetype. At least one parameter should be non null 228 * to retrieve DRM object type 229 * 230 * @param[in] uniqueId Unique identifier for a session 231 * @param[in] path Path of the content or null. 232 * @param[in] mimeType Mime type of the content or null. 233 * @return type of the DRM content, 234 * such as DrmObjectType::CONTENT, DrmObjectType::RIGHTS_OBJECT 235 */ 236 virtual int onGetDrmObjectType( 237 int uniqueId, const String8& path, const String8& mimeType) = 0; 238 239 /** 240 * Check whether the given content has valid rights or not 241 * 242 * @param[in] uniqueId Unique identifier for a session 243 * @param[in] path Path of the protected content 244 * @param[in] action Action to perform (Action::DEFAULT, Action::PLAY, etc) 245 * @return the status of the rights for the protected content, 246 * such as RightsStatus::RIGHTS_VALID, RightsStatus::RIGHTS_EXPIRED, etc. 247 */ 248 virtual int onCheckRightsStatus(int uniqueId, const String8& path, int action) = 0; 249 250 /** 251 * Consumes the rights for a content. 252 * If the reserve parameter is true the rights is reserved until the same 253 * application calls this api again with the reserve parameter set to false. 254 * 255 * @param[in] uniqueId Unique identifier for a session 256 * @param[in] decryptHandle Handle for the decryption session 257 * @param[in] action Action to perform. (Action::DEFAULT, Action::PLAY, etc) 258 * @param[in] reserve True if the rights should be reserved. 259 * @return status_t 260 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 261 */ 262 virtual status_t onConsumeRights(int uniqueId, DecryptHandle* decryptHandle, 263 int action, bool reserve) = 0; 264 265 /** 266 * Informs the DRM Engine about the playback actions performed on the DRM files. 267 * 268 * @param[in] uniqueId Unique identifier for a session 269 * @param[in] decryptHandle Handle for the decryption session 270 * @param[in] playbackStatus Playback action (Playback::START, Playback::STOP, Playback::PAUSE) 271 * @param[in] position Position in the file (in milliseconds) where the start occurs. 272 * Only valid together with Playback::START. 273 * @return status_t 274 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 275 */ 276 virtual status_t onSetPlaybackStatus( 277 int uniqueId, DecryptHandle* decryptHandle, int playbackStatus, int64_t position) = 0; 278 279 /** 280 * Validates whether an action on the DRM content is allowed or not. 281 * 282 * @param[in] uniqueId Unique identifier for a session 283 * @param[in] path Path of the protected content 284 * @param[in] action Action to validate (Action::PLAY, Action::TRANSFER, etc) 285 * @param[in] description Detailed description of the action 286 * @return true if the action is allowed. 287 */ 288 virtual bool onValidateAction(int uniqueId, const String8& path, 289 int action, const ActionDescription& description) = 0; 290 291 /** 292 * Removes the rights associated with the given protected content 293 * 294 * @param[in] uniqueId Unique identifier for a session 295 * @param[in] path Path of the protected content 296 * @return status_t 297 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 298 */ 299 virtual status_t onRemoveRights(int uniqueId, const String8& path) = 0; 300 301 /** 302 * Removes all the rights information of each plug-in associated with 303 * DRM framework. Will be used in master reset 304 * 305 * @param[in] uniqueId Unique identifier for a session 306 * @return status_t 307 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 308 */ 309 virtual status_t onRemoveAllRights(int uniqueId) = 0; 310 311 /** 312 * This API is for Forward Lock based DRM scheme. 313 * Each time the application tries to download a new DRM file 314 * which needs to be converted, then the application has to 315 * begin with calling this API. 316 * 317 * @param[in] uniqueId Unique identifier for a session 318 * @param[in] convertId Handle for the convert session 319 * @return status_t 320 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 321 */ 322 virtual status_t onOpenConvertSession(int uniqueId, int convertId) = 0; 323 324 /** 325 * Accepts and converts the input data which is part of DRM file. 326 * The resultant converted data and the status is returned in the DrmConvertedInfo 327 * object. This method will be called each time there are new block 328 * of data received by the application. 329 * 330 * @param[in] uniqueId Unique identifier for a session 331 * @param[in] convertId Handle for the convert session 332 * @param[in] inputData Input Data which need to be converted 333 * @return Return object contains the status of the data conversion, 334 * the output converted data and offset. In this case the 335 * application will ignore the offset information. 336 */ 337 virtual DrmConvertedStatus* onConvertData( 338 int uniqueId, int convertId, const DrmBuffer* inputData) = 0; 339 340 /** 341 * Informs the Drm Agent when there is no more data which need to be converted 342 * or when an error occurs. Upon successful conversion of the complete data, 343 * the agent will inform that where the header and body signature 344 * should be added. This signature appending is needed to integrity 345 * protect the converted file. 346 * 347 * @param[in] uniqueId Unique identifier for a session 348 * @param[in] convertId Handle for the convert session 349 * @return Return object contains the status of the data conversion, 350 * the header and body signature data. It also informs 351 * the application on which offset these signature data 352 * should be appended. 353 */ 354 virtual DrmConvertedStatus* onCloseConvertSession(int uniqueId, int convertId) = 0; 355 356 /** 357 * Returns the information about the Drm Engine capabilities which includes 358 * supported MimeTypes and file suffixes. 359 * 360 * @param[in] uniqueId Unique identifier for a session 361 * @return DrmSupportInfo 362 * instance which holds the capabilities of a plug-in 363 */ 364 virtual DrmSupportInfo* onGetSupportInfo(int uniqueId) = 0; 365 366 /** 367 * Open the decrypt session to decrypt the given protected content 368 * 369 * @param[in] uniqueId Unique identifier for a session 370 * @param[in] decryptHandle Handle for the current decryption session 371 * @param[in] fd File descriptor of the protected content to be decrypted 372 * @param[in] offset Start position of the content 373 * @param[in] length The length of the protected content 374 * @return 375 * DRM_ERROR_CANNOT_HANDLE for failure and DRM_NO_ERROR for success 376 */ 377 virtual status_t onOpenDecryptSession( 378 int uniqueId, DecryptHandle* decryptHandle, int fd, off64_t offset, off64_t length) = 0; 379 380 /** 381 * Open the decrypt session to decrypt the given protected content 382 * 383 * @param[in] uniqueId Unique identifier for a session 384 * @param[in] decryptHandle Handle for the current decryption session 385 * @param[in] uri Path of the protected content to be decrypted 386 * @return 387 * DRM_ERROR_CANNOT_HANDLE for failure and DRM_NO_ERROR for success 388 */ 389 virtual status_t onOpenDecryptSession( 390 int uniqueId, DecryptHandle* decryptHandle, const char* uri) = 0; 391 392 /** 393 * Close the decrypt session for the given handle 394 * 395 * @param[in] uniqueId Unique identifier for a session 396 * @param[in] decryptHandle Handle for the decryption session 397 * @return status_t 398 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 399 */ 400 virtual status_t onCloseDecryptSession(int uniqueId, DecryptHandle* decryptHandle) = 0; 401 402 /** 403 * Initialize decryption for the given unit of the protected content 404 * 405 * @param[in] uniqueId Unique identifier for a session 406 * @param[in] decryptId Handle for the decryption session 407 * @param[in] decryptUnitId ID Specifies decryption unit, such as track ID 408 * @param[in] headerInfo Information for initializing decryption of this decrypUnit 409 * @return status_t 410 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 411 */ 412 virtual status_t onInitializeDecryptUnit(int uniqueId, DecryptHandle* decryptHandle, 413 int decryptUnitId, const DrmBuffer* headerInfo) = 0; 414 415 /** 416 * Decrypt the protected content buffers for the given unit 417 * This method will be called any number of times, based on number of 418 * encrypted streams received from application. 419 * 420 * @param[in] uniqueId Unique identifier for a session 421 * @param[in] decryptId Handle for the decryption session 422 * @param[in] decryptUnitId ID Specifies decryption unit, such as track ID 423 * @param[in] encBuffer Encrypted data block 424 * @param[out] decBuffer Decrypted data block 425 * @param[in] IV Optional buffer 426 * @return status_t 427 * Returns the error code for this API 428 * DRM_NO_ERROR for success, and one of DRM_ERROR_UNKNOWN, DRM_ERROR_LICENSE_EXPIRED 429 * DRM_ERROR_SESSION_NOT_OPENED, DRM_ERROR_DECRYPT_UNIT_NOT_INITIALIZED, 430 * DRM_ERROR_DECRYPT for failure. 431 */ 432 virtual status_t onDecrypt(int uniqueId, DecryptHandle* decryptHandle, int decryptUnitId, 433 const DrmBuffer* encBuffer, DrmBuffer** decBuffer, DrmBuffer* IV) = 0; 434 435 /** 436 * Finalize decryption for the given unit of the protected content 437 * 438 * @param[in] uniqueId Unique identifier for a session 439 * @param[in] decryptHandle Handle for the decryption session 440 * @param[in] decryptUnitId ID Specifies decryption unit, such as track ID 441 * @return status_t 442 * Returns DRM_NO_ERROR for success, DRM_ERROR_UNKNOWN for failure 443 */ 444 virtual status_t onFinalizeDecryptUnit( 445 int uniqueId, DecryptHandle* decryptHandle, int decryptUnitId) = 0; 446 447 /** 448 * Reads the specified number of bytes from an open DRM file. 449 * 450 * @param[in] uniqueId Unique identifier for a session 451 * @param[in] decryptHandle Handle for the decryption session 452 * @param[out] buffer Reference to the buffer that should receive the read data. 453 * @param[in] numBytes Number of bytes to read. 454 * @param[in] offset Offset with which to update the file position. 455 * 456 * @return Number of bytes read. Returns -1 for Failure. 457 */ 458 virtual ssize_t onPread(int uniqueId, DecryptHandle* decryptHandle, 459 void* buffer, ssize_t numBytes, off64_t offset) = 0; 460 }; 461 462 }; 463 464 #endif /* __DRM_ENGINE_BASE_H__ */ 465 466
