svc_drm.h revision 54b6cfa9a9e5b861a9930af873580d6dc20f773c 
1/*
2 * Copyright (C) 2007 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 __SVC_DRM_NEW_H__
18#define __SVC_DRM_NEW_H__
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24#include <drm_common_types.h>
25
26/**
27 * Define the mime type of DRM data.
28 */
29#define TYPE_DRM_MESSAGE            0x48    /**< The mime type is "application/vnd.oma.drm.message" */
30#define TYPE_DRM_CONTENT            0x49    /**< The mime type is "application/vnd.oma.drm.content" */
31#define TYPE_DRM_RIGHTS_XML         0x4a    /**< The mime type is "application/vnd.oma.drm.rights+xml" */
32#define TYPE_DRM_RIGHTS_WBXML       0x4b    /**< The mime type is "application/vnd.oma.drm.rights+wbxml" */
33#define TYPE_DRM_UNKNOWN            0xff    /**< The mime type is unknown */
34
35/**
36 * Define the delivery methods.
37 */
38#define FORWARD_LOCK                1       /**< Forward_lock */
39#define COMBINED_DELIVERY           2       /**< Combined delivery */
40#define SEPARATE_DELIVERY           3       /**< Separate delivery */
41#define SEPARATE_DELIVERY_FL        4       /**< Separate delivery but DCF is forward-lock */
42
43/**
44 * Define the permissions.
45 */
46#define DRM_PERMISSION_PLAY         0x01    /**< Play */
47#define DRM_PERMISSION_DISPLAY      0x02    /**< Display */
48#define DRM_PERMISSION_EXECUTE      0x04    /**< Execute */
49#define DRM_PERMISSION_PRINT        0x08    /**< Print */
50#define DRM_PERMISSION_FORWARD      0x10    /**< Forward */
51
52/**
53 * Define the constraints.
54 */
55#define DRM_NO_CONSTRAINT           0x80    /**< Indicate have no constraint, it can use freely */
56#define DRM_END_TIME_CONSTRAINT     0x08    /**< Indicate have end time constraint */
57#define DRM_INTERVAL_CONSTRAINT     0x04    /**< Indicate have interval constraint */
58#define DRM_COUNT_CONSTRAINT        0x02    /**< Indicate have count constraint */
59#define DRM_START_TIME_CONSTRAINT   0x01    /**< Indicate have start time constraint */
60#define DRM_NO_PERMISSION           0x00    /**< Indicate no rights */
61
62/**
63 * Define the return values for those interface.
64 */
65#define DRM_SUCCESS                 0
66#define DRM_FAILURE                 -1
67#define DRM_MEDIA_EOF               -2
68#define DRM_RIGHTS_DATA_INVALID     -3
69#define DRM_MEDIA_DATA_INVALID      -4
70#define DRM_SESSION_NOT_OPENED      -5
71#define DRM_NO_RIGHTS               -6
72#define DRM_NOT_SD_METHOD           -7
73#define DRM_RIGHTS_PENDING          -8
74#define DRM_RIGHTS_EXPIRED          -9
75#define DRM_UNKNOWN_DATA_LEN        -10
76
77/**
78 * The input DRM data structure, include DM, DCF, DR, DRC.
79 */
80typedef struct _T_DRM_Input_Data {
81    /**
82     * The handle of the input DRM data.
83     */
84    int32_t inputHandle;
85
86    /**
87     * The mime type of the DRM data, if the mime type set to unknown, DRM engine
88     * will try to scan the input data to confirm the mime type, but we must say that
89     * the scan and check of mime type is not strictly precise.
90     */
91    int32_t mimeType;
92
93    /**
94     * The function to get input data length, this function should be implement by out module,
95     * and DRM engine will call-back it.
96     *
97     * \param inputHandle   The handle of the DRM data.
98     *
99     * \return
100     *      -A positive integer indicate the length of input data.
101     *      -0, if some error occurred.
102     */
103    int32_t (*getInputDataLength)(int32_t inputHandle);
104
105    /**
106     * The function to read the input data, this function should be implement by out module,
107     * and DRM engine will call-back it.
108     *
109     * \param inputHandle   The handle of the DRM data.
110     * \param buf       The buffer mallocced by DRM engine to save the data.
111     * \param bufLen    The length of the buffer.
112     *
113     * \return
114     *      -A positive integer indicate the actually length of byte has been read.
115     *      -0, if some error occurred.
116     *      -(-1), if reach to the end of the data.
117     */
118    int32_t (*readInputData)(int32_t inputHandle, uint8_t* buf, int32_t bufLen);
119
120    /**
121     * The function to seek the current file pointer, this function should be implement by out module,
122     * and DRM engine will call-back it.
123     *
124     * \param inputHandle   The handle of the DRM data.
125     * \param offset    The offset from the start position to be seek.
126     *
127     * \return
128     *      -0, if seek operation success.
129     *      -(-1), if seek operation fail.
130     */
131    int32_t (*seekInputData)(int32_t inputHandle, int32_t offset);
132} T_DRM_Input_Data;
133
134/**
135 * The constraint structure.
136 */
137typedef struct _T_DRM_Constraint_Info {
138    uint8_t indicator;          /**< Whether there is a right */
139    uint8_t unUsed[3];
140    int32_t count;              /**< The constraint of count */
141    int32_t startDate;          /**< The constraint of start date */
142    int32_t startTime;          /**< The constraint of start time */
143    int32_t endDate;            /**< The constraint of end date */
144    int32_t endTime;            /**< The constraint of end time */
145    int32_t intervalDate;       /**< The constraint of interval date */
146    int32_t intervalTime;       /**< The constraint of interval time */
147} T_DRM_Constraint_Info;
148
149/**
150 * The rights permission and constraint information structure.
151 */
152typedef struct _T_DRM_Rights_Info {
153    uint8_t roId[256];                     /**< The unique id for a specially rights object */
154    T_DRM_Constraint_Info playRights;       /**< Constraint of play */
155    T_DRM_Constraint_Info displayRights;    /**< Constraint of display */
156    T_DRM_Constraint_Info executeRights;    /**< Constraint of execute */
157    T_DRM_Constraint_Info printRights;      /**< Constraint of print */
158} T_DRM_Rights_Info;
159
160/**
161 * The list node of the Rights information structure.
162 */
163typedef struct _T_DRM_Rights_Info_Node {
164    T_DRM_Rights_Info roInfo;
165    struct _T_DRM_Rights_Info_Node *next;
166} T_DRM_Rights_Info_Node;
167
168/**
169 * Install a rights object to DRM engine, include the rights in Combined Delivery cases.
170 * Because all the rights object is managed by DRM engine, so every incoming rights object
171 * must be install to the engine first, or the DRM engine will not recognize it.
172 *
173 * \param data      The rights object data or Combined Delivery case data.
174 * \param pRightsInfo   The structure to save this rights information.
175 *
176 * \return
177 *      -DRM_SUCCESS, when install successfully.
178 *      -DRM_RIGHTS_DATA_INVALID, when the input rights data is invalid.
179 *      -DRM_FAILURE, when some other error occur.
180 */
181int32_t SVC_drm_installRights(T_DRM_Input_Data data, T_DRM_Rights_Info* pRightsInfo);
182
183/**
184 * Open a session for a special DRM object, it will parse the input DRM data, and then user
185 * can try to get information for this DRM object, or try to use it if the rights is valid.
186 *
187 * \param data      The DRM object data, DM or DCF.
188 *
189 * \return
190 *      -A handle for this opened DRM object session.
191 *      -DRM_MEDIA_DATA_INVALID, when the input DRM object data is invalid.
192 *      -DRM_FAILURE, when some other error occurred.
193 */
194int32_t SVC_drm_openSession(T_DRM_Input_Data data);
195
196/**
197 * Get the delivery method of the DRM object.
198 *
199 * \param session   The handle for this DRM object session.
200 *
201 * \return
202 *      -The delivery method of this DRM object, include: FORWARD_LOCK, COMBINED_DELIVERY, SEPARATE_DELIVERY, SEPARATE_DELIVERY_FL.
203 *      -DRM_FAILURE, when some other error occurred.
204 */
205int32_t SVC_drm_getDeliveryMethod(int32_t session);
206
207/**
208 * Get DRM object media object content type.
209 *
210 * \param session   The handle for this DRM object session.
211 * \param mediaType The buffer to save the media type string, 64 bytes is enough.
212 *
213 * \return
214 *      -DRM_SUCCESS, when get the media object content type successfully.
215 *      -DRM_SESSION_NOT_OPENED, when the session is not opened or has been closed.
216 *      -DRM_FAILURE, when some other error occured.
217 */
218int32_t SVC_drm_getContentType(int32_t session, uint8_t* mediaType);
219
220/**
221 * Check whether a specific DRM object has the specific permission rights or not.
222 *
223 * \param session   The handle for this DRM object session.
224 * \param permission    Specify the permission to be checked.
225 *
226 * \return
227 *      -DRM_SUCCESS, when it has the rights for the permission.
228 *      -DRM_SESSION_NOT_OPENED, when the session is not opened or has been closed.
229 *      -DRM_NO_RIGHTS, when it has no rights.
230 *      -DRM_RIGHTS_PENDING, when it has the rights, but currently it is pending.
231 *      -DRM_RIGHTS_EXPIRED, when the rights has expired.
232 *      -DRM_FAILURE, when some other error occured.
233 */
234int32_t SVC_drm_checkRights(int32_t session, int32_t permission);
235
236/**
237 * Consume the rights when try to use the DRM object.
238 *
239 * \param session   The handle for this DRM object session.
240 * \param permission    Specify the permission to be checked.
241 *
242 * \return
243 *      -DRM_SUCCESS, when consume rights successfully.
244 *      -DRM_SESSION_NOT_OPENED, when the session is not opened or has been closed.
245 *      -DRM_NO_RIGHTS, when it has no rights.
246 *      -DRM_RIGHTS_PENDING, when it has the rights, but currently it is pending.
247 *      -DRM_RIGHTS_EXPIRED, when the rights has expired.
248 *      -DRM_FAILURE, when some other error occured.
249 */
250int32_t SVC_drm_consumeRights(int32_t session, int32_t permission);
251
252/**
253 * Get DRM media object content data length.
254 *
255 * \param session   The handle for this DRM object session.
256 *
257 * \return
258 *      -A positive integer indicate the length of the media object content data.
259 *      -DRM_SESSION_NOT_OPENED, when the session is not opened or has been closed.
260 *      -DRM_NO_RIGHTS, when the rights object is not existed.
261 *      -DRM_UNKNOWN_DATA_LEN, when DRM object media data length is unknown in case of DCF has no rights.
262 *      -DRM_FAILURE, when some other error occured.
263 */
264int32_t SVC_drm_getContentLength(int32_t session);
265
266/**
267 * Get DRM media object content data. Support get the data piece by piece if the content is too large.
268 *
269 * \param session   The handle for this DRM object session.
270 * \param offset    The offset to start to get content.
271 * \param mediaBuf  The buffer to save media object data.
272 * \param mediaBufLen   The length of the buffer.
273 *
274 * \return
275 *      -A positive integer indicate the actually length of the data has been got.
276 *      -DRM_SESSION_NOT_OPENED, when the session is not opened or has been closed.
277 *      -DRM_NO_RIGHTS, when the rights object is not existed.
278 *      -DRM_MEDIA_EOF, when reach to the end of the media data.
279 *      -DRM_FAILURE, when some other error occured.
280 */
281int32_t SVC_drm_getContent(int32_t session, int32_t offset, uint8_t* mediaBuf, int32_t mediaBufLen);
282
283/**
284 * Get the rights issuer address, this interface is specially for Separate Delivery method.
285 *
286 * \param session   The handle for this DRM object session.
287 * \param rightsIssuer  The buffer to save rights issuer, 256 bytes are enough.
288 *
289 * \return
290 *      -DRM_SUCCESS, when get the rights issuer successfully.
291 *      -DRM_SESSION_NOT_OPENED, when the session is not opened or has been closed.
292 *      -DRM_NOT_SD_METHOD, when it is not a Separate Delivery DRM object.
293 *      -DRM_FAILURE, when some other error occured.
294 */
295int32_t SVC_drm_getRightsIssuer(int32_t session, uint8_t* rightsIssuer);
296
297/**
298 * Get DRM object constraint informations.
299 *
300 * \param session   The handle for this DRM object session.
301 * \param rights    The structue to save the rights object information.
302 *
303 * \return
304 *      -DRM_SUCCESS, when get the rights information successfully.
305 *      -DRM_SESSION_NOT_OPENED, when the session is not opened or has been closed.
306 *      -DRM_NO_RIGHTS, when this DRM object has not rights.
307 *      -DRM_FAILURE, when some other error occured.
308 */
309int32_t SVC_drm_getRightsInfo(int32_t session, T_DRM_Rights_Info* rights);
310
311/**
312 * Close the opened session, after closed, the handle become invalid.
313 *
314 * \param session   The handle for this DRM object session.
315 *
316 * \return
317 *      -DRM_SUCCESS, when close operation success.
318 *      -DRM_SESSION_NOT_OPENED, when the session is not opened or has been closed.
319 *      -DRM_FAILURE, when some other error occured.
320 */
321int32_t SVC_drm_closeSession(int32_t session);
322
323/**
324 * Check and update the given rights according the given permission.
325 *
326 * \param contentID The unique id of the rights object.
327 * \param permission    The permission to be updated.
328 *
329 * \return
330 *      -DRM_SUCCESS, when update operation success.
331 *      -DRM_NO_RIGHTS, when it has no rights.
332 *      -DRM_RIGHTS_PENDING, when it has the rights, but currently it is pending.
333 *      -DRM_RIGHTS_EXPIRED, when the rights has expired.
334 *      -DRM_FAILURE, when some other error occured.
335 */
336int32_t SVC_drm_updateRights(uint8_t* contentID, int32_t permission);
337
338/**
339 * Scan all the rights object in current DRM engine, and get all their information.
340 *
341 * \param ppRightsInfo  The pointer to the list structure to save rights info.
342 *
343 * \return
344 *      -DRM_SUCCESS, when get information successfully.
345 *      -DRM_FAILURE, when some other error occured.
346 */
347int32_t SVC_drm_viewAllRights(T_DRM_Rights_Info_Node **ppRightsInfo);
348
349/**
350 * Free the allocated memory when call "SVC_drm_viewAllRights".
351 *
352 * \param pRightsHeader The header pointer of the list to be free.
353 *
354 * \return
355 *      -DRM_SUCCESS, when free operation successfully.
356 *      -DRM_FAILURE, when some other error occured.
357 */
358int32_t SVC_drm_freeRightsInfoList(T_DRM_Rights_Info_Node *pRightsHeader);
359
360/**
361 * Delete a specify rights.
362 *
363 * \param roId      The unique id of the rights.
364 *
365 * \return
366 *      -DRM_SUCCESS, when free operation successfully.
367 *      -DRM_NO_RIGHTS, when there is not this rights object.
368 *      -DRM_FAILURE, when some other error occured.
369 */
370int32_t SVC_drm_deleteRights(uint8_t* roId);
371
372#ifdef __cplusplus
373}
374#endif
375
376#endif /* __SVC_DRM_NEW_H__ */
377