/*

* 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 <s32strm.h>

#include <mpxcmn.h>

#include <mpxmediabase.h>

//  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<TInt>& 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<TInt> 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<TMPXAttribute> 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<typename T>

     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<typename T>

    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<typename C>

    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<typename C>

    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<typename T>

    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<typename C>

    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<typename C>

    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<T> for

    *  the attribute will return NULL. You MUST be careful to check the

    *  return value of Value<T>. The Value<T> 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<TInt>& 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<typename T>

    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<TMPXAttribute> iAttributes;

    };

#include "mpxmedia.inl"

#endif // CMPXMEDIA_H