1 /*

     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Declaration of class DRMCommon for accessing common

    15 *                DRM functions

    16 *

    17 */

    18 

    19 

    20 #ifndef DRMCOMMON_H

    21 #define DRMCOMMON_H

    22 

    23 #include <e32base.h>

    24 #include <DrmRights.h>

    25 #include <caf/caf.h>

    26 

    27 const TUint KDrmMaxContentInfoSize = 512;

    28 

    29 // FORWARD DECLARATIONS

    30 class TDataType;

    31 

    32 // CLASS DECLARATION

    33 

    34 /**

    35 *  DRMCommon: provides common DRM functions.

    36 *

    37 *  @lib    DRMCommon.dll

    38 *  @since  2.0

    39 */

    40 class DRMCommon: public CBase

    41     {

    42 public:     // Data Types

    43     enum

    44         {

    45         EPlay = ContentAccess::EPlay,

    46         EDisplay = ContentAccess::EView, 

    47         EExecute = ContentAccess::EExecute, 

    48         EPrint = ContentAccess::EPrint, 

    49         EInstall = ContentAccess::EInstall, 

    50         };

    51 

    52     enum TConsumeAction

    53         {

    54         EStart,

    55         EFinish,

    56         };

    57     

    58     enum

    59         {

    60         EOk = KErrNone, 

    61         EGeneralError = -30100, 

    62         EUnknownMIME = -30101, 

    63         EVersionNotSupported = -30102, 

    64         ESessionError = -30103, 

    65         ENoRights = KErrCANoRights, 

    66         ERightsDBCorrupted = -30105, 

    67         EUnsupported = KErrCANotSupported, 

    68         ERightsExpired = KErrCANoPermission, 

    69         EInvalidRights = -30108,

    70         EPaddingFailed = -30109,

    71         EFileError = -30110

    72         };

    73     

    74     enum TContentProtection

    75         {

    76         ENoDCFFile, 

    77         EForwardLocked, 

    78         ESuperDistributable

    79         };

    80     

    81     enum TOMALevel

    82         {

    83         EOMA_None, 

    84         EOMA_1_0,

    85         EOMA_2_0

    86         };

    87     

    88     enum

    89         {

    90         EForwardLock = 0x0001, 

    91         ECombinedDelivery = 0x0002, 

    92         ESeparateDelivery = 0x0004, 

    93         ESuperDistribution = 0x0008

    94         };

    95     

    96 public:  // Constructors and destructor

    97     

    98     /**

    99     * Two-phased constructor.

   100     */

   101     IMPORT_C static DRMCommon* NewL(void);

   102     

   103     /**

   104     * Destructor.

   105     */

   106     IMPORT_C virtual ~DRMCommon(void);

   107     

   108     public: // New functions

   109     

   110     /**

   111     * Version

   112     *

   113     * Returns the version of this API.

   114     *

   115     * @since  2.0

   116     * @return Version of the API

   117     */

   118     IMPORT_C static TVersion Version(void);

   119     

   120     /**

   121     * ServerVersion

   122     * 

   123     * Returns the version of the DRM Engine.

   124     *

   125     * @since  2.0

   126     * @return Version of the DRM Engine

   127     */

   128     IMPORT_C static TVersion ServerVersion(void);

   129     

   130     /**

   131     * Connect

   132     *

   133     * Connect to the DRM Engine.

   134     *

   135     * @since  2.0

   136     * @return EOk if the connection has been made

   137     */

   138     IMPORT_C TInt Connect(void);

   139     

   140     /**

   141     * Disconnect

   142     *

   143     * Disconnect the current connection.

   144     *

   145     * @since  2.0

   146     * @return EOk if the connection has been disconnected

   147     */

   148     IMPORT_C TInt Disconnect(void);

   149     

   150     /**

   151     * CheckContentRights

   152     * 

   153     * Takes a Content URI and a rights specification.

   154     * Checks if the specified rights can be exercised with this content 

   155     * by looking up the content URI in the rights database and checking

   156     * the stored rights.

   157     *

   158     * @since  2.0

   159     * @param  aContentURI: the content URI of the content to be tested

   160     * @param  aRightsSpec: The rights to be checked defined as a bitmask

   161     *         combination of EPlay, EDisplay, EExecute and EPrint

   162     * @return EOk if all of the given rights can be exercised, otherwise

   163     *         or if the content URI cannot be found, ENoRights

   164     */

   165     IMPORT_C TInt CheckContentRights(

   166         const TDesC8& aContentURI, 

   167         TUint32 aRightsSpec);

   168     

   169     /**

   170     * CheckFileRights

   171     *

   172     * Takes a file name and a rights specification. Opens the given file

   173     * and checks if the specified rights can be exercised with this file 

   174     * by extracting the content URI from the file, looking up the content

   175     * URI in the rights database and checking the stored rights.

   176     *

   177     * @since  2.0

   178     * @param  aFileName: the name of the file to be tested.

   179     * @param  aRightsSpec: The rights to be checked defined as a bitmask

   180     *         combination of EPlay, EDisplay, EExecute and EPrint

   181     * @return EOk if all of the given rights can be exercised, otherwise

   182     *         or if the file is not a DCF file or if the content URI cannot

   183     *         be found, ENoRights

   184     */

   185     IMPORT_C TInt CheckFileRights(

   186         const TDesC& aFileName, 

   187         TUint32 aRightsSpec);

   188 

   189     /**

   190     * CheckFileRights

   191     *

   192     * Takes a file name and a rights specification. Opens the given file

   193     * and checks if the specified rights can be exercised with this file 

   194     * by extracting the content URI from the file, looking up the content

   195     * URI in the rights database and checking the stored rights.

   196     *

   197     * @since  3.0

   198     * @param  aFileHandle: file handle to the file.

   199     * @param  aRightsSpec: The rights to be checked defined as a bitmask

   200     *         combination of EPlay, EDisplay, EExecute and EPrint

   201     * @return EOk if all of the given rights can be exercised, otherwise

   202     *         or if the file is not a DCF file or if the content URI cannot

   203     *         be found, ENoRights

   204     */

   205     IMPORT_C TInt CheckFileRights(

   206         RFile& aFileHandle, 

   207         TUint32 aRightsSpec);

   208     

   209     /**

   210     * IsProtectedContent

   211     *

   212     * Takes a memory buffer containing a file and checks if it is a DCF file

   213     * or a regular file.

   214     *

   215     * @since  2.0

   216     * @param  aContent: memory buffer containing a file

   217     * @param  aProtection: return parameter, true if the file is a DCF file

   218     * @return EOk if the content could be checked.

   219     */

   220     IMPORT_C TInt IsProtectedContent(

   221         const TDesC8& aContent, 

   222         TBool& aProtection);

   223     

   224     /**

   225     * IsProtectedFile

   226     *

   227     * Takes a file name and checks if it is a DCF file or a regular file.

   228     *

   229     * @since  2.0

   230     * @param  aFileName: the name of the file to be tested.

   231     * @param  aProtection: return parameter, true if the file is a DCF file

   232     * @return EOk if the content could be checked.

   233     */

   234     IMPORT_C TInt IsProtectedFile(

   235         const TDesC& aFileName, 

   236         TBool& aProtection);

   237 

   238     /**

   239     * IsProtectedFile

   240     *

   241     * Takes a file name and checks if it is a DCF file or a regular file.

   242     *

   243     * @since  3.0

   244     * @param  aFileHandle: handle to the file to be tested.

   245     * @param  aProtection: return parameter, true if the file is a DCF file

   246     * @return EOk if the content could be checked.

   247     */

   248     IMPORT_C TInt IsProtectedFile(

   249         RFile& aFileHandle, 

   250         TBool& aProtection);

   251     

   252     /**

   253     * GetContentInfo

   254     *

   255     * Takes a memory buffer containing a DCF(or at least the header part

   256         * of it) and returns the protection for this content, the MIME type, 

   257     * Content URI and encrypted data length in out parameters.

   258     *

   259     * @since  2.0

   260     * @param  aContent: memory buffer containing a DCF

   261     * @param  aProtection: return parameter for the type of protection for

   262     *         this DCF

   263     * @param  aMIMEType: return parameter for the MIME type header field

   264     * @param  aContentURI: return parameter for the content URI header field

   265     * @param  aDataLength: return parameter for the length of the encrypted

   266     *         data

   267     * @return EOk if the information could be extracted from the DCF

   268     */

   269     IMPORT_C TInt GetContentInfo(

   270         const TDesC8& aContent, 

   271         TContentProtection& aProtection, 

   272         HBufC8*& aMIMEType, 

   273         HBufC8*& aContentURI, 

   274         TUint& aDataLength);

   275     

   276     /**

   277     * GetFileInfo

   278     * 

   279     * Takes the name of a DCF file, opens it and returns the protection for

   280     * this content, the MIME type, Content URI and encrypted data length in

   281     * out parameters.

   282     *

   283     * @since  2.0

   284     * @param  aFileName: the name of the file to be inspected

   285     * @param  aProtection: return parameter for the type of protection for

   286     *         this DCF

   287     * @param  aMIMEType: return parameter for the MIME type header field

   288     * @param  aContentURI: return parameter for the content URI header field

   289     * @param  aDataLength: return parameter for the length of the encrypted

   290     *         data

   291     * @return EOk if the information could be extracted from the DCF

   292     */

   293     IMPORT_C TInt GetFileInfo(

   294         const TDesC& aFileName, 

   295         TContentProtection& aProtection, 

   296         HBufC8*& aMIMEType, 

   297         HBufC8*& aContentURI, 

   298         TUint& aDataLength);

   299 

   300     /**

   301     * GetFileInfo

   302     * 

   303     * Takes the name of a DCF file, opens it and returns the protection for

   304     * this content, the MIME type, Content URI and encrypted data length in

   305     * out parameters.

   306     *

   307     * @since  3.0

   308     * @param  aFileHandle: handle to the file to be inspected

   309     * @param  aProtection: return parameter for the type of protection for

   310     *         this DCF

   311     * @param  aMIMEType: return parameter for the MIME type header field

   312     * @param  aContentURI: return parameter for the content URI header field

   313     * @param  aDataLength: return parameter for the length of the encrypted

   314     *         data

   315     * @return EOk if the information could be extracted from the DCF

   316     */

   317     IMPORT_C TInt GetFileInfo(

   318         RFile& aFileHandle, 

   319         TContentProtection& aProtection, 

   320         HBufC8*& aMIMEType, 

   321         HBufC8*& aContentURI, 

   322         TUint& aDataLength);

   323     

   324     /**

   325     * GetContentHeader

   326     *

   327     * Takes a memory buffer containing a DCF(or at least the header part of

   328     * it) and a header name and returns the value of the header field in an

   329     * out parameter. Return value specifies if the header has been found.

   330     * Search is case insensitive.

   331     *

   332     * @since  2.0

   333     * @param  aContent: memory buffer containing a DCF

   334     * @param  aHeaderName: Name of the header to look for

   335     * @param  aHeaderValue: return parameter for value of the header

   336     * @return EOk if the header was found

   337     */

   338     IMPORT_C TInt GetContentHeader(

   339         const TDesC8& aContent, 

   340         const TDesC8& aHeaderName, 

   341         HBufC8*& aHeaderValue);

   342     

   343     /**

   344     * GetFileHeader

   345     *

   346     * Takes the name of a DCF file and a header name, opens the DCF file and

   347     * returns the value of the header field in an out parameter. Return value

   348     * specifies if the header has been found. Search is case insensitive.

   349     *

   350     * @since  2.0

   351     * @param  aFileName: the name of the DCF file to be opened

   352     * @param  aHeaderName: Name of the header to look for

   353     * @param  aHeaderValue: return parameter for value of the header

   354     * @return EOk if the header was found

   355     */

   356     IMPORT_C TInt GetFileHeader(

   357         const TFileName& aFileName, 

   358         const TDesC8& aHeaderName, 

   359         HBufC8*& aHeaderValue);

   360  

   361     /**

   362     * GetFileHeader

   363     *

   364     * Takes the name of a DCF file and a header name, opens the DCF file and

   365     * returns the value of the header field in an out parameter. Return value

   366     * specifies if the header has been found. Search is case insensitive.

   367     *

   368     * @since  3.0

   369     * @param  aFileHandle: handle to the DCF file

   370     * @param  aHeaderName: Name of the header to look for

   371     * @param  aHeaderValue: return parameter for value of the header

   372     * @return EOk if the header was found

   373     */

   374     IMPORT_C TInt GetFileHeader(

   375         RFile& aFileHandle, 

   376         const TDesC8& aHeaderName, 

   377         HBufC8*& aHeaderValue);

   378     

   379     /**

   380     * SetContentHeader

   381     *

   382     * Takes a memory buffer containing a DCF(or at least the header part of

   383         * it), a header name and the value for the header field. Sets the header

   384     * field in the optional DCF header. If the header field has not existed

   385     * before, it is created. Any previous value of the header field will be

   386     * overwritten.

   387     *

   388     * @since  2.0

   389     * @param  aContent: memory buffer containing a DCF

   390     * @param  aHeaderName: Name of the header to set

   391     * @param  aHeaderValue: New value of the heade

   392     * @return EOk if the header was set.

   393     */

   394     IMPORT_C TInt SetContentHeader(

   395         HBufC8*& aContent, 

   396         const TDesC8& aHeaderName, 

   397         const TDesC8& aHeaderValue);

   398     

   399     /**

   400     * SetFileHeader

   401     *

   402     * Takes the name of a DCF file, a header name and the value for the header

   403     * field. Opens the DCF file, sets the header field in the optional DCF

   404     * header and writes the DCF file. If the header field has not existed

   405     * before, it is created. Any previous value of the header field will be

   406     * overwritten.

   407     *

   408     * @since  2.0

   409     * @param  aFileName: the name of the DCF file to be opened

   410     * @param  aHeaderName: Name of the header to set

   411     * @param  aHeaderValue: New value of the heade

   412     * @return EOk if the header was set.

   413     */

   414     IMPORT_C TInt SetFileHeader(

   415         const TDesC16& aFileName, 

   416         const TDesC8& aHeaderName, 

   417         const TDesC8& aHeaderValue);

   418 

   419     /**

   420     * SetFileHeader

   421     *

   422     * Takes the name of a DCF file, a header name and the value for the header

   423     * field. Opens the DCF file, sets the header field in the optional DCF

   424     * header and writes the DCF file. If the header field has not existed

   425     * before, it is created. Any previous value of the header field will be

   426     * overwritten.

   427     *

   428     * @since  3.0

   429     * @param  aFileHandle: handle to the DCF file

   430     * @param  aHeaderName: Name of the header to set

   431     * @param  aHeaderValue: New value of the heade

   432     * @return EOk if the header was set.

   433     */

   434     IMPORT_C TInt SetFileHeader(

   435         RFile& aFileHandle, 

   436         const TDesC8& aHeaderName, 

   437         const TDesC8& aHeaderValue);

   438 

   439     /**

   440     * GetSingleRightsObject

   441     *

   442     * Takes a content URI, a local ID and a rights object out parameter.

   443     * Looks up the rights object using the content URI and the local ID

   444     * and returns it in the out parameter.

   445     *

   446     * @since  2.5

   447     * @param  aContentURI: the content URI of the content to be tested.

   448     * @param  aLocalID: local ID of the rights object

   449     * @param  aRightsObject: Out parameter for the rights object. It has

   450     *         to be released by the caller.

   451     * @return EOk if the rights object could be retreived, ENoRights if

   452     *         no rights object exists.

   453     */

   454     IMPORT_C TInt GetSingleRightsObject(

   455         const TDesC8& aContentURI, 

   456         TUint32 aLocalID, 

   457         CDRMRights*& aRightsObject);

   458     

   459     /**

   460     * GetDetailedContentRights

   461     *

   462     * Takes a Content URI and an array out parameter. Fills the rights

   463     * specification array with the available rights by looking up the content

   464     * URI in the rights database and retrieving the stored rights. The array

   465     * parameter will contain a list of pointers to all rights object for the 

   466     * given content URI. The rights objects themselves can be distinguished by

   467     * their local ID.

   468     *

   469     * @since  2.5

   470     * @param  aContentURI: the content URI of the content to be tested.

   471     * @param  aRightsList: Out parameter for the available rights. It has to

   472     *         be released by the caller.

   473     * @return EOk if the rights could be retreived, ENoRights if no rights 

   474     *         object exists.

   475     */

   476     IMPORT_C TInt GetDetailedContentRights(

   477         const TDesC8& aContentURI, 

   478         RPointerArray<CDRMRights>*& aRightsList);

   479     

   480     /**

   481     * GetDetailedFileRights

   482     *

   483     * Takes a file name and a rights specification. Opens the given file and 

   484     * fills the rights specification array with the available rights by

   485     * looking up the content URI in the rights database and retrieving the

   486     * stored rights. The array parameter will contain a list of pointers to

   487     * all rights object for the given content URI. The rights objects

   488     * themselves can be distinguished by their local ID.

   489     *

   490     * @since  2.5

   491     * @param  aFileName: the name of the file to be tested.

   492     * @param  aRightsList: Out parameter for the available rights.

   493     * @return EOk if the rights could be retreived, if the file is not a DCF

   494     *         file or if the content URI cannot be found, ENoRights.

   495     */

   496     IMPORT_C TInt GetDetailedFileRights(

   497         const TDesC& aFileName, 

   498         RPointerArray<CDRMRights>*& aRightsList);

   499 

   500     /**

   501     * GetDetailedFileRights

   502     *

   503     * Takes a file name and a rights specification. Opens the given file and 

   504     * fills the rights specification array with the available rights by

   505     * looking up the content URI in the rights database and retrieving the

   506     * stored rights. The array parameter will contain a list of pointers to

   507     * all rights object for the given content URI. The rights objects

   508     * themselves can be distinguished by their local ID.

   509     *

   510     * @since  3.0

   511     * @param  aFileHandle: handle to the file to be tested.

   512     * @param  aRightsList: Out parameter for the available rights.

   513     * @return EOk if the rights could be retreived, if the file is not a DCF

   514     *         file or if the content URI cannot be found, ENoRights.

   515     */

   516     IMPORT_C TInt GetDetailedFileRights(

   517         RFile& aFileHandle, 

   518         RPointerArray<CDRMRights>*& aRightsList);

   519     

   520     /**

   521     * GetActiveRights

   522     *

   523     * Takes a Content URI and a rights specification. Finds all rights objects

   524     * associated with given URI and returns a possible active one. The out 

   525     * parameters will contain a pointer to the found rights object. The found

   526     * rights object can be expired. The details about expiration and constraints

   527     * of the rights can be retrieved with the CDRMRights::GetRightsInfo function. 

   528     *

   529     * @since  2.5

   530     * @param  aContentURI: the content URI of the content to be tested.

   531     * @param  aRightsSpec: The rights to be checked defined as a bitmask

   532     *		  combination of EPlay, EDisplay, EExecute and EPrint

   533     * @param  aRightsObject: Out parameter for the rights object. It has

   534     *         to be released by the caller.

   535     * @return EFullRights, ERestrictedRights, EPreviewRights if a possble active

   536     *         rights object was found. ENoRights if no rights object for given 

   537     *         content URI or permissions.

   538     */

   539     IMPORT_C TInt GetActiveRights(

   540         const TDesC8& aContentURI,

   541         TUint32 aRightsSpec,

   542         CDRMRights*& aRightsObject);

   543     

   544     /**

   545     * GetContentURIList

   546     *

   547     * Returns a list of all content URIs that have rights in the rights 

   548     * database.

   549     *

   550     * @since  2.5

   551     * @param  aURIList: Out parameter for the URI list.

   552     * @return Ok if the URI list could be retreived.

   553     */

   554     IMPORT_C TInt GetContentURIList(

   555         RPointerArray<HBufC8>*& aURIList);

   556     

   557     /**

   558     * DataTypesCount

   559     *

   560     * Returns the number of previously registered datatypes which are

   561     * supported by the DRM system and associated applications.

   562     *

   563     * @since  2.0

   564     * @param  aCount: Out parameter for the datatype count

   565     * @return EOk if the number of datatypes has been returned correctly

   566     */

   567     IMPORT_C TInt DataTypesCount(

   568         TInt& aCount);

   569     

   570     /**

   571     * SupportedDataType

   572     *

   573     * Returns a specific datatype which has been registered before by giving an index

   574     *

   575     * @since  2.0

   576     * @param  aIndex: Number of the datatype to return

   577     * @param  aDataType: Out parameter for the datatype

   578     * @return EOk if the datatype was returned correctly

   579     */

   580     

   581     IMPORT_C TInt SupportedDataType(

   582         const TInt aIndex, TDataType& aDataType);

   583     

   584     /**

   585     * StaticDataTypesCount

   586     *

   587     * Returns the number of default registered datatypes which are

   588     * supported by the DRM system and associated applications.

   589     *

   590     * @since  2.0

   591     * @param  aCount: Out parameter for the static datatype count

   592     * @return EOk if the number of datatypes has been returned correctly

   593     */

   594     IMPORT_C TInt StaticDataTypesCount(

   595         TInt& aCount);

   596     

   597     /**

   598     * RegisterDataType

   599     *

   600     * Registers a datatype as a supported datatype.

   601     *

   602     * @since  2.0

   603     * @param  aDataType: Datatype to register

   604     * @return EOk if the datatype has been registered

   605     */

   606     

   607     IMPORT_C TInt RegisterDataType(

   608         const TDataType& aDataType);

   609     

   610     /**

   611     * UnRegisterDataType

   612     *

   613     * Unregisters a datatype via its index.

   614     *

   615     * @since  2.5

   616     * @param  aIndex: Number of the datatype to unregister

   617     * @return EOk if the datatype has been unregistered

   618     */

   619     

   620     IMPORT_C TInt UnRegisterDataType(

   621         const TInt aIndex);

   622     

   623     /**

   624     * SupportedDRMMethods

   625     *

   626     * Returns the supported DRM protection methods and the OMA compliance

   627     * level of the DRM engine

   628     *

   629     * @since  2.0

   630     * @param  aDRMMethod: Out parameter, bit mask containing any 

   631     *         combination of EForwardLock, ECombinedDelivery, 

   632     *         ESeparateDelivery etc.

   633     * @param  aOMALevel: OMA compliance of the DRM engine

   634     * @return DRMCommon error code

   635     */

   636     

   637     IMPORT_C TInt SupportedDRMMethods(

   638         TInt& aDRMMethod, TOMALevel& aOMALevel);

   639         

   640     /**

   641     * MergeParentAndChild

   642     *

   643     * Merge rights with their parent rights

   644     *

   645     * @since  3.0

   646     * @param  aRights Rights to be merged with their parent rights

   647     */

   648 

   649     IMPORT_C void MergeParentAndChild(CDRMRights* aRights);

   650         

   651     

   652     

   653 protected:

   654     

   655     /**

   656     * C++ default constructor.

   657     */

   658     IMPORT_C DRMCommon(void);

   659     

   660     /**

   661     * 2nd phase constructor.

   662     */

   663     IMPORT_C void ConstructL(void);

   664     

   665     /**

   666     * MapErrorCode

   667     *

   668     * Maps the error codes returned by the core engine to DRMCommon

   669     * error codes.

   670     *

   671     * @since  2.5

   672     * @param  aCode: core error code

   673     * @return DRMCommon error code.

   674     */

   675     IMPORT_C TInt MapErrorCode(

   676         const TInt aCode);

   677     

   678     };

   679 

   680 #endif      // DRMCOMMON_H   

   681 

   682 // End of File