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