1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/security/contentmgmt/cafstreamingsupport/inc/keystreamdecoder.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,195 @@
1.4 +// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +/**
1.20 + @file
1.21 + @publishedPartner
1.22 + @released
1.23 +*/
1.24 +
1.25 +#ifndef KEYSTREAMDECODER_H
1.26 +#define KEYSTREAMDECODER_H
1.27 +
1.28 +#include <e32base.h>
1.29 +#include <f32file.h>
1.30 +#include <caf/importfile.h>
1.31 +#include <caf/streaming/streamcaftypes.h>
1.32 +
1.33 +class CSdpMediaField;
1.34 +class CSdpDocument;
1.35 +
1.36 +namespace StreamAccess
1.37 + {
1.38 + class CAgentKeyStreamDecoder;
1.39 + class CProtectedStreamDesc;
1.40 + class CStreamAgentFactory;
1.41 + class ContentAccess::CImportFile;
1.42 + /**
1.43 + Allows clients to instantiate key stream decoders for short-term key streams in protected broadcasts.
1.44 +
1.45 + This class is initialised with an agent implementation that supports the standard with which the stream is protected.
1.46 + */
1.47 + class CKeyStreamDecoder : public CBase
1.48 + {
1.49 + public:
1.50 + /**
1.51 + Creates a new CKeyStreamDecoder object.
1.52 +
1.53 + Sample code pattern from a media controller for using this interface. (This sample assumes that the stream is protected using
1.54 + IPSec. Similar code pattern can be used for other protection layers.)
1.55 +
1.56 + @code
1.57 + using namespace StreamAccess;
1.58 +
1.59 + // Create protected stream description by using the source and target connection addresses.
1.60 + CIpSecProtectedStreamDesc *ipSecProtectedStreamDec = CIpSecProtectedStreamDesc::NewLC(sourceAddr, targetAddr);
1.61 +
1.62 + // Extract the relevant media field for the key stream
1.63 + ...
1.64 + // Now create the key stream decoder
1.65 + CKeyStreamDecoder *keyStreamDecoder = CKeyStreamDecoder::NewLC(ipSecProtectedStreamDesc, keyStreamSDPDesc, sdpDocument);
1.66 + // If we reached this point, then key stream decoder was initialized correctly, and if the user has rights to
1.67 + // view the stream, it will get decrypted.
1.68 + // If the user doesn't have the rights to view the stream (e.g. no rights for a specific pay-per-view program),
1.69 + // no cryptographic context will be set. In such case, the reason for lack of decryption can be queried via
1.70 + // the GetAttributeL interface.
1.71 + @endcode
1.72 +
1.73 + @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.
1.74 + 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
1.75 + @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
1.76 + several CKeyStreamDecoder objects must be instantiated. If several key streams are available for the same media, then a key stream decoder should be
1.77 + attempted for all of them - depending on the nature of the broadcast, some of these key streams might be optional or not.
1.78 + For example, if SRTP is used for authentication and ISMACryp for encryption then there would be two key streams - both mandatory.
1.79 + On the other hand, if there are two alternative purchase options for the same service, there may be two corresponding key streams.
1.80 + If no key stream decoder can be created, then the media stream cannot be decoded on the device.
1.81 + @param aSdpDoc Description of the Session Description Protocol (SDP) document which contains all defined SDP fields and related values describing a session.
1.82 + 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
1.83 + SDP media field.
1.84 + @return The new CKeyStreamDecoder object.
1.85 +
1.86 + @leave KErrCANoAgent There is no agent on the device which can support the requested key management system.
1.87 + @leave ... One of the system-wide error codes.
1.88 +
1.89 + @capability
1.90 + Only processes with the DRM capability are able to instantiate key stream decoders.
1.91 + If there is prior knowledge of the DRM agent handling this stream, the documentation for that DRM agent should also be consulted.
1.92 + */
1.93 + IMPORT_C static CKeyStreamDecoder* NewL(const CProtectedStreamDesc& aProtectedStreamDesc, const CSdpMediaField& aSdpKeyStream, const CSdpDocument& aSdpDoc);
1.94 +
1.95 + /**
1.96 + @see CKeyStreamDecoder::NewL()
1.97 + */
1.98 + IMPORT_C static CKeyStreamDecoder* NewLC(const CProtectedStreamDesc& aProtectedStreamDesc, const CSdpMediaField& aSdpKeyStream, const CSdpDocument& aSdpDoc);
1.99 +
1.100 + /** Get an attribute for the service/content protection.
1.101 +
1.102 + @param aAttribute The attribute to query, from StreamAccess::TAttribute.
1.103 + @param aValue [out] Used to return the attribute value.
1.104 + @leave KErrCANotSupported if the requested attribute does not exist.
1.105 + @leave Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.106 + other system-wide error codes for any other errors.
1.107 + @capability Requires the DRM capability.
1.108 + @see StreamAccess::TAttribute
1.109 + */
1.110 + IMPORT_C void GetAttributeL(const TAttribute& aAttribute, TBool& aValue) const;
1.111 +
1.112 + /** Get text string attributes or meta-data for the service/content protection.
1.113 +
1.114 + @param aAttribute The attribute to query, from StreamAccess::TStringAttribute.
1.115 + @return A pointer to the value of the attribute. The pointer is put onto the cleanup stack.
1.116 + @leave KErrCANotSupported if the requested attribute does not exist.
1.117 + @leave Otherwise one of the other CAF error codes defined in \c caferr.h or one of the
1.118 + other system-wide error codes for any other errors.
1.119 + @capability Requires the DRM capability.
1.120 + @see StreamAccess::TStringAttribute
1.121 + */
1.122 + IMPORT_C HBufC* GetStringAttributeLC(const TStringAttribute& aAttribute) const;
1.123 +
1.124 + /** Creates a new import session which is used to import the streamed content into a protected file
1.125 + storage for later viewing.
1.126 +
1.127 + A corresponding rights object for post-acquisition protection is delivered automatically to
1.128 + the CAF agent. The returned session has to be closed when the recording has finished.
1.129 +
1.130 + If the agent requires a new output file it will return KErrCANewFileHandleRequired from
1.131 + @see ContentAccess::CImportFile::Write() or @see ContentAccess::CImportFile::WriteComplete().
1.132 + The application using this API should provide the agent with a new file handle using
1.133 + ContentAccess::CImportFile::ContinueWithNewOutputFile().
1.134 +
1.135 + @param aContentMimeType The mime type of the content which is recorded (e.g. video/3gpp).
1.136 + @return A CImportFile object to import the protected streamed content.
1.137 + The newly created object is left on the cleanup stack.
1.138 + @leave KErrCANoAgent No agent supports recording a protected streamed content.
1.139 + @leave KErrCANotSupported if the protection scheme does not have or is not capable of exporting rights info.
1.140 + @leave Otherwise one of the other CAF error codes defined in \c caferr.h or one of the other system-wide
1.141 + error codes for any other errors.
1.142 + @capability Requires the DRM capability.
1.143 + */
1.144 + IMPORT_C ContentAccess::CImportFile* CreateImportSessionLC(const TDesC8& aContentMimeType) const;
1.145 +
1.146 + /** Creates a new import session which is used to import the streamed content into a protected file
1.147 + storage for later viewing.
1.148 +
1.149 + A corresponding rights object for post-acquisition protection is delivered automatically to
1.150 + the CAF agent. The returned session has to be closed when the recording has finished.
1.151 +
1.152 + @param aContentMimeType The mime type of the content which is recorded (e.g. video/3gpp).
1.153 + @param aSuggestedFileName Suggested filename for the CAF agent to use when creating the output file for
1.154 + the content being recorded. Details of the output files produced can be obtained
1.155 + using ContentAccess::CImportFile::OutputFileL().
1.156 + @param aOutputDirectory The preferred location to store the protected streaming content.
1.157 + @return A CImportFile object to import the protected streamed content.
1.158 + The newly created object is left on the cleanup stack.
1.159 + @leave KErrCANoAgent No agent supports recording a protected streamed content.
1.160 + @leave KErrCANotSupported if the protection scheme does not have or is not capable of exporting rights info.
1.161 + @leave Otherwise one of the other CAF error codes defined in \c caferr.h or one of the other system-wide
1.162 + error codes for any other errors.
1.163 + @capability Requires the DRM capability.
1.164 + */
1.165 + IMPORT_C ContentAccess::CImportFile* CreateImportSessionLC(const TDesC8& aContentMimeType, const TDesC& aSuggestedFileName, const TDesC& aOutputDirectory) const;
1.166 +
1.167 + // Destructor
1.168 + ~CKeyStreamDecoder();
1.169 +
1.170 + protected:
1.171 + // Constructor
1.172 + CKeyStreamDecoder();
1.173 +
1.174 + // Second phase constructor
1.175 + void ConstructL(const CProtectedStreamDesc& aProtectedStreamDesc, const CSdpMediaField& aSdpKeyStream, const CSdpDocument& aSdpDoc);
1.176 +
1.177 + private:
1.178 + ContentAccess::CImportFile* DoCreateImportSessionLC(const TDesC8& aContentMimeType, const TDesC& aSuggestedName, const TDesC& aOutputDirectory) const;
1.179 +
1.180 + private:
1.181 + // Pointer to the resolved agent key stream decoder
1.182 + CAgentKeyStreamDecoder* iAgentKeyStreamDecoder;
1.183 +
1.184 + // Handle to the factory of the resolved stream agent is required in order to successfully cleanup
1.185 + // the factory instance during destruction.
1.186 + CStreamAgentFactory *iStreamAgentFactory;
1.187 +
1.188 + // ECOM session key. This is set by REComSession::CreateImplementationL() during construction
1.189 + TUid iEcomKey;
1.190 + };
1.191 + /**
1.192 + The maximum length of a mime type string. Agents should not use mime types and content IDs
1.193 + which is longer than this value.
1.194 + */
1.195 + const TInt KMimeTypesMaxLength = 512;
1.196 +
1.197 + } // namespace StreamAccess
1.198 +#endif // KEYSTREAMDECODER_H