/*

* Copyright (c) 2007 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:      Utility for parsing upnp items

*

*/

#ifndef UPNPITEMUTILITY_H

#define UPNPITEMUTILITY_H

//  INCLUDES

#include <e32base.h>

#include <upnpobject.h>

#include <f32file.h>

// FORWARD DECLARATIONS

class CUpnpItem;

class CUpnpObject;

class CUpnpElement;

class CUpnpAttribute;

// CLASS DECLARATION

/**

* Utility for working with classes CUpnpObject and CUpnpItem.

* The class provides helpers to locating elements and attributes

* within the class, locating the resource and the URI, decoding

* some special elements like dc:date, res@duration etc.

*

* @lib upnpavcontrollerhelper.lib

* @since S60 3.2

*/

class UPnPItemUtility

    {

public: // Business logic methods

    /**

     * Tests if given object is of given class type.

     * Note that in upnp the object classes are organised in open

     * hierarchies, and this method will return true even if the class

     * is unknown, if aObject's class is derived from aClass.

     * see upnpconstantdefs.h for defined class definitions.

     * example:

     * TBool isPlaylist = BelongsToClass( item, KClassPlaylist );

     *

     * @since S60 3.2

     * @param aObject the object whose class is to be tested

     * @param aClass the class (in string form) against which to test

     * @return reference to the res-element

     */

    IMPORT_C static TBool BelongsToClass(

        const CUpnpObject& aObject,

        const TDesC8& aClass );

    /**

     * Extracts all RES elements from an item.

     * An item can include multiple resources, for instance

     * an item may include the same image scaled to multiple

     * resolutions, or a music track may include the track and

     * its CR cover art as thumbnail.

     * example:

     * RUPnPElementsArray array;

     * GetResElements( array );

     *

     * @since S60 3.2

     * @param aItem UPnP item where to extract the res element.

     * @return reference to the res-element

     */

    IMPORT_C static void GetResElements(

        const CUpnpObject& aObject,

        RUPnPElementsArray& aResElementsArray );

    /**

     * Finds the original resource of given item.

     * Note that if item has multiple resource elements,

     * this API will select the original and recommended one to use.

     * Also note that if an item includes a thumbnail or another

     * supporting resource, this can not be used to retrieve it.

     * Example:

     * const TDesC& uri = ResourceFromItemL( item ).Value();

     *

     * @since S60 3.2

     * @param aItem UPnP item where to extract the res element.

     * @return reference to the res-element

     */

    IMPORT_C static const CUpnpElement& ResourceFromItemL(

        const CUpnpItem& aItem );

    /**

     * Finds an element within an object.

     * see upnpconstantdefs.h for element name definitions.

     * example:

     * CUpnpElement* date = FindElementByName( item, KElementDate );

     *

     * @since S60 3.2

     * @param aObject the object where to look for elements

     * @param aName element name

     * @return a pointer to the element, or NULL if not found

     */

    IMPORT_C static  const CUpnpElement* FindElementByName(

        const CUpnpObject& aObject, const TDesC8& aName );

    /**

     * Finds an element within an object.

     * Leaves if not found.

     * see upnpconstantdefs.h for element name definitions.

     * example:

     * TDesC& genre = FindElementByNameL( item, KElementDate ).Value();

     *

     * @since S60 3.2

     * @param aObject the object where to look for elements

     * @param aName element name

     * @return a reference to the element found.

     */

    IMPORT_C static  const CUpnpElement& FindElementByNameL(

        const CUpnpObject& aObject, const TDesC8& aName );

    /**

     * Finds an attribute within an upnp element

     * see upnpconstantdefs.h for element name definitions.

     * example:

     * CUpnpAttribute* s = FindAttributeByName( resElem, KAttributeSize );

     *

     * @since S60 3.2

     * @param aElement the element where to look for attributes

     * @param aName attribute name

     * @return a pointer to the attribute found

     */

    IMPORT_C static const CUpnpAttribute* FindAttributeByName(

        const CUpnpElement& aElement, const TDesC8& aName );

    /**

     * Finds an attribute within an upnp element.

     * Leaves if not found

     * see upnpconstantdefs.h for attribute name definitions.

     * example:

     * TDesC& s = FindAttributeByNameL( resElem, KAttributeSize ).Value();

     *

     * @since S60 3.2

     * @param aElement the element where to look for attributes

     * @param aName attribute name

     * @return a reference to the attribute found

     */

    IMPORT_C static const CUpnpAttribute& FindAttributeByNameL(

        const CUpnpElement& aElement, const TDesC8& aName );

    /**

     * Converts given upnp date string into TTime.

     * example:

     * TTime time = UpnpDateAsTTime( FindElementByNameL(

     *      item, KElementDate ).Value() );

     *

     * @since S60 3.2

     * @param aUpnpDate value from item's dc:date element

     * @param aTime out variable to receive corresponding TTime

     * @return KErrNone if conversion was succesful, otherwise < 0

     *         for error values see TTime::Parse()

     */

    IMPORT_C static TInt UPnPDateAsTTime(

        const TDesC8& aUpnpDate, TTime& aTime );

    /**

     * Converts given upnp duration or position string to a value in

     * milliseconds.

     * Duration was received in res element duration attribute, or

     * in PositionInfo result from renderer.

     * example:

     * TInt duration = UpnpDurationAsMilliseconds( FindAttributeByNameL(

     *      ResourceFromItemL( item ), KAttributeDuration ).Value() );

     *

     * @since S60 3.2

     * @param aDuration duration or position as string

     * @param aMilliseconds out variable to receive the result

     * @return KErrNone if conversion was succesful, otherwise < 0

     */

    IMPORT_C static TInt UPnPDurationAsMilliseconds(

        const TDesC8& aDuration, TInt& aMilliseconds );

private:

    static void UPnPDateAsTTimeL( const TDesC8& aUpnpDate,

        TTime& aTime );

    };

#endif  // UPNPITEMUTILITY_H

// End of File