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