--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/contentmgmt/cafstreamingsupport/inc/keystreamdecoder.h Mon Mar 15 12:46:43 2010 +0200
@@ -0,0 +1,195 @@
+// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of the License "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+//
+
+/**
+ @file
+ @publishedPartner
+ @released
+*/
+
+#ifndef KEYSTREAMDECODER_H
+#define KEYSTREAMDECODER_H
+
+#include <e32base.h>
+#include <f32file.h>
+#include <caf/importfile.h>
+#include <caf/streaming/streamcaftypes.h>
+
+class CSdpMediaField;
+class CSdpDocument;
+
+namespace StreamAccess
+ {
+ class CAgentKeyStreamDecoder;
+ class CProtectedStreamDesc;
+ class CStreamAgentFactory;
+ class ContentAccess::CImportFile;
+ /**
+ Allows clients to instantiate key stream decoders for short-term key streams in protected broadcasts.
+
+ This class is initialised with an agent implementation that supports the standard with which the stream is protected.
+ */
+ class CKeyStreamDecoder : public CBase
+ {
+ public:
+ /**
+ Creates a new CKeyStreamDecoder object.
+
+ Sample code pattern from a media controller for using this interface. (This sample assumes that the stream is protected using
+ IPSec. Similar code pattern can be used for other protection layers.)
+
+ @code
+ using namespace StreamAccess;
+
+ // Create protected stream description by using the source and target connection addresses.
+ CIpSecProtectedStreamDesc *ipSecProtectedStreamDec = CIpSecProtectedStreamDesc::NewLC(sourceAddr, targetAddr);
+
+ // Extract the relevant media field for the key stream
+ ...
+ // Now create the key stream decoder
+ CKeyStreamDecoder *keyStreamDecoder = CKeyStreamDecoder::NewLC(ipSecProtectedStreamDesc, keyStreamSDPDesc, sdpDocument);
+ // If we reached this point, then key stream decoder was initialized correctly, and if the user has rights to
+ // view the stream, it will get decrypted.
+ // If the user doesn't have the rights to view the stream (e.g. no rights for a specific pay-per-view program),
+ // no cryptographic context will be set. In such case, the reason for lack of decryption can be queried via
+ // the GetAttributeL interface.
+ @endcode
+
+ @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.
+ 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
+ @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
+ several CKeyStreamDecoder objects must be instantiated. If several key streams are available for the same media, then a key stream decoder should be
+ attempted for all of them - depending on the nature of the broadcast, some of these key streams might be optional or not.
+ For example, if SRTP is used for authentication and ISMACryp for encryption then there would be two key streams - both mandatory.
+ On the other hand, if there are two alternative purchase options for the same service, there may be two corresponding key streams.
+ If no key stream decoder can be created, then the media stream cannot be decoded on the device.
+ @param aSdpDoc Description of the Session Description Protocol (SDP) document which contains all defined SDP fields and related values describing a session.
+ 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
+ SDP media field.
+ @return The new CKeyStreamDecoder object.
+
+ @leave KErrCANoAgent There is no agent on the device which can support the requested key management system.
+ @leave ... One of the system-wide error codes.
+
+ @capability
+ Only processes with the DRM capability are able to instantiate key stream decoders.
+ If there is prior knowledge of the DRM agent handling this stream, the documentation for that DRM agent should also be consulted.
+ */
+ IMPORT_C static CKeyStreamDecoder* NewL(const CProtectedStreamDesc& aProtectedStreamDesc, const CSdpMediaField& aSdpKeyStream, const CSdpDocument& aSdpDoc);
+
+ /**
+ @see CKeyStreamDecoder::NewL()
+ */
+ IMPORT_C static CKeyStreamDecoder* NewLC(const CProtectedStreamDesc& aProtectedStreamDesc, const CSdpMediaField& aSdpKeyStream, const CSdpDocument& aSdpDoc);
+
+ /** Get an attribute for the service/content protection.
+
+ @param aAttribute The attribute to query, from StreamAccess::TAttribute.
+ @param aValue [out] Used to return the attribute value.
+ @leave KErrCANotSupported if the requested attribute does not exist.
+ @leave Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
+ other system-wide error codes for any other errors.
+ @capability Requires the DRM capability.
+ @see StreamAccess::TAttribute
+ */
+ IMPORT_C void GetAttributeL(const TAttribute& aAttribute, TBool& aValue) const;
+
+ /** Get text string attributes or meta-data for the service/content protection.
+
+ @param aAttribute The attribute to query, from StreamAccess::TStringAttribute.
+ @return A pointer to the value of the attribute. The pointer is put onto the cleanup stack.
+ @leave KErrCANotSupported if the requested attribute does not exist.
+ @leave Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
+ other system-wide error codes for any other errors.
+ @capability Requires the DRM capability.
+ @see StreamAccess::TStringAttribute
+ */
+ IMPORT_C HBufC* GetStringAttributeLC(const TStringAttribute& aAttribute) const;
+
+ /** Creates a new import session which is used to import the streamed content into a protected file
+ storage for later viewing.
+
+ A corresponding rights object for post-acquisition protection is delivered automatically to
+ the CAF agent. The returned session has to be closed when the recording has finished.
+
+ If the agent requires a new output file it will return KErrCANewFileHandleRequired from
+ @see ContentAccess::CImportFile::Write() or @see ContentAccess::CImportFile::WriteComplete().
+ The application using this API should provide the agent with a new file handle using
+ ContentAccess::CImportFile::ContinueWithNewOutputFile().
+
+ @param aContentMimeType The mime type of the content which is recorded (e.g. video/3gpp).
+ @return A CImportFile object to import the protected streamed content.
+ The newly created object is left on the cleanup stack.
+ @leave KErrCANoAgent No agent supports recording a protected streamed content.
+ @leave KErrCANotSupported if the protection scheme does not have or is not capable of exporting rights info.
+ @leave Otherwise one of the other CAF error codes defined in \c caferr.h or one of the other system-wide
+ error codes for any other errors.
+ @capability Requires the DRM capability.
+ */
+ IMPORT_C ContentAccess::CImportFile* CreateImportSessionLC(const TDesC8& aContentMimeType) const;
+
+ /** Creates a new import session which is used to import the streamed content into a protected file
+ storage for later viewing.
+
+ A corresponding rights object for post-acquisition protection is delivered automatically to
+ the CAF agent. The returned session has to be closed when the recording has finished.
+
+ @param aContentMimeType The mime type of the content which is recorded (e.g. video/3gpp).
+ @param aSuggestedFileName Suggested filename for the CAF agent to use when creating the output file for
+ the content being recorded. Details of the output files produced can be obtained
+ using ContentAccess::CImportFile::OutputFileL().
+ @param aOutputDirectory The preferred location to store the protected streaming content.
+ @return A CImportFile object to import the protected streamed content.
+ The newly created object is left on the cleanup stack.
+ @leave KErrCANoAgent No agent supports recording a protected streamed content.
+ @leave KErrCANotSupported if the protection scheme does not have or is not capable of exporting rights info.
+ @leave Otherwise one of the other CAF error codes defined in \c caferr.h or one of the other system-wide
+ error codes for any other errors.
+ @capability Requires the DRM capability.
+ */
+ IMPORT_C ContentAccess::CImportFile* CreateImportSessionLC(const TDesC8& aContentMimeType, const TDesC& aSuggestedFileName, const TDesC& aOutputDirectory) const;
+
+ // Destructor
+ ~CKeyStreamDecoder();
+
+ protected:
+ // Constructor
+ CKeyStreamDecoder();
+
+ // Second phase constructor
+ void ConstructL(const CProtectedStreamDesc& aProtectedStreamDesc, const CSdpMediaField& aSdpKeyStream, const CSdpDocument& aSdpDoc);
+
+ private:
+ ContentAccess::CImportFile* DoCreateImportSessionLC(const TDesC8& aContentMimeType, const TDesC& aSuggestedName, const TDesC& aOutputDirectory) const;
+
+ private:
+ // Pointer to the resolved agent key stream decoder
+ CAgentKeyStreamDecoder* iAgentKeyStreamDecoder;
+
+ // Handle to the factory of the resolved stream agent is required in order to successfully cleanup
+ // the factory instance during destruction.
+ CStreamAgentFactory *iStreamAgentFactory;
+
+ // ECOM session key. This is set by REComSession::CreateImplementationL() during construction
+ TUid iEcomKey;
+ };
+ /**
+ The maximum length of a mime type string. Agents should not use mime types and content IDs
+ which is longer than this value.
+ */
+ const TInt KMimeTypesMaxLength = 512;
+
+ } // namespace StreamAccess
+#endif // KEYSTREAMDECODER_H