DrmEngineBase.h revision 8f00151cbe693d52f3e233757c57fab3b6396d21
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
23namespace 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 */
31class DrmEngineBase : public IDrmEngine {
32public:
33    DrmEngineBase();
34    virtual ~DrmEngineBase();
35
36public:
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
101protected:
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