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