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