os/security/contentmgmt/cafstreamingsupport/inc/keystreamdecoder.h
author sl@SLION-WIN7.fritz.box
Fri, 15 Jun 2012 03:10:57 +0200
changeset 0 bde4ae8d615e
permissions -rw-r--r--
First public contribution.
sl@0
     1
// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0
     2
// All rights reserved.
sl@0
     3
// This component and the accompanying materials are made available
sl@0
     4
// under the terms of the License "Eclipse Public License v1.0"
sl@0
     5
// which accompanies this distribution, and is available
sl@0
     6
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0
     7
//
sl@0
     8
// Initial Contributors:
sl@0
     9
// Nokia Corporation - initial contribution.
sl@0
    10
//
sl@0
    11
// Contributors:
sl@0
    12
//
sl@0
    13
// Description:
sl@0
    14
//
sl@0
    15
sl@0
    16
/**
sl@0
    17
 @file
sl@0
    18
 @publishedPartner
sl@0
    19
 @released
sl@0
    20
*/
sl@0
    21
sl@0
    22
#ifndef KEYSTREAMDECODER_H
sl@0
    23
#define KEYSTREAMDECODER_H
sl@0
    24
sl@0
    25
#include <e32base.h>
sl@0
    26
#include <f32file.h>
sl@0
    27
#include <caf/importfile.h>
sl@0
    28
#include <caf/streaming/streamcaftypes.h>
sl@0
    29
sl@0
    30
class CSdpMediaField;
sl@0
    31
class CSdpDocument;
sl@0
    32
sl@0
    33
