diff -r 000000000000 -r 7f85d04be362 upnpavcontroller/upnpavcontrollerhelper/inc/upnpitemutility.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/upnpavcontroller/upnpavcontrollerhelper/inc/upnpitemutility.h Thu Dec 17 08:52:00 2009 +0200 @@ -0,0 +1,207 @@ +/* +* 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 +#include +#include + +// 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