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