namespace StreamAccess
sl@0
    34
	{
sl@0
    35
	class CAgentKeyStreamDecoder;
sl@0
    36
	class CProtectedStreamDesc;
sl@0
    37
	class CStreamAgentFactory;
sl@0
    38
	class ContentAccess::CImportFile;
sl@0
    39
	/**
sl@0
    40
 	Allows clients to instantiate key stream decoders for short-term key streams in protected broadcasts.
sl@0
    41
	 
sl@0
    42
 	This class is initialised with an agent implementation that supports the standard with which the stream is protected.
sl@0
    43
 	*/
sl@0
    44
	class CKeyStreamDecoder : public CBase
sl@0
    45
		{
sl@0
    46
	public:
sl@0
    47
		/** 
sl@0
    48
		 Creates a new CKeyStreamDecoder object. 
sl@0
    49
sl@0
    50
		 Sample code pattern from a media controller for using this interface. (This sample assumes that the stream is protected using
sl@0
    51
		 IPSec. Similar code pattern can be used for other protection layers.)
sl@0
    52
sl@0
    53
		 @code
sl@0
    54
		 using namespace StreamAccess;
sl@0
    55
		 
sl@0
    56
		 // Create protected stream description by using the source and target connection addresses.
sl@0
    57
		 CIpSecProtectedStreamDesc *ipSecProtectedStreamDec = CIpSecProtectedStreamDesc::NewLC(sourceAddr, targetAddr);
sl@0
    58
		  
sl@0
    59
		 // Extract the relevant media field for the key stream
sl@0
    60
		 ...
sl@0
    61
		 // Now create the key stream decoder
sl@0
    62
		 CKeyStreamDecoder *keyStreamDecoder = CKeyStreamDecoder::NewLC(ipSecProtectedStreamDesc, keyStreamSDPDesc, sdpDocument);
sl@0
    63
		 // If we reached this point, then key stream decoder was initialized correctly, and if the user has rights to
sl@0
    64
		 // view the stream, it will get decrypted.
sl@0
    65
		 // If the user doesn't have the rights to view the stream (e.g. no rights for a specific pay-per-view program), 
sl@0
    66
		 // no cryptographic context will be set. In such case, the reason for lack of decryption can be queried via
sl@0
    67
		 // the GetAttributeL interface.
sl@0
    68
		 @endcode
sl@0
    69
		 
sl@0
    70
		 @param aProtectedStreamDesc Description of the protected media stream (e.g. a specific audio track, or the video channel). This parameter defines where the keys will be applied to. 
sl@0
    71
		 Description may vary according to the protection layer. For example, for IPSec it might be a subsession, while for ISMACryp a reference to the ISMACryp decoder
sl@0
    72
		 @param aSdpKeyStream Defines the parameters for the key stream. If several key streams are present (e.g. one for video protection, and one for audio protection), then
sl@0
    73
		 several CKeyStreamDecoder objects must be instantiated. If several key streams are available for the same media, then a key stream decoder should be
sl@0
    74
		 attempted for all of them - depending on the nature of the broadcast, some of these key streams might be optional or not.
sl@0
    75
		 For example, if SRTP is used for authentication and ISMACryp for encryption then there would be two key streams - both mandatory. 
sl@0
    76
		 On the other hand, if there are two alternative purchase options for the same service, there may be two corresponding key streams.
sl@0
    77
		 If no key stream decoder can be created, then the media stream cannot be decoded on the device.
sl@0
    78
		 @param aSdpDoc Description of the Session Description Protocol (SDP) document which contains all defined SDP fields and related values describing a session.
sl@0
    79
		 By using SDP document, agents can extract SDP connection field and other fields or attributes which they may need and which are not defined in the key stream
sl@0
    80
		 SDP media field.
sl@0
    81
		 @return The new CKeyStreamDecoder object.
sl@0
    82
		  
sl@0
    83
		 @leave	KErrCANoAgent	There is no agent on the device which can support the requested key management system.
sl@0
    84
		 @leave	...		One of the system-wide error codes.
sl@0
    85
sl@0
    86
         @capability	
sl@0
    87
		 Only processes with the DRM capability are able to instantiate key stream decoders.
sl@0
    88
		 If there is prior knowledge of the DRM agent handling this stream, the documentation for that DRM agent should also be consulted. 
sl@0
    89
		 */
sl@0
    90
		IMPORT_C static CKeyStreamDecoder* NewL(const CProtectedStreamDesc& aProtectedStreamDesc, const CSdpMediaField& aSdpKeyStream, const CSdpDocument& aSdpDoc);
sl@0
    91
sl@0
    92
		/** 
sl@0
    93
		 @see CKeyStreamDecoder::NewL()
sl@0
    94
		 */
sl@0
    95
		IMPORT_C static CKeyStreamDecoder* NewLC(const CProtectedStreamDesc& aProtectedStreamDesc, const CSdpMediaField& aSdpKeyStream, const CSdpDocument& aSdpDoc);
sl@0
    96
				
sl@0
    97
		 /**  Get an attribute for the service/content protection.
sl@0
    98
			  
sl@0
    99
		 @param aAttribute The attribute to query, from StreamAccess::TAttribute.
sl@0
   100
		 @param aValue [out] Used to return the attribute value.
sl@0
   101
		 @leave KErrCANotSupported if the requested attribute does not exist.
sl@0
   102
		 @leave Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0
   103
				other system-wide error codes for any other errors.
sl@0
   104
		 @capability Requires the DRM capability.
sl@0
   105
		 @see StreamAccess::TAttribute
sl@0
   106
		 */
sl@0
   107
		IMPORT_C void GetAttributeL(const TAttribute& aAttribute, TBool& aValue) const;
sl@0
   108
sl@0
   109
		 /**  Get text string attributes or meta-data for the service/content protection.
sl@0
   110
sl@0
   111
		 @param aAttribute The attribute to query, from StreamAccess::TStringAttribute.
sl@0
   112
		 @return A pointer to the value of the attribute. The pointer is put onto the cleanup stack.
sl@0
   113
		 @leave KErrCANotSupported if the requested attribute does not exist.
sl@0
   114
		 @leave Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 
sl@0
   115
		 		 other system-wide error codes for any other errors.
sl@0
   116
		 @capability Requires the DRM capability.
sl@0
   117
		 @see StreamAccess::TStringAttribute				 
sl@0
   118
		 */
sl@0
   119
		IMPORT_C HBufC* GetStringAttributeLC(const TStringAttribute& aAttribute) const;
sl@0
   120
		
sl@0
   121
		/**	Creates a new import session which is used to import the streamed content into a protected file
sl@0
   122
		    storage for later viewing.
sl@0
   123
		    
sl@0
   124
		    A corresponding rights object for post-acquisition protection is delivered automatically to 
sl@0
   125
		    the CAF agent. The returned session has to be closed when the recording has finished.
sl@0
   126
		    
sl@0
   127
		    If the agent requires a new output file it will return KErrCANewFileHandleRequired from 
sl@0
   128
		    @see ContentAccess::CImportFile::Write() or @see ContentAccess::CImportFile::WriteComplete().
sl@0
   129
		    The application using this API should provide the agent with a new file handle using 
sl@0
   130
		    ContentAccess::CImportFile::ContinueWithNewOutputFile().
sl@0
   131
			
sl@0
   132
		    @param aContentMimeType The mime type of the content which is recorded (e.g. video/3gpp).
sl@0
   133
		    @return A CImportFile object to import the protected streamed content. 
sl@0
   134
		    		The newly created object is left on the cleanup stack.
sl@0
   135
		 	@leave KErrCANoAgent	No agent supports recording a protected streamed content.
sl@0
   136
		 	@leave KErrCANotSupported if the protection scheme does not have or is not capable of exporting rights info. 
sl@0
   137
		 	@leave Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the other system-wide 
sl@0
   138
		 	       error codes for any other errors.	
sl@0
   139
		 	@capability Requires the DRM capability.
sl@0
   140
		 */
sl@0
   141
		IMPORT_C ContentAccess::CImportFile* CreateImportSessionLC(const TDesC8& aContentMimeType) const;
sl@0
   142
		
sl@0
   143
		/**	Creates a new import session which is used to import the streamed content into a protected file
sl@0
   144
		    storage for later viewing.
sl@0
   145
		    
sl@0
   146
		    A corresponding rights object for post-acquisition protection is delivered automatically to 
sl@0
   147
		    the CAF agent. The returned session has to be closed when the recording has finished.
sl@0
   148
		    
sl@0
   149
		    @param aContentMimeType The mime type of the content which is recorded (e.g. video/3gpp).
sl@0
   150
		    @param aSuggestedFileName  Suggested filename for the CAF agent to use when creating the output file for
sl@0
   151
		    					   the content being recorded. Details of the output files produced can be obtained 
sl@0
   152
		    					   using ContentAccess::CImportFile::OutputFileL().
sl@0
   153
		    @param aOutputDirectory The preferred location to store the protected streaming content.
sl@0
   154
		    @return A CImportFile object to import the protected streamed content. 
sl@0
   155
		    		The newly created object is left on the cleanup stack.
sl@0
   156
		 	@leave KErrCANoAgent	No agent supports recording a protected streamed content.
sl@0
   157
		 	@leave KErrCANotSupported if the protection scheme does not have or is not capable of exporting rights info. 
sl@0
   158
		 	@leave Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the other system-wide 
sl@0
   159
		 	       error codes for any other errors.	
sl@0
   160
		 	@capability Requires the DRM capability.
sl@0
   161
		 */
sl@0
   162
		IMPORT_C ContentAccess::CImportFile* CreateImportSessionLC(const TDesC8& aContentMimeType, const TDesC& aSuggestedFileName, const TDesC& aOutputDirectory) const;
sl@0
   163
		
sl@0
   164
		// Destructor
sl@0
   165
		~CKeyStreamDecoder();
sl@0
   166
		
sl@0
   167
	protected:
sl@0
   168
		// Constructor
sl@0
   169
		CKeyStreamDecoder();
sl@0
   170
	
sl@0
   171
		// Second phase constructor
sl@0
   172
		void ConstructL(const CProtectedStreamDesc& aProtectedStreamDesc, const CSdpMediaField& aSdpKeyStream, const CSdpDocument& aSdpDoc);
sl@0
   173
	
sl@0
   174
	private:
sl@0
   175
		ContentAccess::CImportFile* DoCreateImportSessionLC(const TDesC8& aContentMimeType, const TDesC& aSuggestedName, const TDesC& aOutputDirectory) const;
sl@0
   176
	
sl@0
   177
	private:
sl@0
   178
		// Pointer to the resolved agent key stream decoder
sl@0
   179
		CAgentKeyStreamDecoder* iAgentKeyStreamDecoder;			
sl@0
   180
		
sl@0
   181
		// Handle to the factory of the resolved stream agent is required in order to successfully cleanup
sl@0
   182
		// the factory instance during destruction.
sl@0
   183
		CStreamAgentFactory *iStreamAgentFactory;
sl@0
   184
		
sl@0
   185
		// ECOM session key. This is set by REComSession::CreateImplementationL() during construction
sl@0
   186
		TUid iEcomKey;
sl@0
   187
		};
sl@0
   188
	/** 
sl@0
   189
	 	The maximum length of a mime type string. Agents should not use mime types and content IDs 
sl@0
   190
	 	which is longer than this value.
sl@0
   191
	 */
sl@0
   192
	const TInt KMimeTypesMaxLength = 512;
sl@0
   193
		
sl@0
   194
	} // namespace StreamAccess
sl@0
   195
#endif // KEYSTREAMDECODER_H