diff -r 000000000000 -r a2952bb97e68 mmappfw_plat/mpx_common_api/inc/mpxmedia.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmappfw_plat/mpx_common_api/inc/mpxmedia.h Thu Dec 17 08:55:47 2009 +0200 @@ -0,0 +1,513 @@ +/* +* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "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: Encapsulates media +* +*/ + + + +#ifndef CMPXMEDIA_H +#define CMPXMEDIA_H + +// INCLUDES +#include +#include +#include + +// FORWARD DECLARATIONS + +/** +* Encapsulates arbitrary data. The ID is a unique identifier for the type +* of content contained within this object: there may be several supported IDs. +* Supported IDs provide a means whereby a client who receives a media object +* can request additional media objects from the same source using another of +* the supported IDs. Attributes are referenced by flags which are unique to +* the type of content contained in the object (i.e ID). The media object may +* contain the full range of attribute values or some subset, depending both +* on the attributes requested by the client and the capabilities of the source +* of the data. +* +* @lib mpxcommon.lib +*/ + +class CMPXMedia : public CMPXMediaBase + { +public: + /** + * Two-phased constructor. + * + * @since S60 3.2.3 + * @param aSupportedIds, denotes all possible content that can be provided + * by the source of this media object + * @return new instance of object + */ + IMPORT_C static CMPXMedia* NewL(const TArray& aSupportedIds); + + /** + * Two-phased constructor. + * @since S60 3.2.3 + * @return new instance of object + */ + IMPORT_C static CMPXMedia* NewL(); + + /** + * Two-phased constructor. + * + * @since S60 3.2.3 + * @param aStream create object from stream + * @return new instance of object + */ + IMPORT_C static CMPXMedia* NewL(RReadStream& aStream); + + /** + * Two-phased constructor. Creates new instance of CMPXMedia + * which shares underlying data from aMedia; lifetime of + * data is reference counted, i.e. all CMPXMedia instances which + * reference same data must be deleted before underlying data is deleted. + * + * @since S60 3.2.3 + * @param aMedia create object from media + * @return new instance of object + */ + IMPORT_C static CMPXMedia* NewL(const CMPXMedia& aMedia); + + /** + * Two-phased constructor. Creates object from existing data handle. + * The data handle is used to indentify the data in a media object. + * + * @since S60 3.2.3 + * @param aDataHandle handle to the data + * @return new instance of object + */ + IMPORT_C static CMPXMedia* NewL(TInt aDataHandle); + + /** + * Two-phased constructor. Creates new instance of CMPXMedia + * which duplicates underlying data from aMedia. + * + * @since S60 3.2.3 + * @param aMedia create object from media + * @return new instance of object + */ + IMPORT_C static CMPXMedia* CopyL(const CMPXMedia& aMedia); + + /** + * Destructor. + * + * @since S60 3.2.3 + */ + IMPORT_C ~CMPXMedia(); + + /** + * Assignment operator. + * It copies data handle and increase the reference count of the aMedia only. + * + * @since S60 3.2.3 + * @param aMedia source media + * @return reference to updated object + */ + IMPORT_C CMPXMedia& operator=(const CMPXMedia& aMedia); + + /** + * Gets the total size and the currently used size of the global heap. + * + * @since S60 3.2.3 + * @param aTotal Total size of memory (out parameter) + * @param aUsed Used size of memory (out parameter) + */ + IMPORT_C static void HeapMemoryInfoL( TInt& aTotal, TInt& aUsed ); + + public: + /** + * Possible content IDs that denote the type of content the source of this + * object can supply. + * + * @since S60 3.2.3 + * @return IDs indicating type of content that can be contained within + * this object + */ + IMPORT_C const TArray SupportedIds() const; + + /** + * The attributes provided in this media object. + * + * @since S60 3.2.3 + * @return array of attributes indicating the attributes for the values + * contained in this object + */ + IMPORT_C const TArray Attributes() const; + + /** + * Checks if this object contains the value for a given attribute. + * + * @since S60 3.2.3 + * @param aAttribute the specified attribute + * @return whether supported or not + */ + IMPORT_C TBool IsSupported(const TMPXAttribute& aAttribute) const; + + /** + * The number of attribute values provided in this media object. + * + * @since S60 3.2.3 + * @return count of attribute values in this object + */ + IMPORT_C TInt Count() const; + + /** + * The attribute for a specific index. + * + * @since S60 3.2.3 + * @param aIndex the index from 0 to Count()-1, covering all the values + * provided in this object + * @return the attribute corresponding to the value at the specified index + */ + IMPORT_C const TMPXAttribute& Attribute(TInt aIndex) const; + + /** + * The attributes set for a specific content id. + * + * @since S60 3.2.3 + * @param aContentId content Id + * @return the attributes set corresponding to content id + */ + IMPORT_C TUint AttributesSet(TInt aContentId) const; + + /** + * The index of a given attribute. + * + * @since S60 3.2.3 + * @param aAttribute the specified attribute + * @return the index, or KErrNotFound if not present in this object + */ + IMPORT_C TInt Index(const TMPXAttribute& aAttribute) const; + + /** + * The type of data stored for the index. + * + * @since S60 3.2.3 + * @param aIndex the index whose type of value is queried + * @return the data type at that index + */ + IMPORT_C TMPXAttributeType Type(TInt aIndex) const; + + /** + * The type of data stored for the attribute. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose type of value is queried + * @return the data type of the attribute, + * EMPXTypeUnknown returned if the attribute does not exist + */ + IMPORT_C TMPXAttributeType Type(const TMPXAttribute& aAttribute) const; + + /** + * Clears all the attributes and values. + * + * @since S60 3.2.3 + */ + IMPORT_C void Reset(); + + /** + * Deletes a given attribute and its value; No effect + * if attribute is not present. + * + * @since S60 3.2.3 + * @param aAttribute the attribute to delete + */ + IMPORT_C void Delete(const TMPXAttribute& aAttribute); + + /** + * Deletes a given attribute and its value; No effect + * if attribute is not present. + * + * @since S60 3.2.3 + * @param aIndex the index from 0 to Count()-1 + */ + IMPORT_C void Delete(TInt aIndex); + + /** + * The value for a specific attribute. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is queried + * @return value of the attribute + */ + IMPORT_C const TDesC& ValueText(const TMPXAttribute& aAttribute) const; + + /** + * Add a new attribute value to this object, or modifies existing + * value if already present. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is added/modified + * @param aValue text value to be set + */ + IMPORT_C void SetTextValueL(const TMPXAttribute& aAttribute, + const TDesC& aValue); + + /** + * Merges in the attributes of the provided media. + * + * @since S60 3.2.3 + * @param aMedia Media object with attributes to merge in + */ + IMPORT_C void MergeMediaL( const CMPXMedia& aMedia ); + + /** + * Compares if the specified media's attribute matches this one. + * + * @since S60 3.2.3 + * @param aMedia Media object to match + * @param aAtt Attribute to match + * @return ETrue if matches, else EFalse + */ + IMPORT_C TBool Match( + const CMPXMedia& aMedia, + const TMPXAttribute& aAtt ); + + public: + + /** + * The value for a specific attribute. it may return NULL + * + * This method supports all T types and CMPXMediaBase classes like + * CMPXMedia and CMPXMediaArray. + * + * This method returns NULL (ASSERT happens on UDEB image) for CBase + * objects other than CMPXMedia, CMPXMediaArray. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is queried + * @return value of the attribute, or NULL if not present + * Note: Ownership is not transferred to caller + * @deprecated if an error code is set for the attribue, use method: + * CMPXMedia::ValueTObjectL(const TMPXAttribute& aAttribute), + * CMPXMedia::ValueNoNewLCObjectL(const TMPXAttribute& aAttribute), + * CMPXMedia::ValueCObjectL(const TMPXAttribute& aAttribute). + * + * For CMPXCollectionPath, use method: + * CMPXMedia::ValueCObjectL(const TMPXAttribute& aAttribute). + */ + template + inline T* Value(const TMPXAttribute& aAttribute) const; + + /** + * A copy of the value for a specific attribute. + * If the media attribute does not exist, the default T object will be returned. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is queried + * @return copy of the value of the attribute + */ + template + inline T ValueTObjectL(const TMPXAttribute& aAttribute) const; + + /** + * Copy an object out of media object. + * Note: C++ default contructor of class C must be public. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is queried + * @return new copy object of class C + */ + template + inline C* ValueNoNewLCObjectL(const TMPXAttribute& aAttribute) const; + + /** + * Copy an object out of media object. + * Note: class C must implement the function NewL() and streamable. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is queried + * @return new copy object of class C + */ + template + inline C* ValueCObjectL(const TMPXAttribute& aAttribute) const; + + /** + * Add a new attribute value to this object, or modifies existing + * value if already present. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is added/modified + * @param aValue attribute value of the T object. + */ + template + inline void SetTObjectValueL(const TMPXAttribute& aAttribute, T aValue); + + /** + * Add a new attribute value to this object, or modifies existing + * value if already present. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is added/modified + * @param aValue pointer to the C object + */ + template + inline void SetNoNewLCObjectL(const TMPXAttribute& aAttribute,C* aValue); + + /** + * Add a new attribute value to this object, or modifies existing + * value if already present. + * Uses CTypeObject::NewL( RReadStream& aStream ). + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is added/modified + * @param aValue pointer to the C object + */ + template + inline void SetCObjectValueL(const TMPXAttribute& aAttribute,C* aValue); + + /** + * A representation (handle) of the data stored in this object. + * + * @since S60 3.2.3 + * @return TInt handle to the data + */ + inline TInt Data() const; + + /** + * Set an error code to an attribute. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose error code is setted. + * @param aError error code of the attribute. + * Note: if error code is set for an attribute, call to Value for + * the attribute will return NULL. You MUST be careful to check the + * return value of Value. The Value is deprecated for this reason + * and you should use ValueTObject instead. + */ + IMPORT_C void SetErrorL(const TMPXAttribute& aAttribute, TInt aError); + + /** + * Get the error code of an attribute. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose error code is retrieved. + * @return TInt error code of the attribute, or KErrNone if no error code is set. + */ + IMPORT_C TInt Error(const TMPXAttribute& aAttribute) const; + +public: + + /** + * Externalize media object. + * + * @since S60 3.2.3 + * @param aStream write stream + */ + IMPORT_C void ExternalizeL(RWriteStream& aStream) const; + + /** + * Internalize media object. + * + * @since S60 3.2.3 + * @param aStream read stream + */ + IMPORT_C void InternalizeL(RReadStream& aStream); + +private: + + /** + * 2nd phase contructor. + * + * @since S60 3.2.3 + * @param aSupportedIds support content ids + */ + void ConstructL(const TArray& aSupportedIds); + + /** + * 2nd phase contructor. + * + * @since S60 3.2.3 + * @param aStream read stream + */ + void ConstructL(RReadStream& aStream); + +private: + /** + * Set data. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is queried + * @param aValue the value of the media attribute + * @param aType object type of the media attribute + * + */ + IMPORT_C void SetValueL(const TMPXAttribute& aAttribute, + const TDesC8& aValue, + TMPXAttributeType aType); + + /** + * The value for a specific attribute. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is queried + * @return value of the attribute, or NULL if not present + * Note: ownerhip of returned pointer is not transferred. + */ + IMPORT_C TAny* ValuePtr(const TMPXAttribute& aAttribute) const; + + + /** + * Get the binary value for a specific attribute. + * + * @since S60 3.2.3 + * @param aAttribute the attribute whose value is queried + * @return type of the attribute or EMPXTypeUnknown + * if not present + */ + IMPORT_C TMPXAttributeType GetValue(const TMPXAttribute& aAttribute, TDes8& aValue) const; + +private: + /** + * Reconstructs local attribute array. + * + * @since S60 3.2.3 + */ + void RefreshAttributes(); + + /** + * Frees all local data. + * + * @since S60 3.2.3 + */ + void ResetLocal(); + + /** + * Copy an object out of a descriptor buffer. + * Note: Cbased class must implement the function NewL(). + * + * @since S60 3.2.3 + * @return new copy object of class T + */ + template + inline T* ValueL(const TDesC8& aData) const; + + /** + * Copy an object out of media object. + * + * @since S60 3.2.3 + * @return pointer to new copy of object, ownership transferred + */ + TAny* ValueCObjectL(const TDesC8& aData) const; + +private: + RArray iAttributes; + }; + +#include "mpxmedia.inl" + +#endif // CMPXMEDIA_H