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